OpenTelemetry 추적을 Agent 분석으로 전송

Amplitude의 OTLP 엔드포인트는 OpenTelemetry GenAI 스팬을 수신하여 AI SDK가 생성하는 것과 동일한 [Agent] 이벤트로 변환하므로 세션, 보강 및 모든 차트가 동일한 방식으로 작동합니다. 스택에서 이미 GenAI 스팬을 방출하는 경우 내보내기에 Amplitude를 지정하십시오. Amplitude SDK나 새로운 계측은 필요하지 않습니다.

이미 OpenTelemetry 내보내기 또는 Collector를 실행하고 있는 경우 이 경로를 사용하십시오. 대신 AI SDK를 사용하여 Node 또는 Python 앱을 계측하는 경우, 별도의 경로인 SDK의 프로세스 내 OTel 내보내기를 사용하십시오. 시작하기 전에 세션 ID와 개인정보 보호 모드를 결정합니다.

내보내기 구성

Exporter 또는 Collector에서 다음 환경 변수를 설정합니다.

bash
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.amplitude.com/otlp/v1/traces   # US
# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.eu.amplitude.com/otlp/v1/traces  # EU
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <project API key>"
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf   # or http/json

OTLP HTTP 엔드포인트는 일반적으로 미국 및 EU에서 사용할 수 있습니다. 유효한 프로젝트 API 키만으로도 충분합니다. Amplitude는 프로젝트별 활성화 요청이 필요하지 않으며, 허용 목록이 누락된 경우 수신자가 403을(를) 반환하는 일은 없습니다.

  • 프로토콜: HTTP 전용 OTLP. Amplitude는 http/protobuf(OpenTelemetry SDK 및 Collector 기본값) 및 http/json을(를) 허용하며, gzip은 선택 사항입니다. Amplitude는 OTLP/gRPC를 지원하지 않으므로 OTLP/HTTP 엑스포터를 사용하는 로컬 Collector를 통해 gRPC 트래픽을 브리징하십시오.
  • 인증: 프로젝트 API 키를 Bearer 토큰으로 전달하거나 api_key 쿼리 매개변수로 전달합니다.
  • 지원되는 계측: OpenTelemetry GenAI 시맨틱 컨벤션, OpenInference(llm.*), OpenLLMetry 및 Traceloop(traceloop.*), OpenLIT 및 LiteLLM. Amplitude는 GenAI 스팬이 아닌 스팬을 무시하므로 혼합 Collector를 Amplitude로 가리킬 수 있습니다.

Claude 플랫폼 추적 전송

Claude는 이미 OpenTelemetry를 내보냅니다. Amplitude를 Claude 목적지로 추가합니다. 이 경로에 Amplitude SDK는 필요하지 않습니다.

Claude 콘솔에서 목적지 기본 URL을 지역 호스트로 설정합니다. Claude가 /v1/traces을(를) 추가하므로 기본 URL에 해당 경로가 포함되지 않습니다.

헤더를 Authorization: Bearer <project API key>로 설정합니다.

  • 전체 콘텐츠는 트랜스크립트를 전송합니다. 관리 에이전트 턴의 사용자 및 비서 텍스트는 [Agent] User Message 및 [Agent] AI Response로 변경됩니다.
  • 메타데이터는 여전히 모델, 토큰, 지연 시간, 도구 호출 및 오류만 전송합니다. 메시지 텍스트가 없는 턴은 [Agent] Span로 유지됩니다.
  • 하나의 내보내기 경로를 사용합니다. Claude SDK와 Claude Platform이 모두 동일한 응답을 내보내는 경우, Amplitude는 두 응답을 모두 저장합니다.
  • 목적지 Test 작업이 anthropic.test을(를) 전송합니다. Amplitude는 해당 범위를 허용하며 라이브 이벤트에 표시하지 않습니다.

Claude 세션은 anthropic.session.id입니다. gen_ai.conversation.id은(는) 해당 세션 내에서 스레드를 유지합니다. Messages API 스팬에는 Claude 세션 id가 없으므로 세션 속성 순서를 사용합니다. 스팬 매핑은 Claude 플랫폼 스팬을 참조하십시오.

세션 및 사용자 속성 설정

세션 속성은 계측에 적용할 가치가 있는 단 하나의 변경 사항입니다. Amplitude는 다른 모든 것을 자동으로 매핑합니다.

Amplitude 에이전트 세션은 하나의 추적이 아니라 전체 대화입니다. 대화 속성이 없으면 모든 추적은 자체의 단일 턴 세션이 됩니다. 그러면 작업 완료 및 중단은 노이즈로 표시되며, 청구는 에이전트 세션별로 이루어지므로 한 대화가 여러 대화로 청구됩니다.

GenAI 스팬에 다음 속성을 설정합니다.

  • 세션: gen_ai.conversation.id을(를) 대화, 티켓 또는 run ID로 설정합니다. 세션 ID 선택을 참조하십시오.
  • 사용자: enduser.id을(를) 프로덕트 분석에 사용하는 것과 동일한 사용자 ID로 설정합니다. anonymous와 같은 위치 표시자를 절대로 전송하지 마십시오. 사용자 ID 설정을 참조하십시오.
  • 에이전트: gen_ai.agent.id 또는 Amplitude는 리소스 service.name을(를) 기본값으로 사용합니다.
  • 상위 에이전트: span 속성 amplitude.parent.agent.id. 상위 스팬 ID는 상위 에이전트가 아니며, Amplitude는 리소스에서 상위 에이전트를 읽지 않습니다.

Amplitude는 session.id 및 Traceloop 연관 속성과 같은 다른 일반적인 속성도 읽습니다. 전체 해결 순서에 대해서는 속성 해결 순서를 참조하십시오.

비용을 리포트하려면 gen_ai.usage.cost도 설정합니다. 이 속성이 없을 때 Amplitude는 비용을 계산하지 않습니다.

span이 실행된 A/B 테스트 또는 기능 플래그 변형을 기록하려면 feature_flag.evaluationspan 이벤트를 추가하거나, span에 feature_flag.key 및 feature_flag.result.variant을(를) 설정합니다. Amplitude는 이를 [Agent] Experiment*속성에 매핑합니다. 기능 플래그 속성을 참조하십시오.

개인정보 보호 모드 적용

대부분의 OpenTelemetry GenAI 계측은 메시지 콘텐츠를 옵트인으로 취급합니다.

  • 콘텐츠 캡처 해제: metadata_only트랜스크립트 없이 비용, 토큰, 지연 시간, 모델 및 세션의 형태를 확인할 수 있습니다.
  • 콘텐츠 캡처 사용: gen_ai.input.messages, gen_ai.output.messages, 및 gen_ai.system_instructions는 메시지 텍스트가 되고 [Agent] System Prompt가 됩니다. Amplitude는 해당 텍스트를 내보낸 상태로 저장합니다. Amplitude는 수신 후 이를 폐기하지 않습니다. 내보내기 전에 해당 속성, Plus 도구 인수 및 도구 결과를 삭제합니다. 에이전트 분석 개인정보 보호 모드를 참조하십시오.

데이터가 네트워크에서 벗어나기 전에 수행해야 하는 편집은 애플리케이션 또는 Collector 프로세서에 속합니다. 각 모드가 전송하는 내용에 대해서는 에이전트 분석 개인정보 보호 모드를 참조하십시오.

OTLP 전용 경로에서 세션 닫기

[Agent] Session End은(는) 선택 사항이며 권장됩니다. 파이프라인이 해당 이벤트를 추가하지 않는 한 OpenTelemetry 내보내기는 이를 전송하지 않습니다. Amplitude는 기본적으로 적합한 에이전트 이벤트가 없을 때 30분 후에 세션을 닫으며, 세션별 재정의가 설정되지 않은 경우 세션 시작 후 24시간이 지나면 세션을 닫습니다. Enrichment는 첫 번째 닫기 후 한 번 실행됩니다. OpenTelemetry 변환기는 스팬에서 idle-timeout 속성을 읽지 않습니다. 창을 변경하려면 HTTP [Agent] Context 키 idle_timeout_minutes을(를) 전송하거나, 하나의 [Agent] Session End와(과) 함께 [Agent] Session Idle Timeout Minutes을(를) 전송하십시오. 세션 닫기 방법을 참조하십시오. 에이전트 프레임워크 가이드는 이 동일한 경로를 사용합니다. 에이전트 프레임워크를 참조하십시오.

안정적인 전송 유지

전송은 최소 한 번 이루어집니다. 인메모리 대기열은 재시작 시 버퍼링된 스팬을 잃게 되므로 영구 전송 큐로 Collector를 실행하고 재시도를 활성화한 상태로 유지하십시오. 200 응답에는 거부된 이벤트를 나열하는 partial_success 본문이 포함될 수 있습니다. 제한 및 응답 코드에 대해서는 전송, 제한 및 응답을 참조하십시오.

확인

하나의 추적된 대화를 전송한 다음 라이브 이벤트에서 다음을 포함하여 이벤트가 도착하는지 확인합니다:

  1. 추적 ID가 아닌 실제 [Agent] Session ID입니다.
  2. 채워진 [Agent] Agent ID.
  3. 귀하의 고유 사용자 ID이며, unknown은(는) 아닙니다.

이 세 가지 값은 '세션 및 사용자 속성 설정'의 속성에서 가져옵니다. 전체 체크리스트는 에이전트 분석 계측 확인을 참조하십시오.

이 내용이 도움이 되었나요?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

이 페이지에서