트레이스를 프로젝트로 보내기

트레이스를 프로젝트로 보내기 (Send Traces to Projects)

Confident AI에서 트레이스를 서로 다른 프로젝트로 보내는 방법을 다루는 페이지예요. 런타임에 프로젝트 API 키를 선택하면 각 트레이스가 어느 프로젝트로 갈지를 지정할 수 있어요. 멀티테넌트 SaaS에서 테넌트별로 프로젝트를 분리하거나 특정 기능을 위한 별도 프로젝트를 만들 때 유용하답니다.

출처: 문서

본문

개요 (Overview)

런타임에 프로젝트 API 키를 선택해서 각 트레이스가 보내질 프로젝트를 지정할 수 있어요. 같은 LLM 애플리케이션 안에서 트레이스를 다른 프로젝트로 분리해야 할 때 특히 유용해요 — 예를 들어 멀티테넌트 SaaS에서 테넌트당 하나의 프로젝트, 또는 특정 기능을 위한 별도 프로젝트 같은 경우죠.

Confident API key는 프로젝트마다 고유하고, Confident AI의 프로젝트 설정에서 찾을 수 있어요.

기본 프로젝트 구성 (Configure the Default Project)

다르게 지정하지 않으면 모든 트레이스는 기본 프로젝트로 가요. 기본값은 시작 시 CONFIDENT_API_KEY 환경 변수로 설정하거나 init()에 api_key / apiKey를 전달해서 한 번 설정해요:

export CONFIDENT_API_KEY="<your-default-project-key>"

init()은 프로세스가 시작될 때 한 번만 호출하세요 — 요청마다 호출하지 마세요. 서로 다른 요청을 서로 다른 프로젝트로 보내려면 단일 전역 런타임을 유지하고 아래의 요청 스코프를 사용해요.

트레이스를 프로젝트로 라우팅 (Route Traces to Projects)

특정 요청의 트레이스를 다른 곳으로 보내려면, 추적된 작업을 그 프로젝트에 도착시키고 싶은 API 키를 가진 프로젝트 스코프(project scope)로 감싸면 돼요. 스코프 안에서 추적된 모든 것 — 자동 계측된 LLM 호출 포함 — 이 그 프로젝트로 내보내져요.

이 기능은 자동 계측된 통합에서도 동작해요. 프로젝트 컨텍스트는 래퍼 스팬을 만들지 않으면서 그 안에서 시작된 모든 트레이스를 라우팅해요.

Python

import os
from langchain_openai import ChatOpenAI
from confident_trace import init, project_context

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

def handle_request(query: str):
    if query == "Write me a poem.":
        key = os.environ["POETRY_PROJECT_KEY"]
    else:
        key = os.environ["OTHER_PROJECT_KEY"]
    with project_context(api_key=key):
        return model.invoke(query)

project_context(...)은 비동기 코드에서 async with와도 동작해요.

TypeScript

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

init();

function handleRequest(query: string) {
    const apiKey = query === "Write me a poem."
        ? process.env.POETRY_PROJECT_KEY!
        : process.env.OTHER_PROJECT_KEY!;
    return projectContext({ apiKey }, () =>
        generateText({ model: openai("gpt-4o"), prompt: query }),
    );
}

Vercel AI SDK 호출이 계측되어 요청의 나머지와 함께 라우팅되도록 Node preload로 진입점을 실행하세요.

실제 앱에서 이 키는 보통 요청 내용이 아니라 인증된 고객의 서버 측 구성에서 나와요. 기억할 몇 가지가 있어요:

  • 추적된 작업이 시작되기 전에 스코프를 여세요. 활성 추적 스팬 안에서 프로젝트를 바꾸는 것은 거부돼요 — 요청 핸들러에서 프로젝트를 선택한 다음 계측된 코드를 호출하세요.
  • 스코프는 요청 로컬이에요. 동시 요청은 각자의 목적지를 유지하고, 스코프가 끝나면 호출자의 목적지가 복원돼요. 스코프 안에서 만들어진 스팬은 라우팅된 프로젝트에 남아요.
  • 조용한 폴백은 없어요. 프로젝트 라우팅이 실패하면 트레이스가 기본 프로젝트로 조용히 보내지지 않아요. 그래서 잘못 구성된 키가 한 고객의 트레이스를 다른 프로젝트로 새지 않게 해요.
  • 커스텀 스팬이 필요 없어요. 프로바이더 호출이 자동 계측된다면, 프로젝트 컨텍스트로 감싸는 것만으로 라우팅할 수 있어요.

프로젝트 키는 서버 측에 유지돼요 — 내보내기를 고르는 데만 쓰이고 스팬 속성이나 전파 컨텍스트에는 절대 나타나지 않아요. 각 목적지는 자체 배치 내보내기를 갖고, flush() / shutdown()이 전부를 다루므로 프로젝트별로 flush할 필요가 없어요.

다음 단계 (Next Steps)

Multi-Tenant Project Isolation

각 고객의 트레이스를 자기 프로젝트로 라우팅하는 전체 워크스루예요.

Environment

단일 프로젝트 안에서 프로덕션·스테이징·개발 트래픽을 분리해요.

더 알아보기