> ## Documentation Index > Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt > Use this file to discover all available pages before exploring further. # GenAI Span Attributes > OpenTelemetry GenAI semantic convention attributes dual-written by the LLM Gateway alongside TrueFoundry span attributes. The LLM Gateway can also emit attributes that follow the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (`gen_ai.*`), alongside related standard OTel attributes such as `error.type` and `server.*`. This lets GenAI-aware observability platforms — and any collector that understands the GenAI conventions — consume gateway traces without a TrueFoundry-specific attribute translator, and lets you join gateway spans with spans your own SDK instrumentation already produces. This is a **dual-write**: `gen_ai.*` attributes are added in addition to the [`tfy.*` attributes](/docs/ai-gateway/fetch-request-logs-span-attributes). No `tfy.*` attribute is removed or renamed, so existing dashboards, queries, and integrations continue to work unchanged. Gateway-specific concepts that have no GenAI equivalent — cost in USD, tenant and subject, semantic cache, guardrails, load balancing, budgets, and rate limits — remain available only under `tfy.*`. ## Enabling GenAI Attributes This feature is behind a feature flag and is **off by default**. To turn it on, set the following environment variable on your `tfy-llm-gateway` deployment and restart it: ```bash theme={"dark"} ENABLE_GEN_AI_OTEL_ATTRIBUTES=true ``` The OpenTelemetry GenAI semantic conventions are still in development upstream, so attribute names may change in future releases. `tfy.*` attributes remain the stable source of truth. ## Attribute Mapping Each `gen_ai.*` attribute is written only when the corresponding source data is present on the span. The sampling parameters (`gen_ai.request.temperature` through `gen_ai.request.presence_penalty`) are extracted from the request body and appear on model spans only. | GenAI attribute | Derived from | Description | | ------------------------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gen_ai.operation.name` | `tfy.model.request_type`, `tfy.span_type` | Operation being performed: `chat`, `embeddings`, `text_completion`, `generate_content`, `invoke_agent`, or `image_generation` | | `gen_ai.provider.name` | `tfy.model.provider_integration_type` | Normalized provider name (e.g. `openai`, `anthropic`, `aws.bedrock`, `azure.ai.openai`, `gcp.vertex_ai`). Unrecognized integrations fall back to the integration slug | | `gen_ai.workflow.name` | `tfy.span_type` | Span type, exposed as the GenAI workflow name | | `gen_ai.conversation.id` | `tfy.request.conversation_id` | Conversation identifier | | `gen_ai.output.type` | `tfy.model.request_type`, `tfy.span_type` | Set to `image` for image generation requests | | `gen_ai.request.model` | `tfy.model.name`, `tfy.model.requested_model_name` | Model requested by the client | | `gen_ai.response.model` | `tfy.model.provider_model_name` | Model name reported by the provider | | `gen_ai.request.stream` | `tfy.model.streaming` | Written only when the request was streaming | | `gen_ai.request.temperature` | request body `temperature` | Sampling temperature | | `gen_ai.request.max_tokens` | request body `max_tokens` / `max_completion_tokens` | Maximum tokens requested | | `gen_ai.request.top_p` | request body `top_p` | Nucleus sampling parameter | | `gen_ai.request.top_k` | request body `top_k` | Top-k sampling parameter | | `gen_ai.request.seed` | request body `seed` | Sampling seed | | `gen_ai.request.stop_sequences` | request body `stop` | Stop sequences, normalized to a list | | `gen_ai.request.frequency_penalty` | request body `frequency_penalty` | Frequency penalty | | `gen_ai.request.presence_penalty` | request body `presence_penalty` | Presence penalty | | `gen_ai.response.id` | response body `id` | Provider response identifier | | `gen_ai.response.finish_reasons` | response body `choices[].finish_reason` | List of finish reasons across choices | | `gen_ai.response.time_to_first_chunk` | `tfy.model.metric.time_to_first_token_in_ms` | Time to first chunk, converted from milliseconds to **seconds** | | `gen_ai.usage.input_tokens` | `tfy.model.metric.input_tokens` | Input token count | | `gen_ai.usage.output_tokens` | `tfy.model.metric.output_tokens` | Output token count | | `gen_ai.usage.total_tokens` | derived | Sum of input and output tokens. Emitted when either count is present, treating the missing one as `0`. Not part of the current GenAI registry; emitted as a convenience | | `gen_ai.usage.cache_read.input_tokens` | `tfy.model.metric.cache_read_input_tokens` | Input tokens served from the provider prompt cache | | `gen_ai.usage.cache_creation.input_tokens` | `tfy.model.metric.cache_creation_input_tokens` | Input tokens written to the provider prompt cache | | `gen_ai.usage.reasoning.output_tokens` | `tfy.model.metric.thoughts_tokens` | Reasoning / thinking tokens. Currently populated only on realtime/WebSocket turn spans | | `gen_ai.prompt.name` | `tfy.prompt_version_fqn` | FQN of the prompt version used | | `gen_ai.input.messages` | `tfy.input` | Request messages in GenAI message format. Subject to prompt logging and redaction rules | | `gen_ai.output.messages` | `tfy.output` | Response messages in GenAI message format, including per-choice `finish_reason`. Subject to prompt logging and redaction rules | | `error.type` | `tfy.error_type` | Standard OTel error type (not under `gen_ai.*`). Note that client-disconnect spans set `error.type` regardless of this flag | | `server.address` | `tfy.model.request_url` | Hostname of the provider endpoint | | `server.port` | `tfy.model.request_url` | Port of the provider endpoint, defaulting to 443 for HTTPS and 80 for HTTP | ## Content and Privacy `gen_ai.input.messages` and `gen_ai.output.messages` are derived from `tfy.input` and `tfy.output` **after** redaction has been applied, so redaction rules carry over. If prompt logging is disabled, the source attributes are removed and these GenAI attributes are absent entirely. Payload-size limits are applied afterwards and evaluated independently for each attribute. If a message payload exceeds the limit, the attribute is present but set to the sentinel value `{ "__skipped_large_payload": true }` rather than being dropped. Because the GenAI message format adds wrapping JSON, `gen_ai.input.messages` can be skipped for size while `tfy.input` is still retained. ## Current Limitations The initial release covers inference-critical fields on model and root spans, though some attributes are narrower than that — see the notes in the mapping table. Agent attributes (`gen_ai.agent.*`), tool call attributes (`gen_ai.tool.*`), retrieval attributes, and MCP attributes (`mcp.*`) are not yet dual-written — that data remains available under `tfy.agent.*`, `tfy.model.tool_calls`, and `tfy.mcp_server.*`. Prometheus metric labels are unaffected by this flag and continue to use TrueFoundry names. ## References * [Span attributes](/docs/ai-gateway/fetch-request-logs-span-attributes) * [Query Spans API](/docs/truefoundry_sdk/traces#query-spans) * [`query_spans` method in TrueFoundry SDK](/docs/truefoundry_sdk/traces#query-spans)