LangWatch Observability

LangWatch Observability

LangWatch (GitHub)은 LLM 파이프라인을 모니터링, 실험, 측정, 개선하기 위한 LLM Ops 플랫폼이며, fair-code 배포 모델을 채택하고 있어요.

출처: 문서

본문

설정

LangWatch 대시보드에서 LANGWATCH_API_KEY를 얻어요.

npm install langwatch

LANGWATCH_API_KEY가 설정되었는지 확인해요:

환경 변수

LANGWATCH_API_KEY='your_api_key_here'

클라이언트 파라미터

import { LangWatch } from 'langwatch';

const langwatch = new LangWatch({
  apiKey: 'your_...re',
});

기본 개념

  • LLM 파이프라인 전체를 트리거하는 각 메시지는 Trace로 캡처돼요.
  • Trace는 파이프라인 안의 단계인 여러 Span을 포함해요.
    • span은 LLM 호출, RAG 검색을 위한 데이터베이스 쿼리, 또는 단순한 함수 변환이 될 수 있어요.
    • 서로 다른 유형의 Span은 서로 다른 파라미터를 캡처해요.
    • Span은 파이프라인 구조를 캡처하기 위해 중첩될 수 있어요.
  • Trace는 메타데이터에 동일한 thread_id를 가짐으로써 LangWatch 대시보드에서 함께 그룹화될 수 있으며, 개별 메시지가 대화의 일부가 돼요.
    • 사용자 분석을 추적하려면 user_id 메타데이터도 제공하는 것이 권장돼요.

구성

AI SDK는 Next.js OpenTelemetry 통합을 통한 트레이싱을 지원해요. LangWatchExporter를 사용해 이 trace를 LangWatch로 자동 수집할 수 있어요.

먼저 필요한 의존성을 설치해요:

npm install @vercel/otel langwatch @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/sdk-logs @ai-sdk/otel

그런 다음 애플리케이션용 OpenTelemetry를 설정해요. Next.js와 함께 AI SDK를 쓰는지 Node.js에서 쓰는지에 따라 아래 탭 중 하나를 따르세요:

Next.js

아직 instrumentationHook을 활성화하지 않았다면 next.config.js 파일에서 활성화해야 해요:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};

module.exports = nextConfig;

다음으로 프로젝트의 루트 디렉토리(또는 사용 중이라면 src 폴더 안)에 instrumentation.ts(또는 .js)라는 파일을 만들고 LangWatchExporter를 traceExporter로 사용해요:

import { registerTelemetry } from 'ai';
import { LegacyOpenTelemetry } from '@ai-sdk/otel';
import { registerOTel } from '@vercel/otel';
import { LangWatchExporter } from 'langwatch';

registerTelemetry(new LegacyOpenTelemetry());

export function register() {
  registerOTel({
    serviceName: 'next-app',
    traceExporter: new LangWatchExporter(),
  });
}

(Next.js OpenTelemetry 구성에 대해 더 알아보려면 공식 가이드를 참고하세요)

마지막으로 추적하려는 AI SDK 호출에서 telemetry 추적을 활성화해요:

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

const result = await generateText({
  model: openai('gpt-6-luna'),
  prompt:
    'Explain why a chicken would make a terrible astronaut, be creative and humorous about it.',
  telemetry: {
    // optional metadata
    metadata: {
      userId: 'myuser-123',
      threadId: 'mythread-123',
    },
  },
});

Node.js

Node.js의 경우 먼저 공식 OpenTelemetry 가이드를 따르세요:

OpenTelemetry를 설정했다면 LangWatchExporter를 사용해 trace를 LangWatch로 자동 전송할 수 있어요:

import { LangWatchExporter } from 'langwatch';

const sdk = new NodeSDK({
  traceExporter: new LangWatchExporter({
    apiKey: proces...KEY,
  }),
  // ...
});

끝이에요! 이제 메시지가 LangWatch에 표시돼요:

AI SDK

예시 프로젝트

더 복잡한 파이프라인과 AI SDK·LangWatch 통합이 포함된 전체 예시 프로젝트는 우리 GitHub에서 찾을 수 있어요.

수동 통합

아래부터의 문서는 수동 통합을 위한 것이에요. AI SDK OpenTelemetry 통합을 사용하지 않는 경우, 메시지를 캡처하기 위해 trace를 수동으로 시작할 수 있어요:

import { LangWatch } from 'langwatch';

const langwatch = new LangWatch();

const trace = langwatch.getTrace({
  metadata: { threadId: 'mythread-123', userId: 'myuser-123' },
});

그런 다음 LLM으로 보낼 입력과 함께 trace 안에서 LLM span을 시작할 수 있어요.

const span = trace.startLLMSpan({
  name: 'llm',
  model: model,
  input: {
    type: 'chat_messages',
    value: messages,
  },
});

이것은 LLM 입력을 캡처하고 호출이 시작된 시간을 등록해요. LLM 호출이 끝나면 span을 종료해 종료 타임스탬프가 등록되게 하고 출력과 토큰 메트릭(비용 계산에 사용됨)을 캡처해요, 예:

span.end({
  output: {
    type: 'chat_messages',
    value: [chatCompletion.choices[0]!.message],
  },
  metrics: {
    promptTokens: chatCompletion.usage?.prompt_tokens,
    completionTokens: chatCompletion.usage?.completion_tokens,
  },
});

자료

더 많은 정보와 예시는 아래에서 읽을 수 있어요:

지원

질문이 있거나 도움이 필요하면 커뮤니티에 참여하세요:

더 알아보기 (Learn more)