Span Attributes

Every GenAI span emitted by the gateway follows the OpenTelemetry GenAI semantic conventions. The span name follows the pattern {operation} {model} (e.g. chat gpt-4o, embeddings text-embedding-3-small). This page is the complete catalog of every span attribute that may appear on your GenAI spans. Attributes are grouped by category: core GenAI semantics, routing, experimentation, client context, and caching. For how to configure and export your telemetry, see Telemetry Overview.

​

Conventions used in this reference

• Type column uses OTel attribute types: string, int, float, bool.
• string (JSON) denotes a string attribute whose value is a JSON-encoded structure.
• string (JSON array) denotes a string attribute whose value is a JSON array.
• “When set” means the attribute is omitted entirely when the source value is absent; it is never recorded as empty or zero.
• Attributes in the gen_ai.* namespace follow the OTel GenAI semantic conventions. Attributes in the gateway.* namespace are gateway-specific extensions.

​

Endpoint instrumentation matrix

Not every endpoint produces GenAI telemetry. The table below shows which endpoints emit GenAI spans and metrics versus plain HTTP spans only. Endpoints marked “No” under GenAI Span still produce standard HTTP spans. Media endpoints (images/generations, audio/speech, audio/transcriptions) do not report token usage metrics. Only gen_ai.client.operation.duration is recorded for those endpoints.

​

Always present

These four attributes appear on every GenAI span regardless of endpoint, provider, or request shape. They form the minimum set required for basic filtering and grouping in any trace backend.

​

Request parameters (when set)

These attributes are recorded only when the corresponding parameter is present in the request body. Absent parameters produce no attribute rather than a zero or null value.

​

Response attributes

Populated after the upstream provider returns a response (or after the final streaming chunk). For streaming requests, token counts and finish reasons are extracted from the terminal usage chunk when the provider includes one, or accumulated from individual deltas otherwise. The gen_ai.response.model attribute is particularly useful when the request specifies an alias (e.g. gpt-4o) and the provider resolves it to a specific snapshot (e.g. gpt-4o-2024-08-06).

​

Advanced token types

Provider-specific token breakdowns beyond standard input/output counts. These attributes supplement gen_ai.usage.input_tokens and gen_ai.usage.output_tokens with finer-grained detail where the upstream provider supports it. When Anthropic cache tokens are present, the relationship between token counts is:

• gen_ai.usage.input_tokens = total input tokens (includes both cached and non-cached)
• gen_ai.usage.cache_read.input_tokens = subset of input tokens served from cache
• gen_ai.usage.cache_creation.input_tokens = tokens newly written to cache (aggregate)
• gen_ai.usage.cache_creation_5m.input_tokens = 5-minute TTL portion of cache creation (when Anthropic sends TTL breakdown)
• gen_ai.usage.cache_creation_1h.input_tokens = 1-hour TTL portion of cache creation (when Anthropic sends TTL breakdown)

When both the aggregate and TTL-specific breakdown are present, cache_creation.input_tokens equals the sum of cache_creation_5m.input_tokens + cache_creation_1h.input_tokens. The gateway passes all fields through as-is from the provider. For OpenAI reasoning models, gen_ai.usage.reasoning_tokens is separate from gen_ai.usage.output_tokens. Reasoning tokens represent internal chain-of-thought computation and are billed separately by the provider.

​

Embeddings attributes

Emitted on embeddings operation spans when the corresponding value is available.

​

Server performance attributes

Per-request performance attributes recorded on completed operation spans. These use the gen_ai.server.* namespace. gen_ai.server.time_to_first_token and gen_ai.server.request.duration are recorded on every completed operation span, streaming or not. The baseline lifecycle path also stamps gen_ai.server.time_to_first_token on cache hits, embeddings, audio, and image spans. These are per-span attributes. A few have a matching aggregate metric under a different name — for instance, the span attribute gen_ai.server.output_tokens_per_second is published as the metric gen_ai.client.output_tokens_per_second.

​

Output type

Indicates the modality of the response produced by the operation. The value is determined by the endpoint and, for chat endpoints, by the requested response format. The mapping from endpoint to output type is: For chat endpoints, the value is json when the request specifies a JSON object or JSON schema response format, and text otherwise. Audio transcription produces text, since the response is transcribed text rather than audio.

​

Server address

Identifies the upstream provider endpoint the gateway connected to. These follow the OTel server.* namespace conventions.

​

Error attributes

Present when the upstream call fails or times out. A span with error attributes always has its OTel status set accordingly. The span StatusCode is set to ERROR and StatusMessage contains the error detail string. On successful requests, StatusCode remains UNSET and no error.type attribute is recorded. Transport-level error type values: Other paths record their own error.type categories, including rate_limit (gateway rate limit), guardrail_violation (a guardrail blocked the request), and the retrieval-error value declared via x-to11-context-retrieval-error on a retrieval span. Domain-level routing failures (for example unknown_model, no_matching_route, all_targets_failed) carry their own category strings. Provider-returned error bodies are not captured as span attributes. The StatusMessage contains a summary suitable for filtering and alerting.

​

Session and user metadata

Populated from request headers or body fields. All attributes in this group are optional and appear only when the corresponding header or field is present. These attributes enable grouping spans by user, session, or conversation for analytics and debugging. When both the x-to11-user-id header and the user body field are present, the header takes precedence. The gen_ai.user.id attribute lets you group and filter spans by user or session when you explore your traces.

​

Tool call child spans

When a model response includes tool calls, the gateway emits child spans nested under the GenAI operation span. Each tool call produces one child span. The parent-child relationship is visible in any trace viewer that supports nested spans. Span name: tool_call.{function_name} (e.g. tool_call.get_weather) The gen_ai.tool.definitions attribute (string, JSON array) appears on the parent span, not on tool call child spans. It contains the tool/function definitions sent in the request when capture_content is enabled. Multiple tool calls within a single response each produce their own child span. The child spans share the same parent span ID as the GenAI operation span. If a response contains no tool calls, no child spans are created.

​

Timing behavior

In the non-streaming case, the gateway cannot observe when individual tool calls were generated. The synthetic timestamp distribution ensures that tool call spans are evenly spaced within the parent span’s duration, providing a reasonable approximation for visualization in trace viewers.

​

Gateway routing attributes

Present on spans that traverse the gateway’s managed routing layer. These attributes use the gateway.* namespace, which is specific to the to11 gateway and not part of the OTel semantic conventions. Passthrough requests carry gateway.routing.path = "passthrough" and omit the remaining routing attributes. For fallback strategies, the gateway.routing.attempt attribute increments with each retry. The first attempt is 1. Combined with gateway.routing.target, this allows reconstruction of the full fallback chain from span data.

​

Provider qualifier attributes

Emitted on the operation span when the resolved provider configuration carries the corresponding qualifier. These attributes use the gen_ai.provider.* namespace and distinguish between multiple provider configurations that map to the same gen_ai.provider.name. Each attribute is omitted when the resolved configuration does not define it. gen_ai.provider.config_key disambiguates multiple config entries that resolve to the same canonical gen_ai.provider.name.

​

Experiment and variant attributes

Present when the request is routed through a function variant. These attributes record which variant was selected and the weight distribution at the time of the request. Each attribute is emitted only when the route resolution carries the corresponding value; gateway.experiment.total_variants reflects the number of variants defined on the function. Variant selection is determined at request time based on the configured weights. The gateway.variant.weight attribute records the weight of the selected variant, not the probability. To compute the selection probability, divide by the sum of all variant weights (derivable from the total variants and their individual weights across spans).

​

Client-context operation attributes

These attributes appear on sibling spans created via x-to11-context-* headers. Each header value generates a separate span adjacent to the main GenAI operation span, sharing the same parent trace context. The span name matches the operation type (e.g. execute_tool, retrieval, invoke_agent, create_agent).

​

execute_tool spans

​

retrieval spans

​

invoke_agent / create_agent spans

The invoke_agent and create_agent span types differ in their attribute sets. gen_ai.agent.step tracks the execution step within an agent invocation, while gen_ai.agent.description records the agent definition at creation time. Both share gen_ai.agent.id and gen_ai.agent.name.

​

Content capture attributes

Recorded when content capture is enabled, which it is by default. These attributes contain the full prompt and completion text as serialized JSON. Streaming responses are accumulated up to a 64 KB limit; non-streaming responses are captured in full. See Content Capture for how it’s controlled. For media endpoints, content capture behavior varies:

​

Cache status attributes

Present when the gateway evaluates its response cache for the request. The skip status indicates that the cache was not consulted for a hit because cache directives disabled, bypassed, or write-only-gated this request. On a cache hit, the gateway skips the upstream provider call entirely. The span still records gen_ai.response.model and token usage attributes from the cached response. The gen_ai.cache.age_seconds attribute indicates staleness, allowing cache freshness analysis across requests. Cache status values: