Confident AI 관측성

Confident AI 는 개발·프로덕션에서 신뢰할 수 있는 AI 애플리케이션을 구축하는 팀을 위한 LLM 관측성·평가 플랫폼이에요.

confident-trace 는 Confident AI의 OpenTelemetry 네이티브 트레이싱 SDK로, 호출을 바꾸지 않고도 AI SDK 애플리케이션을 추적해요 — 모든 generateText와 streamText 호출이 에이전트·단계·모델·도구 스팬과 함께 Observatory에 트레이스로 나타나므로, 앱이 어떤 도구를 선택했는지, 각 모델 호출 비용이 얼마인지 확인하고 결과에 대한 평가를 실행할 수 있어요.

Confident AI는 AI SDK와 통합해 다음을 제공해요:

전체 에이전트·단계·모델·도구 계층이 담긴 트레이스
모든 모델 호출의 토큰 사용량과 비용
대화의 턴을 하나의 단위로 묶는 스레드
수집되는 대로 트레이스를 점수화하는 온라인 평가

출처: 문서

본문

설정 (Setup)

트레이싱에는 Node.js 22 이상과 AI SDK >=7.0.93 <8이 필요해요.

1. confident-trace 설치

npm install confident-trace @ai-sdk/otel

2. API 키 설정

Confident AI에 가입하거나 로그인해 프로젝트 API 키를 받은 뒤, 환경 변수로 설정하세요:

CONFIDENT_API_KEY="YOUR-PROJECT-API-KEY"

참고: EU 지역 사용자는 CONFIDENT_OTEL_ENDPOINT="https://eu.otel.confident-ai.com/v1/traces"를 설정하세요.

3. 텔레메트리 통합 등록

createVercelAITracer() 함수는 AI SDK 스팬을 Confident AI의 스팬 유형에 매핑하는 트레이서를 반환해요. 이 트레이서를 OpenTelemetry에 전달하고, AI SDK 호출 전에 애플리케이션 시작 시 한 번 등록하세요. init()은 스팬을 프로젝트로 보내는 익스포터를 설정해요:

import { registerTelemetry } from 'ai';
import { OpenTelemetry } from '@ai-sdk/otel';
import { init } from 'confident-trace';
import { createVercelAITracer } from 'confident-trace/vercel-ai';

export function register() {
  init();
  registerTelemetry(new OpenTelemetry({ tracer: createVercelAITracer() }));
}

Next.js에서는 프로젝트 루트의 instrumentation.ts에 넣으면 Next.js가 register()를 호출해 줘요. Next.js가 없는 Node.js 애플리케이션에서는 진입 파일 최상위에서 같은 두 줄을 실행하세요:

import { generateText, registerTelemetry } from 'ai';
import { openai } from '@ai-sdk/openai';
import { OpenTelemetry } from '@ai-sdk/otel';
import { init } from 'confident-trace';
import { createVercelAITracer } from 'confident-trace/vercel-ai';

const runtime = init();
registerTelemetry(new OpenTelemetry({ tracer: createVercelAITracer() }));

try {
  const { text } = await generateText({
    model: openai('gpt-6-astra'),
    prompt: 'How do you make the best coffee?',
  });
  console.log(text);
} finally {
  await runtime.shutdown();
}

AI SDK 호출은 그대로 유지돼요. 모든 스팬은 Vercel AI SDK 통합 라벨을 담고, 호출 시 활성화된 스팬 아래 중첩되며 다음을 캡처해요:

에이전트·단계 스팬 — 전체 generateText 또는 streamText 호출에 대한 스팬 하나와, 다단계 실행에서 단계별 스팬 하나.
모델 호출 — 모델 이름, 토큰 사용량, 종료 이유, 정규화된 입출력 메시지(모델이 요청한 도구 호출 포함)가 담긴 LLM 스팬.
도구 호출 — 도구 이름·입력·결과가 담긴 도구 스팬으로, 이를 실행한 단계 아래 중첩.
콘텐츠 — 프롬프트와 응답 텍스트, 기본적으로 크기 제한 없이 캡처되며(직접 설정하지 않는 한) 콘텐츠 정책이 적용돼요.

참고: 추론(reasoning)·바이너리 콘텐츠 부분은 표시되지만 내보내지지 않고, 원시 요청 헤더, 임의의 SDK 메타데이터, 예외 메시지는 제외돼요. 임베딩, 리랭킹, 이미지·오디오 API는 이 통합의 범위 밖이에요.

참고: 한 번 초기화하고 한 번 종료하세요. 장기 실행 서버에서는 시작 시 init()을 호출하고, 진행 중인 요청·스트림이 끝난 뒤 정상 종료(graceful shutdown) 중에 runtime.shutdown()을 호출하세요 — 절대 요청마다 호출하지 마세요. 서버리스 함수에서는 핸들러 끝에서 스트림이 끝난 후 runtime.flush()를 호출해, 함수가 동결되기 전에 스팬이 내보내지도록 하세요.

고급 기능 (Advanced Features)

온라인 평가 (Online Evals)

Confident AI의 워크플로 페이지에서 들어오는 트레이스에 무엇을 할지 구성할 수 있어요.

Confident AI workflows page

구성할 수 있는 워크플로는 다음과 같아요:

평가 규칙 (Evaluation rules) — 들어오는 트레이스를 메트릭 컬렉션으로 평가.
분류기 (Classifiers) — 이슈, 감정, 정의한 어떤 차원으로든 트레이스에 라벨을 붙여 나중에 그룹화하거나 필터링할 수 있게 함.
큐 수집 (Queue ingestion) — 프로덕션 트레이스를 주석 큐로 라우팅해 내부 검토 팀이 수동으로 주석을 달게 함.
데이터셋 수집 (Dataset ingestion) — 프로덕션 트레이스를 데이터셋으로 수집해 테스트 케이스로 재사용하고 결과를 반복하며 시간에 따라 개선.

트레이스, 스팬, 스레드 같은 서로 다른 데이터 모델에 대해 필요에 따라 개별적으로 커스텀 워크플로를 만들 수 있어요.

컴포넌트나 트레이스를 수동으로 평가하려면 updateTrace로 메트릭 컬렉션을 전달하세요 — 온라인 평가 참고.

트레이스 속성 (Trace Properties)

트레이스 컨텍스트를 사용해 호출이 시작되기 전에 아는 속성을 첨부해요. 추가 스팬을 만들지 않고, generateText()가 시작한 트레이스가 전달한 모든 것을 상속받아요:

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { traceContext } from 'confident-trace';

const { text } = await traceContext(
  {
    tags: ['support'],
    metadata: { release: '2026-09' },
    userId: 'user-456',
    environment: 'production',
  },
  () =>
    generateText({
      model: openai('gpt-6-astra'),
      prompt: 'How do you make the best coffee?',
    }),
);

트레이스를 스레드로 묶기 (Group Traces Into Threads)

confident-trace는 두 개의 연속 AI SDK 호출을 하나의 턴으로 묶는 turn() 메서드를 제공해요. 이후 턴에서 같은 스레드 ID를 재사용하면 Confident AI에서 보고 평가할 수 있는 하나의 스레드로 묶여요:

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { turn, updateTrace } from 'confident-trace';

async function chat(prompt: string, threadId: string) {
  return turn({ name: 'chat', threadId }, async () => {
    const { text } = await generateText({
      model: openai('gpt-6-astra'),
      prompt,
    });
    updateTrace({ input: prompt, output: text });
    return text;
  });
}

문제 해결 (Troubleshooting)

트레이스가 전혀 없음: 첫 AI SDK 호출 전에 registerTelemetry()가 실행되는지 확인하세요. Next.js에서는 라우트 안이 아니라 프로젝트 루트의 instrumentation.ts를 의미해요. 텔레메트리 통합을 등록하지 않으면 AI SDK 텔레메트리가 완전히 비활성화돼요.
트레이스가 실행 중간에 중단됨: 내보내기 큐가 비워지기 전에 프로세스가 종료된 경우예요. 종료 시 runtime.shutdown()을 호출하거나 서버리스 핸들러 끝에서 runtime.flush()를 호출하세요.
스트리밍 호출이 불완전하게 도착: 플러시나 종료 전에 스트림을 끝까지 소비하거나 중단하세요.
트레이스에 콘텐츠가 없음: AI SDK의 recordInputs·recordOutputs와 init()의 captureContent를 확인하세요.

그 외에는 Confident AI 문제 해결 가이드를 참고하세요.

더 알아보기 (Learn more)

전체 사이트맵