트레이스 환경 설정

트레이스 환경 설정 (Set Trace Environments)

트레이싱할 때 환경을 지정해서 디버깅을 더 쉽게 하는 방법을 다루는 페이지예요. "development", "staging", "production", "testing" 같은 환경별로 트레이스를 분리하면 Observatory를 필터링하고 원하는 배포 환경에 맞춰 평가 범위를 정할 수 있어요.

출처: 문서

본문

개요 (Overview)

환경(environment) 기능을 쓰면 트레이스가 어느 환경에서 왔는지 지정할 수 있어요. "development", "staging", "production", "testing" 같은 서로 다른 환경의 트레이스를 분리할 때 유용해서, 관심 있는 배포로 Observatory를 필터링하고 평가 범위를 좁힐 수 있어요.

컴포넌트 단위 평가(component-level evals)의 트레이스는 자동으로 "testing" 환경으로 분류돼요.

환경 구성 (Configure Environment)

대부분의 애플리케이션은 프로세스당 정확히 하나의 환경에서 실행되므로, CONFIDENT_ENVIRONMENT 환경 변수로 한 번만 설정하는 게 가장 쉬워요 — 그 프로세스의 모든 트레이스가 그 값을 가지게 돼요:

export CONFIDENT_ENVIRONMENT="staging"

또는 init()을 호출할 때 코드에서 직접 환경을 설정할 수도 있어요:

Python

from openai import OpenAI
from confident_trace import init, shutdown

init(environment="production")
client = OpenAI()

def llm_app(query: str):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": query}]
    ).choices[0].message.content

try:
    llm_app("Write me a poem.")
finally:
    shutdown()

TypeScript

import OpenAI from "openai";
import { init } from "confident-trace";

const runtime = init({ environment: "production" });
const openai = new OpenAI();

const llmApp = async (query: string) => {
    const result = await openai.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: query }],
    });
    return result.choices[0].message.content;
};

try {
    await llmApp("Write me a poem.");
} finally {
    await runtime.shutdown();
}

OpenAI 호출이 계측되도록 Node preload로 진입점을 실행하세요.

environment는 보통 "production", "staging", 또는 "development"이고, 트레이스가 어디에서 왔는지 식별하는 데 도움을 줘요. 명시적인 init() 인자가 환경 변수보다 우선해요 — 전체 우선순위 순서는 configure init()에서 볼 수 있어요.

이는 deployment.environment.name 같은 OpenTelemetry 리소스 속성과는 별개예요. Confident AI는 confident-trace로 설정한 환경을 읽으므로, OTEL 리소스가 이미 배포 이름을 담고 있더라도 여기에서도 설정해 주세요.

트레이스별 환경 덮어쓰기 (Override Environment Per Trace)

가끔 하나의 프로세스가 둘 이상의 환경을 서비스하기도 해요 — 프로덕션 트래픽 일부를 처리하는 카나리(canary), 또는 스테이징·프로덕션 작업을 함께 돌리는 공유 워커 같은 경우죠. 시작 기본값은 그대로 두고, 요청별 옵션 두 가지 중 하나를 고르면 돼요:

  • 활성 트레이스의 환경을 명시적으로 변경한다.
  • 스코프 안에서 시작되는 트레이스에 환경 기본값을 제공한다.

활성 트레이스 변경 (Change an Active Trace)

요청에 활성 스팬이 이미 있다면, 트레이스 업데이트 헬퍼를 써서 그 트레이스의 환경을 명시적으로 변경할 수 있어요:

Python

from langchain_openai import ChatOpenAI
from confident_trace import init, span, update_trace

init(environment="production")
model = ChatOpenAI(model="gpt-4o")

@span(type="agent", name="LLM App")
def llm_app(query: str, is_canary: bool):
    if is_canary:
        update_trace(environment="staging")
    return model.invoke(query)

TypeScript

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { init, span, updateTrace } from "confident-trace";

init({ environment: "production" });

const llmApp = span(
    { name: "LLM App", type: "agent" },
    async (query: string, isCanary: boolean) => {
        if (isCanary) updateTrace({ environment: "staging" });
        return generateText({
            model: openai("gpt-4o"),
            prompt: query,
        });
    },
);

Vercel AI SDK 호출이 계측되도록 Node preload로 진입점을 실행하세요.

명시적 값은 그 활성 트레이스에 대해서만 시작 기본값을 대체해요. 다른 모든 트레이스는 init() / CONFIDENT_ENVIRONMENT의 환경을 그대로 유지해요.

스코프 안 작업의 기본값 제공 (Supply Defaults for Work in a Scope)

스코프 안에서 시작된 트레이스의 경우, trace-context 값이 init()에 전달된 환경을 덮어쓰고, 그 init() 값이 다시 CONFIDENT_ENVIRONMENT를 덮어써요. 스코프는 두 전역 설정을 바꾸지 않아요. 단지 스코프 안 작업에 적용되는 환경만 바꿀 뿐이죠.

Python

from langchain_openai import ChatOpenAI
from confident_trace import init, trace_context

init(environment="production")
model = ChatOpenAI(model="gpt-4o")

def llm_app(query: str, is_canary: bool):
    env = "staging" if is_canary else "production"
    with trace_context(environment=env):
        return model.invoke(query)

TypeScript

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { init, traceContext } from "confident-trace";

init({ environment: "production" });

const llmApp = async (query: string, isCanary: boolean) => {
    const environment = isCanary ? "staging" : "production";
    return traceContext({ environment }, () =>
        generateText({ model: openai("gpt-4o"), prompt: query }),
    );
};

Vercel AI SDK 호출이 계측되도록 Node preload로 진입점을 실행하세요.

트레이스 컨텍스트는 트레이스도 스팬도 만들지 않아요. 단지 그 스코프 안에서 시작되는 트레이스에 환경을 공급할 뿐이죠. 반면 트레이스 업데이트 헬퍼는 활성 스팬을 요구하고 그 트레이스의 환경을 명시적으로 대체해요. 전체 차이는 Update Trace Properties에서 볼 수 있어요.

다음 단계 (Next Steps)

Configure init()

init()이 받는 모든 설정 — API 키, 엔드포인트, 샘플 비율, 환경 — 과 환경 변수·인자가 어떻게 상호작용하는지 볼 수 있어요.

Sampling

스테이징을 100%로 유지하면서 프로덕션 트레이스의 일부만 내보내요.

더 알아보기