환경

환경 (Environments)

Environments를 사용하면 프로덕션, 스테이징, 개발 같은 서로 다른 컨텍스트의 trace, observation, score를 조직화할 수 있어요. 같은 프로젝트를 쓰면서 개발·프로덕션 데이터를 분리하고, 환경별로 데이터를 필터·분석하며, 여러 환경에서 데이터셋과 프롬프트를 재사용할 수 있어요.

출처: 문서

본문

Environments를 사용하면 프로덕션, 스테이징, 개발 같은 서로 다른 컨텍스트의 trace, observation, score를 조직화할 수 있어요. 이렇게 하면:

• 같은 프로젝트를 쓰면서 개발과 프로덕션 데이터를 분리할 수 있어요.
• 환경별로 데이터를 필터링하고 분석할 수 있어요.
• 여러 환경에서 데이터셋과 프롬프트를 재사용할 수 있어요.

필터링 (Filtering)

Langfuse UI에서 내비게이션 바의 environment 필터로 이벤트를 환경별로 필터링할 수 있어요. 이 필터는 Langfuse의 모든 뷰에 적용돼요.

API에서 환경별 필터링 방법은 API Reference를 참고하세요.

환경 관리 (Managing Environments)

환경은 특정 environment 값으로 데이터가 처음 수집될 때 생성되며 영속돼요. 현재 UI에서는 삭제하거나 이름을 바꿀 수 없어요.

여러 환경을 프로젝트와 단계에 걸쳐 구조화·분리·작업하는 지침은 FAQ: Managing different environments를 참고하세요.

환경 구성 (Configure environments)

LANGFUSE_TRACING_ENVIRONMENT 환경 변수를 설정하거나(권장), 클라이언트 초기화의 environment 파라미터로 환경을 구성할 수 있어요. 둘 다 지정되면 초기화 파라미터가 우선해요. 아무것도 지정하지 않으면 기본 환경은 default예요.

Python SDK에서는 특정 trace 범위에 대해 propagate_attributes(environment="...")로 환경을 설정할 수도 있어요. 이는 환경이 서비스 프로세스 자체가 아니라 들어오는 요청에 속할 때 유용해요. 예를 들어 공유 LLM 프록시 하나가 개발, 스테이징, QA, 프로덕션의 요청을 처리하는 경우죠. as_baggage=True를 사용하면 그 환경을 서비스 경계를 넘어 전파할 수 있어요.

이름 제약 (Naming constraints)

환경은 ^(?!langfuse)[a-z0-9-_]+$ 정규식 패턴을 따르는 문자열이어야 하며 최대 40자예요.

즉:

• "langfuse"로 시작할 수 없어요.
• 소문자, 숫자, 하이픈, 밑줄만 포함할 수 있어요.

데이터 모델 (Data Model)

환경 속성은 Langfuse의 모든 이벤트에서 사용할 수 있어요: Traces, Observations, Scores, Sessions.

Python SDK — 데이터 모델 상세:

from langfuse import get_client, observe, propagate_attributes
import os

# Set the environment variable
# Alternatively, set via .env file and load via dotenv
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"

# Get the client (will use environment variable)
langfuse = get_client()

# All operations will now be associated with the "production" environment
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Your code here
    pass

@observe
def main():
    return "Hello"

main()

# For request-scoped environments, propagate the environment explicitly.
# This maps to the first-class langfuse.environment field.
with langfuse.start_as_current_observation(as_type="span", name="proxy-request"):
    with propagate_attributes(environment="staging"):
        # All child observations created here are associated with staging.
        pass

JS/TS SDK

환경 변수로 Langfuse 환경 설정:

export LANGFUSE_TRACING_ENVIRONMENT=production

OpenTelemetry

OpenTelemetry를 사용할 때 다음 속성 중 하나로 환경을 설정할 수 있어요:

• langfuse.environment
• deployment.environment.name
• deployment.environment

환경 속성을 전역으로 설정하려면 리소스 속성을 사용할 수 있어요: os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "langfuse.environment=staging".

span 단위로 환경을 설정하려면:

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_observation("my-operation") as span:
    # Set environment using Langfuse-specific attribute
    span.set_attribute("langfuse.environment", "staging")

    # Or using OpenTelemetry convention
    span.set_attribute("deployment.environment.name", "staging")

Python SDK 사용 시 클라이언트 초기화에 제공된 환경은 사용 중인 Langfuse 유지보수 통합과 무관하게 모든 이벤트 입력·출력에 적용돼요. 자세한 내용은 Python SDK 탭을 참고하세요.

OpenAI (Python)

from langfuse import Langfuse
from langfuse.openai import openai

# Either set the environment variable or configure the Langfuse client
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"

langfuse = Langfuse(environment="production")

# the integration will use the instantiated client under the hood
completion = openai.chat.completions.create(
  model="gpt-3.5-turbo",
  messages=[
    {"role": "system", "content": "You are a calculator."},
    {"role": "user", "content": "1 + 1 = "}],
)

OpenAI (JS/TS) — .env:

LANGFUSE_TRACING_ENVIRONMENT=production

import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";

const openai = observeOpenAI(new OpenAI());

OpenAI Integration (JS/TS)에서 자세한 내용을 확인하세요.

Python SDK 사용 시 클라이언트 초기화에 제공된 환경은 사용 중인 Langfuse 유지보수 통합과 무관하게 모든 이벤트 입력·출력에 적용돼요.

Langchain (Python)

from langfuse.langchain import CallbackHandler

# Set the environment via environment variable before initializing the client
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"
handler = CallbackHandler()

Python SDK 탭에서 자세한 내용을 확인하세요.

Langchain (JS/TS)

환경은 LangfuseSpanProcessor에서 구성돼요(또는 LANGFUSE_TRACING_ENVIRONMENT 환경 변수로) — CallbackHandler가 만든 LangChain span이 자동으로 이를 통과해요:

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { CallbackHandler } from "@langfuse/langchain";

const sdk = new NodeSDK({
  spanProcessors: [
    new LangfuseSpanProcessor({
      environment: "production",
    }),
  ],
});
sdk.start();

const handler = new CallbackHandler();

Vercel AI SDK (JS/TS) — instrumentation.ts:

import { registerOTel } from "@vercel/otel";
import { LangfuseSpanProcessor } from "@langfuse/otel";

export function register() {
  registerOTel({
    serviceName: "langfuse-vercel-ai-nextjs-example",
    spanProcessors: [new LangfuseSpanProcessor({ environment: "production" })],
  });
}

모범 사례 (Best Practices)

1. 일관된 환경 이름: 필터링과 분석을 쉽게 하기 위해 애플리케이션 전체에서 일관된 환경 이름을 사용하세요.
2. 환경별 분석: 서로 다른 배포 단계에서 메트릭을 분석·비교하는 데 환경을 사용하세요.
3. 테스트: 프로덕션 데이터를 오염시키지 않도록 테스트에 별도의 환경을 사용하세요.

GitHub Discussions

더 알아보기 (Learn more)

• 출처 문서: 환경 (Environments)