OpenTelemetry 수집 참조
이 페이지는 Amplitude의 OTLP 엔드포인트가 OpenTelemetry GenAI 스팬을 에이전트 분석 [Agent] 이벤트로 변환하는 방법에 대한 참조입니다. 설정 단계는 에이전트 분석으로 OpenTelemetry 추적 보내기를 참조하십시오.
엔드포인트 및 프로토콜
| 지역 | 엔드포인트 |
|---|---|
| 미국 | https://api.amplitude.com/otlp/v1/traces |
| EU | https://api.eu.amplitude.com/otlp/v1/traces |
- 프로토콜: HTTP 전용 OTLP(
http/protobuf또는http/json), 선택적 gzip 포함. Amplitude는 OTLP/gRPC를 지원하지 않습니다. - 인증:
Bearer토큰 또는api_key쿼리 매개변수로 사용되는 프로젝트 API 키. Amplitude는 프로젝트별 활성화 요청을 필요로 하지 않습니다. - 지원되는 계측: OpenTelemetry GenAI 시맨틱 컨벤션, OpenInference(
llm.*), OpenLLMetry 및 Traceloop(traceloop.*), OpenLIT 및 LiteLLM. Amplitude는 GenAI 스팬이 아닌 스팬을 무시합니다.
속성 확인 순서
Amplitude는 존재하는 첫 번째 속성을 다음 순서로 읽습니다.
| 신호 | Amplitude가 읽는 속성(순서대로) |
|---|---|
| 세션 | gen_ai.conversation.id, session.id, traceloop.association.properties.session (또는 chat, thread, conversation), gen_ai.session.id, 리소스 session.id 및 gen_ai.conversation.id. 이러한 항목이 없으면 Amplitude는 추적 ID로 되돌리고 세션을 성능 저하됨으로 표시합니다. Claude-native 스팬은 예외입니다: anthropic.session.id은(는) 세션이고, 다른 gen_ai.conversation.id이(가) 스레드로 유지됩니다. |
| 사용자 | enduser.id, gen_ai.request.user, gen_ai.user, user.id, traceloop.association.properties.user, resource enduser.id 및 user.id, 그 다음 LiteLLM의 metadata.user_api_key_end_user_id. 이 중 어느 것도 없는 경우 사용자는 unknown로 확인됩니다. |
| 에이전트 | gen_ai.agent.id, 그 외 리소스 service.name. Claude-native span은 service.name로 폴백되지 않으므로 claude-platform 는 에이전트로 저장되지 않습니다. |
| 상위 에이전트 | 스팬 속성 amplitude.parent.agent.id만 해당. 상위 스팬 ID 및 리소스 속성은 상위 에이전트가 아닙니다. |
| 환경 | deployment.environment, 스팬 또는 리소스에 대해. |
무엇이 무엇에 매핑되는지
| OpenTelemetry 소스 | [Agent] 결과 |
|---|---|
chat, text_completion, 또는 generate_content의 gen_ai.operation.name | [Agent] AI Response 및 새로운 입력 메시지에서 합성된 [Agent] User Message |
gen_ai.operation.name의 execute_tool | gen_ai.tool.name, gen_ai.tool.call.id, [Agent] Tool Call, 인수 및 결과 |
invoke_agent, retrieval, plan 또는 메모리 작업 등 모든 기타 작업 | [Agent] Span |
gen_ai.request.model, gen_ai.response.model | [Agent] Model Name |
gen_ai.provider.name, 또는 사용되지 않는 gen_ai.system | [Agent] Provider |
gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, 그리고 추론 및 캐시 토큰 속성 | 토큰 속성 |
gen_ai.usage.cost | [Agent] Cost USD. 이는 Amplitude 확장 프로그램입니다: OpenTelemetry는 비용을 표준화하지 않으므로 대부분의 계측에서 이를 생략합니다. |
gen_ai.response.finish_reasons | [Agent] Finish Reason |
gen_ai.input.messages, gen_ai.output.messages | $llm_message |
gen_ai.system_instructions, 또는 system-role 메시지 | [Agent] System Prompt AI 응답에 대한 |
Span 상태 ERROR | [Agent] Is Error, [Agent] Error Message |
trace_id, span_id, parent_span_id, 시작 시간, 기간 | [Agent] Trace ID, [Agent] Span ID, [Agent] Parent Span ID, 이벤트 타임스탬프, [Agent] Latency Ms |
amplitude.parent.agent.id | [Agent] Parent Agent ID |
| 합성된 사용자 메시지를 기반으로 파생됨 | [Agent] Message Source: 명시적 amplitude.message.source이(가) 우선합니다. 그렇지 않으면 상위 에이전트가 있는 경우 agent, 그 외에는 user |
Amplitude는 gen_ai.usage.cost가 없을 때 비용을 계산하지 않습니다. 비용 계산 방법을 참조하십시오.
채팅 호출은 전체 프롬프트 기록을 다시 전송하므로 마지막 비서 메시지 뒤에 있는 사용자 메시지만 새 [Agent] User Message로 변경됩니다. Amplitude는 재생 기록을 다시 표시하지 않으며, 새 입력이 도구 결과인 도구 루프 연속(tool-loop continuation)은 사용자 턴을 생성하지 않습니다.
AI SDK의 프로세스 내 OpenTelemetry 내보내기는 자체 매핑을 사용합니다. SDK 참조에서 OpenTelemetry 속성 매핑을 참조하십시오.
기능 플래그 속성
Amplitude는 GenAI 스팬에서 OpenTelemetry 기능 플래그 평가를 읽고 각 평가를 실험으로 기록합니다. 모든 feature_flag.evaluation 스팬 이벤트를 먼저 읽은 다음 스팬의 자체 feature_flag.* 속성을 읽습니다. 리소스 속성은 카운트되지 않습니다.
| OpenTelemetry 소스 | 실험 필드 |
|---|---|
feature_flag.key | 키 |
feature_flag.result.variant, 또는 이전 feature_flag.variant | 변형 |
feature_flag.provider.name, 또는 이전 feature_flag.provider_name | 공급자 |
amplitude.experiment.unit agent_session또는 turn | Unit. 이 값이 없거나 다른 값으로 사용되는 경우 단위는 span입니다. |
스팬이 생성하는 모든 이벤트는 [Agent] Experiments를 포함하고, 정확히 하나의 평가가 남았을 때 [Agent] Experiment Key, Variant, Unit, Provider가 추가됩니다. 오류를 반환한 것처럼 변형이 없는 평가는 아무것도 추가되지 않습니다. 두 평가가 키를 공유하는 경우 나중에 수행된 평가가 우선하므로 span 속성이 동일한 키를 사용하는 span 이벤트를 재정의합니다. 유효성 검사 규칙과 10회 실험 제한이 AI SDK와 일치합니다. 에이전트 분석에서 실험 변형 기록을 참조하십시오.
Claude Platform이 걸쳐 있는 범위
Amplitude는 스팬 이름이 anthropic.로 시작하고 스팬에 gen_ai.provider.name=anthropic, com.anthropic.claude-platform 또는 com.anthropic.sdk 계측 범위, 또는 리소스 service.name=claude-platform이(가) 포함된 경우에만 이러한 규칙을 적용합니다. 일반 invoke_agent 스팬과 다른 이름의 Anthropic 채팅 스팬은 위의 매핑에 머무릅니다.
| Claude 스팬 | [Agent] 결과 |
|---|---|
anthropic.messages.create | 사용자 메시지 및 AI 응답. 이 범위는 토큰 총 수를 유지합니다. |
anthropic.model_request Messages API 하위 | [Agent] Span 사용량이 제거된 상태로 상위 합계는 다시 계산되지 않습니다. |
anthropic.session.turn 메시지 텍스트 포함 | 사용자 메시지 및 AI 응답이며, 해당 이벤트에 복사된 사용량은 없습니다. |
anthropic.session.turn 메시지 텍스트가 없는 경우 | [Agent] Span, 사용량이 제거된 상태입니다. |
anthropic.model_request 및 gen_ai.operation.name=chat | [Agent] Span 는 모델, 토큰, 캐시, 지연 시간 및 오류를 유지합니다. 여러 모델 요청은 각각 고유한 사용량을 유지합니다. |
anthropic.tool_use, anthropic.mcp_tool_use 또는 anthropic.custom_tool_use로 시작하는 스팬 이름 | [Agent] Tool Call. anthropic.tool_result.content은(는) 도구 출력입니다. anthropic.mcp.server.name은(는) 추가 속성으로 유지됩니다. |
anthropic.test | 승인되었으며 삭제되었습니다. 라이브 이벤트에는 나타나지 않습니다. |
anthropic.message.stop_reason 후 anthropic.session.turn.stop_reason이(가) 수행되면, gen_ai.response.finish_reasons이(가) 없을 때 AI 응답에서 [Agent] Finish Reason이(가) 됩니다. Amplitude는 enduser.id 또는 gen_ai.usage.cost을(를) 발명하지 않습니다. 상위 스팬 ID는 계층 구조로 유지됩니다. 그들은 [Agent] Parent Agent ID이(가) 아닙니다.
목적지를 추가하려면 Claude 플랫폼 추적 보내기를 참조하십시오.
전송, 제한 및 응답
전송은 최소 한 번 발생합니다. 영속적 전송 큐로 Collector를 실행하고 재시도를 활성화한 상태로 유지하십시오. 인메모리 큐는 재시작 시 버퍼링된 스팬을 손실합니다.
| 제한 | 행동 방식 |
|---|---|
| 압축 해제 시 4MB인 요청 본문 | 413 |
| 내보내기당 2,000개의 번역된 이벤트 | 413. Collector 배치 크기를 줄입니다. |
| 응답 | 의미 |
|---|---|
200 | 승인되었습니다. partial_success 본문은 수집이 거부한 모든 이벤트를 보고합니다. 200은 수집기에게 배치를 삭제하도록 지시하므로 이를 모니터링하십시오. |
400 | 잘못된 형식의 요청 본문 또는 OTLP 페이로드입니다. 재시도할 수 없습니다. |
401 | 누락되었거나 잘못된 API 키입니다. |
415 | application/x-protobuf또는 application/json가 아닌 콘텐츠 유형입니다. |
503 | 다운스트림 수집 중단 포함 일시적입니다. Collector가 해당 큐에서 재시도해야 합니다. |
OTLP 리시버는 403를 반환하지 않습니다. CDN 또는 WAF 등의 다른 홉에서 발생한 403를 누락된 Amplitude 활성화가 아닌 구성 오류로 취급하십시오.
이 내용이 도움이 되었나요?
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.