트레이스에서 사용자 추적

트레이스에서 사용자 추적 (Track Users in Traces)

관측성을 위해 트레이스에 사용자 정보를 추적하는 방법을 다루는 페이지예요. 트레이스에 사용자 ID를 설정하면 LLM 앱과의 사용자 상호작용을 추적할 수 있어요. 각 사용자가 얼마나 많은 토큰 비용을 일으키는지, 누가 앱과 가장 많이 상호작용했는지 등을 알 수 있죠.

출처: 문서

본문

개요 (Overview)

트레이스에 사용자 ID를 설정해서 LLM 앱과의 사용자 상호작용을 추적할 수 있어요. 이를 통해 각 사용자가 얼마나 많은 토큰 비용을 일으키는지, 누가 LLM 앱과 가장 많이 상호작용했는지 등을 추적할 수 있어요.

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

런타임에서 사용자 설정 (Set Users at Runtime)

Python

from langchain_openai import ChatOpenAI
from confident_trace import init, trace_context

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

def llm_app(query: str, user_id: str):
    with trace_context(user_id=user_id):
        return model.invoke(query)

user_id는 애플리케이션의 안정적인 사용자 또는 계정 멤버 ID가 될 수도 있고, 심지어 이메일 주소일 수도 있어요. 모든 것이 UI에서 보이고 검색 가능해요.

TypeScript

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

init();

const llmApp = (query: string, userId: string) =>
    traceContext({ userId }, () =>
        generateText({ model: openai("gpt-4o"), prompt: query }),
    );

userId는 애플리케이션의 안정적인 사용자 또는 계정 멤버 ID가 될 수도 있고, 심지어 이메일 주소일 수도 있어요. 모든 것이 UI에서 보이고 검색 가능해요.

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

트레이스 컨텍스트는 그 안에서 시작된 트레이스에 기본값을 공급해요. 트레이스에 이미 사용자 ID가 있다면 기존 값이 이겨요. 전체 동작은 Update Trace Properties에서 볼 수 있어요.

사용자 필드 설정 (Set User Fields)

관측소에서 트레이스를 쉽게 식별하도록 사용자에 표시 이름을 붙일 수 있어요. user 객체를 넘기면 ID와 이름을 함께 설정할 수 있어요:

Python

with trace_context(user={"id": "user-42", "name": "Marta"}):
    return model.invoke(query)

TypeScript

return traceContext(
  { user: { id: "user-42", name: "Marta" } },
  () => model.invoke(query),
);

사용자를 식별하는 방법은 두 가지 중 하나를 골라 쓰면 돼요:

ID만 필요할 때는 user_id / userId를 넘겨요.
표시 이름도 함께 설정하고 싶다면 user 객체를 넘겨요. 이 객체는 id를 포함하고 name도 넣을 수 있어요.

같은 두 옵션은 turn(), 트레이스 컨텍스트, 그리고 트레이스 업데이트 헬퍼에서도 쓸 수 있어요. Python은 span()을 만들 때도 이 값들을 받아들이고, TypeScript의 span() 또는 withSpan() 콜백 안에서는 updateTrace()를 호출하면 돼요.

다음 단계 (Next Steps)

Threads

멀티턴 표시와 평가를 위해 사용자의 트레이스를 대화로 묶어요.

Customers

같은 계정·조직·테넌트에 속한 사용자들을 그룹화해요.

더 알아보기

Customers — 고객 단위로 활동·품질·비용을 비교해요.
Thread Traces — 트레이스를 대화로 묶어 멀티턴을 평가해요.