OpenTelemetry ingestion reference

이 페이지는 아직 귀하의 언어로 번역되지 않았습니다. 현재 작업 중이므로 곧 다시 확인해 주십시오.

This page is the reference for how Amplitude's OTLP endpoint translates OpenTelemetry GenAI spans into Agent Analytics [Agent] events. For setup steps, refer to Send OpenTelemetry traces to Agent Analytics.

Endpoints and protocol

Region	Endpoint
US	`https://api.amplitude.com/otlp/v1/traces`
EU	`https://api.eu.amplitude.com/otlp/v1/traces`

Protocol: OTLP over HTTP only, as http/protobuf or http/json, with optional gzip. Amplitude doesn't support OTLP/gRPC.
Authentication: The project API key as a Bearer token or as an api_key query parameter. Amplitude doesn't require a per-project enablement request.
Supported instrumentation: OpenTelemetry GenAI semantic conventions, OpenInference (llm.*), OpenLLMetry and Traceloop (traceloop.*), OpenLIT, and LiteLLM. Amplitude ignores non-GenAI spans.

Attribute resolution order

Amplitude reads the first attribute present, in this order:

Signal	Attributes Amplitude reads, in order
Session	`gen_ai.conversation.id`, `session.id`, `traceloop.association.properties.session` (or `chat`, `thread`, `conversation`), `gen_ai.session.id`, then resource `session.id` and `gen_ai.conversation.id`. With none of these, Amplitude falls back to the trace ID and marks the session degraded.
User	`enduser.id`, `gen_ai.request.user`, `gen_ai.user`, `user.id`, `traceloop.association.properties.user`, resource `enduser.id` and `user.id`, then LiteLLM's `metadata.user_api_key_end_user_id`. With none of these, the user resolves to `unknown`.
Agent	`gen_ai.agent.id`, else resource `service.name`.
Environment	`deployment.environment`, on the span or the resource.

What maps to what

OpenTelemetry source	`[Agent]` result
`gen_ai.operation.name` of `chat`, `text_completion`, or `generate_content`	`[Agent] AI Response`, plus an `[Agent] User Message` synthesized from the new input messages
`gen_ai.operation.name` of `execute_tool`	`[Agent] Tool Call`, with `gen_ai.tool.name`, `gen_ai.tool.call.id`, arguments, and result
Any other operation, such as `invoke_agent`, `retrieval`, `plan`, or the memory operations	`[Agent] Span`
`gen_ai.request.model`, `gen_ai.response.model`	`[Agent] Model Name`
`gen_ai.provider.name`, or the deprecated `gen_ai.system`	`[Agent] Provider`
`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and the reasoning and cache token attributes	Token properties
`gen_ai.usage.cost`	`[Agent] Cost USD`. This is an Amplitude extension: OpenTelemetry doesn't standardize cost, so most instrumentation omits it.
`gen_ai.response.finish_reasons`	`[Agent] Finish Reason`
`gen_ai.input.messages`, `gen_ai.output.messages`	`$llm_message`
`gen_ai.system_instructions`, or a `system`-role message	`[Agent] System Prompt` on the AI Response
Span status of `ERROR`	`[Agent] Is Error`, `[Agent] Error Message`
`trace_id`, `span_id`, `parent_span_id`, start time, duration	`[Agent] Trace ID`, `[Agent] Span ID`, `[Agent] Parent Span ID`, event timestamp, `[Agent] Latency Ms`

Amplitude doesn't calculate a cost when gen_ai.usage.cost is absent. Refer to How cost is calculated.

A chat call re-sends the whole prompt history, so only the user messages after the last assistant message become a new [Agent] User Message. Amplitude doesn't re-emit replayed history, and a tool-loop continuation whose new input is a tool result doesn't produce a user turn.

The AI SDK's in-process OpenTelemetry exporter uses its own mapping. Refer to OpenTelemetry attribute mapping in the SDK reference.

Delivery, limits, and responses

Delivery is at least once. Run a Collector with a persistent sending queue and keep retries enabled. An in-memory queue loses buffered spans on restart.

Limit	Behavior
4 MB decompressed request body	`413`
2,000 translated events per export	`413`. Lower your Collector batch size.

Response	Meaning
`200`	Accepted. A `partial_success` body reports any events that ingestion rejected. Watch for it, because a `200` tells your Collector to delete the batch.
`400`	Malformed request body or OTLP payload. Not retryable.
`401`	Missing or invalid API key.
`415`	A content type other than `application/x-protobuf` or `application/json`.
`503`	Temporary, including downstream ingestion outages. Your Collector should retry from its queue.

The OTLP receiver never returns 403. Treat a 403 from another hop, such as a CDN or WAF, as a configuration error, not a missing Amplitude enablement.

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