OpenTelemetry GenAI compatibility

Send your application’s native OpenTelemetry GenAI spans to Future AGI over OTLP/HTTP to inspect model calls, token usage and parent-child relationships in Observe. Keep your existing instrumentation; you do not need a second instrumentor or a custom exporter.

This reference describes the collector mapping in Future AGI v1.58.0. For application setup, choose your integration guide or use the OpenInference guide for a standard OTLP exporter example.

Export settings

Configure your instrumentor’s OTLP/HTTP exporter with these values:

Setting	Value
Cloud trace endpoint	https://api.futureagi.com/tracer/v1/traces
Self-hosted trace endpoint	Your collector base URL followed by /v1/traces
Authentication headers	X-Api-Key and X-Secret-Key, using your Future AGI credentials
Resource attributes	project_name for the destination project and project_type=observe
Payload format	OTLP Protobuf (application/x-protobuf) or OTLP JSON (application/json)
HTTP compression	Uncompressed or Content-Encoding: gzip

Use the trace-specific endpoint setting when supplying the full URL; exporters that append /v1/traces to a base URL must receive only the base. Flush pending spans before a short-lived application exits, then open Observe and select your destination project.

Gzip and the deprecated GenAI token aliases below are supported in self-hosted v1.56.0 and later. For an older collector, upgrade; uncompressed exports with gen_ai.usage.input_tokens and gen_ai.usage.output_tokens avoid those compatibility differences.

Model, provider and token attributes

The collector reads aliases in the order shown, from left to right. For model and provider, the first non-empty string wins. For token counts, the first numeric value wins, including an explicit zero; numeric strings are also accepted.

Stored field	Attribute aliases, highest priority first
Model	llm.model_name, gen_ai.request.model, gen_ai.response.model, llm.request.model
Provider	gen_ai.provider.name, llm.system, gen_ai.system, llm.vendor, llm.provider
Input tokens	llm.token_count.prompt, gen_ai.usage.input_tokens, llm.usage.prompt_tokens, gen_ai.usage.prompt_tokens
Output tokens	llm.token_count.completion, gen_ai.usage.output_tokens, llm.usage.completion_tokens, gen_ai.usage.completion_tokens
Total tokens	llm.token_count.total, gen_ai.usage.total_tokens, llm.usage.total_tokens

The deprecated gen_ai.system, gen_ai.usage.prompt_tokens and gen_ai.usage.completion_tokens remain supported. Prefer the current gen_ai.provider.name, gen_ai.usage.input_tokens and gen_ai.usage.output_tokens names for new instrumentation.

If no total-token alias supplies a numeric value, the collector derives the total from input plus output tokens. If both request and response model names are present without llm.model_name, the request model is displayed; the response model remains in the span attributes.

When a span emits both naming conventions

Aliases on the same span are selected, not added. For example, a span containing both llm.token_count.prompt=3 and gen_ai.usage.input_tokens=3, with both corresponding output aliases set to 4, stores input 3, output 4 and a derived total of 7, not 14.

This does not deduplicate separate spans emitted by two instrumentors. Use one instrumentation path for each model call to avoid duplicate observations.

Span types and errors

An explicit span-kind attribute takes precedence over gen_ai.operation.name. The collector checks fi.span.kind, gen_ai.span.kind, llm.request.type and openinference.span.kind in that order. Recognized values such as AGENT, RETRIEVER, LLM and TOOL become the corresponding lowercase display types.

When no non-empty span-kind attribute is present, these operation names determine the display type:

gen_ai.operation.name	Display type
chat, generate_content, text_completion	llm
embeddings	embedding
execute_tool	tool
invoke	chain
invoke_agent, retrieval	unknown

Spans with unrecognized types still appear in the trace tree with their attributes and parent-child relationships. If you need agent or retriever filters, configure your instrumentation to emit a supported span-kind value; invoke_agent and retrieval alone do not supply those types.

An OpenTelemetry span status of ERROR is stored as ERROR, together with its status description. An exception event alone does not set the span’s status.

Privacy

Content capture is controlled by your instrumentor. Review prompt, response, tool and exception data before exporting to a shared project. Disable content capture in that instrumentor or redact sensitive fields in an OpenTelemetry Collector before export. Do not assume Future AGI SDK privacy variables apply to a third-party instrumentor, or that hiding message content also removes exception text from the status description.

Troubleshooting

• Token counts are zero. Check that the span contains numeric usage values under one of the supported aliases. A higher-priority zero overrides a lower-priority nonzero value. A failed model call may have no usage data. For deprecated-only token names on an older self-hosted collector, upgrade or use the current names.
• The model differs from the provider’s response. Check the alias order: llm.model_name and then gen_ai.request.model take precedence over gen_ai.response.model.
• An agent or retrieval span shows as unknown. Set a supported span-kind value in the existing instrumentation; do not add a second span solely to change its type.
• HTTP 401. Check both authentication headers and that the credentials belong to the destination workspace.
• HTTP 415. Send OTLP JSON or Protobuf with its matching content type. Use no compression or a single gzip layer, not another content encoding.
• HTTP 413 with gzip. Reduce the exporter batch size. The collector limits both compressed and decompressed request sizes.