Axiom Observability

Axiom Observability

Axiom은 AI 엔지니어링 워크플로우를 위한 특화 기능을 갖춘 데이터 플랫폼으로, 정교한 AI 시스템을 자신 있게 구축하도록 도와줘요.

Axiom의 AI SDK 통합은 모델 래퍼를 사용해 모든 LLM 호출에 대한 상세 trace를 자동으로 캡처하므로, 애플리케이션의 성능, 비용, 동작에 대한 즉각적인 가시성을 제공해요.

출처: 문서

본문

설정

1. Axiom 구성

먼저 Axiom 조직, trace를 보낼 데이터셋, 그리고 API 토큰이 필요해요.

2. Axiom SDK 설치

프로젝트에 Axiom 패키지를 설치해요:

npm install axiom

3. 환경 변수 설정

.env 파일에서 환경 변수를 설정해요. 이것은 표준 OpenTelemetry 구성을 사용해 trace를 Axiom 데이터셋으로 직접 보내요.

# Axiom Configuration
AXIOM_TOKEN="YOUR_AXIOM_API_TOKEN"
AXIOM_DATASET="your-axiom-dataset-name"

# Vercel and OpenTelemetry Configuration
OTEL_SERVICE_NAME="my-ai-app"
OTEL_EXPORTER_OTLP_ENDPOINT="https://api.axiom.co/v1/traces"
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_AXIOM_API_TOKEN,X-Axiom-Dataset=your-axiom-dataset-name"

# Your AI Provider Key
OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

플레이스홀더 값을 실제 Axiom 토큰과 데이터셋 이름으로 바꿔요.

4. 계측(instrumentation) 설정

Axiom으로 데이터를 보내려면 tracer를 구성해요. 예를 들어 전용 계측 파일을 만들고 앱의 나머지 부분보다 먼저 로드해요. Node.js 환경의 예시 구성:

  1. 의존성 설치:
npm install dotenv @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/sdk-node @opentelemetry/sdk-trace-node @opentelemetry/semantic-conventions @opentelemetry/api
  1. 계측 파일 생성:
import { trace } from '@opentelemetry/api';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import type { Resource } from '@opentelemetry/resources';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
import { initAxiomAI, RedactionPolicy } from 'axiom/ai';

const tracer = trace.getTracer('my-tracer');

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: 'my-ai-app',
  }) as Resource,
  spanProcessor: new SimpleSpanProcessor(
    new OTLPTraceExporter({
      url: `https://api.axiom.co/v1/traces`,
      headers: {
        Authorization: *** ${process.env.AXIOM_TOKEN}`,
        'X-Axiom-Dataset': process.env.AXIOM_DATASET,
      },
    }),
  ),
});

sdk.start();

initAxiomAI({ tracer, redactionPolicy: RedactionPolicy.AxiomDefault });

5. AI 모델 감싸기와 사용

애플리케이션 코드에서 axiom/ai에서 wrapAISDKModel을 import 해서 기존 AI SDK 모델 클라이언트를 감싸요.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
import { wrapAISDKModel } from 'axiom/ai';

// 1. Create your standard AI model provider
const openaiProvider = createOpenAI({
  apiKey: proces...KEY,
});

// 2. Wrap the model to enable automatic tracing
const tracedGpt4o = wrapAISDKModel(openaiProvider('gpt-6-astra'));

// 3. Use the wrapped model as you normally would
const { text } = await generateText({
  model: tracedGpt4o,
  prompt: 'What is the capital of Spain?',
});

console.log(text);

tracedGpt4o 모델을 사용한 모든 호출은 이제 Axiom 데이터셋으로 상세 trace를 자동으로 보내요.

Axiom에서 볼 수 있는 것

통합 후 Axiom 데이터셋에는 다음이 포함돼요:

  • AI Trace Waterfall: 단일/다중 스텝 LLM 워크플로우를 시각화하는 전용 뷰.
  • Gen AI Dashboard: 비용, 지연시간, 토큰 사용량, 오류율을 모니터링하는 사전 구축 대시보드.
  • Detailed Spans: 전체 프롬프트와 완성, 토큰 수, 모델 정보를 포함한 모든 호출에 대한 풍부한 텔레메트리.

고급 사용법

Axiom의 AI SDK는 더 깊은 가시성을 위한 더 고급 계측을 제공해요:

  • 비즈니스 컨텍스트: withSpan 함수를 사용해 특정 비즈니스 기능(예: customer_support_agent) 아래에서 LLM 호출을 그룹화해요.
  • 도구 트레이싱: wrapTool 헬퍼를 사용해 AI 모델이 호출하는 도구의 실행을 자동으로 추적해요.

이 기능들에 대해 더 알아보려면 Axiom AI SDK Instrumentation guide를 참고하세요.

추가 자료

더 알아보기 (Learn more)