Sentry 관측성

Sentry 관측성 (Sentry Observability)

Sentry는 AI 애플리케이션의 오류, 트레이스, 지연 시간, 토큰 사용량을 모니터링할 수 있게 해 줘요. Sentry의 Next.js와 Node.js SDK는 네이티브 Node.js 텔레메트리 채널을 통해 AI SDK v7을 계측하므로, AI SDK 트레이스를 Sentry로 보낼 때 @ai-sdk/otel이나 registerTelemetry가 따로 필요 없어요.

출처: 문서

본문

Sentry는 generateText, streamText, 모델 호출, 도구 호출, 임베딩, 리랭킹, 토큰 사용량, 그리고 오류에 대한 스팬(span)을 캡처해요. AI SDK telemetry 옵션으로 functionId를 추가하면, Sentry에서 트레이스를 더 쉽게 찾고 그룹화할 수 있어요.

참고: AI SDK v7 지원에는 @sentry/node, @sentry/nextjs 또는 다른 Sentry 서버 SDK 버전 10.62.0 이상이 필요해요. 네이티브 텔레메트리 채널은 Node.js 런타임에서 사용할 수 있으니, 이 트레이스에는 Node.js 라우트나 서버 프로세스를 사용하세요.

셋업 (Setup)

애플리케이션에 Sentry가 이미 설정되어 있다면 사용법으로 건너뛰세요. 그렇지 않다면 AI SDK 호출을 실행하기 전에 런타임에 맞는 Sentry SDK를 설치하고 초기화하세요.

Next.js

Sentry 마법사(wizard)가 Next.js 셋업 전체를 만들어 줄 수 있어요. 아래 스니펫은 AI SDK 트레이스와 관련된 서버 쪽 부분을 보여 줘요:

pnpm add @sentry/nextjs

Sentry 서버 설정을 만들거나 업데이트하고 tracesSampleRate나 tracesSampler로 트레이싱을 활성화하세요:

import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Next.js에서 Sentry를 수동으로 설정한다면, instrumentation.ts가 Node.js 런타임용 서버 설정을 로드하는지 확인하세요:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./sentry.server.config');
  }
}

Node.js

pnpm add @sentry/node

서버 진입점 시작 부분에서 Sentry를 초기화하고 tracesSampleRate나 tracesSampler로 트레이싱을 활성화하세요:

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Sentry 서버 SDK에서는 Vercel AI 통합이 기본으로 활성화되어 있어요. 기본 통합을 비활성화했다면 명시적으로 다시 추가하세요:

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  integrations: [Sentry.vercelAIIntegration()],
});

사용법 (Usage)

AI SDK를 평소처럼 사용하면 돼요. Sentry에는 registerTelemetry(new OpenTelemetry()) 호출이나 telemetry.isEnabled: true 플래그가 필요 없어요.

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

export const runtime = 'nodejs';

export async function POST() {
  const result = await generateText({
    model: anthropic('claude-sonnet-5'),
    prompt: 'What is the weather in Tokyo?',
    telemetry: {
      functionId: 'anthropic-weather-demo',
    },
  });

  return Response.json({ text: result.text });
}

독립 실행형 Node.js 스크립트라면, AI SDK 호출을 Sentry 스팬 안에 감싸서 AI 스팬이 부모 트레이스를 갖도록 한 뒤, 프로세스가 종료되기 전에 플러시하세요:

import './instrumentation';
import * as Sentry from '@sentry/node';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

await Sentry.startSpan({ name: 'ai-sdk-demo' }, async () => {
  const result = await generateText({
    model: openai('gpt-6-luna'),
    prompt: 'Write a haiku about observability.',
    telemetry: {
      functionId: 'haiku-demo',
    },
  });

  console.log(result.text);
});

await Sentry.flush(2000);

요청이 실행된 후 Sentry를 열고 트레이스에서 gen_ai.invoke_agent, gen_ai.generate_content, gen_ai.execute_tool 스팬을 찾아보세요.

프롬프트와 응답 기록하기 (Recording prompts and responses)

기본적으로 Sentry는 모델, 프로바이더, 지연 시간, 토큰 사용량, 오류 같은 메타데이터를 기록해요. 프롬프트와 응답 내용은 옵트인(opt in)할 때만 전송돼요.

Sentry의 dataCollection.genAI 옵션으로 콘텐츠 캡처를 전역적으로 활성화하세요:

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  dataCollection: {
    genAI: {
      inputs: true,
      outputs: true,
    },
  },
});

아니면 telemetry 옵션으로 AI SDK 호출 하나에만 활성화할 수도 있어요:

const result = await generateText({
  model: openai('gpt-6-luna'),
  prompt: 'Summarize this support ticket.',
  telemetry: {
    functionId: 'support-summary',
    recordInputs: true,
    recordOutputs: true,
  },
});

민감한 호출에 대해 Sentry AI 텔레메트리를 끄려면 telemetry.isEnabled를 false로 설정하세요.

더 알아보기 (Learn more)