트레이스에 메타데이터 추가

트레이스에 메타데이터 추가 (Add Metadata to Traces)

트레이스에 추가 정보를 담은 메타데이터를 붙이는 방법을 다루는 페이지예요. 이 정보는 관측소에서 트레이스를 필터링·그룹화·분석하는 데 쓰여요. 예를 들어 앱 버전, 모델, 리트리버가 적중한 지식 베이스별로 트레이스를 비교할 수 있죠.

출처: 문서

본문

개요 (Overview)

Confident AI에서는 트레이스·스팬·스레드에 추가 메타데이터를 붙일 수 있어요. 이 정보는 관측소에서 트레이스를 필터링·그룹화·분석하는 데 쓰여요 — 예를 들어 앱 버전, 모델, 리트리버가 적중한 지식 베이스로 트레이스를 비교할 수 있죠.

이 패턴은 자동 계측된 통합에서도 동작해요. 트레이스 컨텍스트는 래퍼 스팬을 만들지 않으면서 통합이 만든 트레이스에 메타데이터를 추가해요.

트레이스에 메타데이터 추가 (Add Metadata to Traces)

작업 주위에 트레이스 컨텍스트를 열고, 키가 문자열이고 값이 어떤 JSON 직렬화 가능한 타입인 메타데이터 객체를 제공해요:

Python

from langchain_openai import ChatOpenAI
from confident_trace import init, trace_context

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

def llm_app(query: str):
    with trace_context(
        metadata={
            "app_version": "1.2.3",
            "knowledge_base": "support-v2",
        }
    ):
        return model.invoke(query)

TypeScript

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

init();

const llmApp = (query: string) =>
    traceContext(
        {
            metadata: {
                app_version: "1.2.3",
                knowledge_base: "support-v2",
            },
        },
        () => generateText({ model: openai("gpt-4o"), prompt: query }),
    );

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

메타데이터 객체는 병합되지 않아요. 트레이스 컨텍스트는 완전한 객체를 기본값으로 공급하고, 트레이스에 이미 설정된 메타데이터를 덮어쓰지 않아요. 필요한 모든 트레이스 메타데이터를 하나의 객체로 모으세요.

전체 트레이스 컨텍스트 동작은 Update Trace Properties에서 볼 수 있어요.

스팬에 메타데이터 추가 (Add Metadata to Spans)

직접 만든 스팬의 경우, 그 스팬이 활성인 동안 메타데이터를 업데이트해요:

Python

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

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

@span(type="agent", name="Support Request")
def llm_app(query: str):
    response = model.invoke(query)
    update_span(metadata={"app_version": "1.2.3"})
    return response

TypeScript

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

init();

const llmApp = span(
  { name: "Support Request", type: "agent" },
  async (query: string) => {
    const response = await generateText({
      model: openai("gpt-4o"),
      prompt: query,
    });
    updateSpan({ metadata: { app_version: "1.2.3" } });
    return response;
  },
);

스팬 업데이트 헬퍼는 활성 스팬을 요구하고, 다시 호출하면 전체 메타데이터 객체를 대체해요. 스팬 레벨 메타데이터에만 필요하고, 트레이스 레벨 메타데이터에는 트레이스 컨텍스트를 사용해요.

메타데이터 값은 나머지 트레이스 데이터와 같은 콘텐츠 컨트롤(content controls)을 받으므로, init()에서 구성한 삭제 규칙과 크기 제한이 여기에도 적용돼요.

스레드 레벨 메타데이터 (Thread-Level Metadata)

스레드에도 메타데이터를 붙일 수 있어요 — 프로덕션 대화를 DVA 버전, 클라이언트, 에이전트 ID 같은 속성으로 태깅하는 데 유용하죠. update_trace에 thread 객체를 넘기는 방법은 Set Thread Fields에서 볼 수 있어요.

다음 단계 (Next Steps)

Tags

단순히 트레이스를 그룹화·필터링해야 할 때는 간단한 문자열 라벨을 사용해요.

Threads

트레이스를 대화로 묶고 전체 스레드에 메타데이터를 붙여요.

더 알아보기

• Add Tags to Traces — 트레이스에 간단한 문자열 라벨을 추가해요.
• Set Input/Output — 트레이스·스팬의 입력과 출력을 제어해요.