> ## 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. # Request Logs: Span Attributes > Reference for span attributes captured in AI Gateway request logs, including model, token usage, and request metadata fields. ## Understanding Span Attributes Each span you query from LLM Gateway captures key request and model details. Recognizing these attributes helps you analyze and debug usage effectively. ### Core Span Attributes | Attribute | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tfy.span_type` | Type of span, with possible values:
• `"ChatCompletion"` - Complete chat request lifecycle
• `"Completion"` - Text completion requests without chat context
• `"MCP"` - Model Context Protocol server interactions and tool calls
• `"Rerank"` - Document reranking operations for search relevance
• `"Embedding"` - Vector embedding generation operations
• `"Model"` - Actual LLM model inference processing
• `"AgentResponse"` - Multi-tool agent orchestration workflows
• `"Guardrail"` - Safety, compliance, and content validation checks | | `tfy.input` | Complete input data sent to the model, mcp\_server, guardrail, etc.. | | `tfy.output` | Complete output response from the model, mcp\_server, guardrail, etc.. | | `tfy.input_short_hand` | Abbreviated version of the input for display purposes | | `tfy.error_message` | Error message if the request failed | | `tfy.prompt_version_fqn` | FQN of the prompt version used (if applicable) | | `tfy.prompt_variables` | Variables used in prompt templating | | `tfy.triggered_guardrail_fqns` | String array of the fully qualified names of the guardrails that were triggered during the request. Emitted on `ChatCompletion`, `AgentResponse`, and `MCPGateway` spans — see [Triggered guardrails on request spans](#triggered-guardrails-on-request-spans). | ### Request Context Attributes | Attribute | Description | | -------------------------------------- | ------------------------------------------------------------------------ | | `tfy.request.model_name` | Name of the model that was requested | | `tfy.request.created_by_subject` | Subject (user/service account) that made the request | | `tfy.request.created_by_subject_teams` | Teams associated with the requesting subject | | `tfy.request.metadata` | Additional metadata associated with the request (e.g., `{'foo': 'bar'}`) | | `tfy.request.conversation_id` | Unique identifier for the conversation (if part of a chat) | ### Model Attributes | Attribute | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `tfy.model.id` | Unique identifier of the model | | `tfy.model.name` | Display name of the model | | `tfy.model.fqn` | Fully qualified name of the model | | `tfy.model.request_url` | URL endpoint used for the model request | | `tfy.model.streaming` | Whether the request used streaming mode | | `tfy.model.request_type` | Type of request (e.g., `"ChatCompletion", "Completion", "Embedding", "Rerank", "AgentResponse", "MCPGateway", "CreateModelResponse"`) | | `tfy.model.metric.cache_read_input_tokens` | Number of input tokens served from the cache, billed at a lower cache read rate instead of the standard input rate | | `tfy.model.metric.cache_creation_input_tokens` | Number of input tokens written to the cache, billed at a higher cache write rate to cover the cost of storage | ### Model Performance Metrics | Attribute | Description | | -------------------------------------------- | ------------------------------------------------- | | `tfy.model.metric.time_to_first_token_in_ms` | Time taken to receive the first token (streaming) | | `tfy.model.metric.latency_in_ms` | Total request latency in milliseconds | | `tfy.model.metric.input_tokens` | Number of tokens in the model input | | `tfy.model.metric.output_tokens` | Number of tokens in the model output | | `tfy.model.metric.cost_in_usd` | Cost of the request in USD | | `tfy.model.metric.inter_token_latency_in_ms` | Average latency between tokens (streaming) | ### Load Balancing Attributes | Attribute | Description | | ------------------------------ | -------------------------------------------------------------------------- | | `applied_loadbalance_rule_ids` | IDs of load balancing rules that were applied (e.g., `['gpt-4-dev-load']`) | ### Budget Control Attributes | Attribute | Description | | ------------------------- | -------------------------------------------------------------------------------------------------- | | `applied_budget_rule_ids` | IDs of budget rules that were applied to this request (e.g., `['virtualaccount1-monthly-budget']`) | ### Rate Limiting Attributes | Attribute | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------- | | `applied_ratelimit_rule_ids` | IDs of all rate limiting rules that were applied (e.g., `['virtualaccount1-daily-ratelimit']`) | ### MCP (Model Context Protocol) Server Attributes | Attribute | Description | | --------------------------------------------- | ---------------------------------------------- | | `tfy.mcp_server.id` | Unique identifier of the MCP server | | `tfy.mcp_server.name` | Display name of the MCP server | | `tfy.mcp_server.url` | URL endpoint of the MCP server | | `tfy.mcp_server.fqn` | Fully qualified name of the MCP server | | `tfy.mcp_server.server_name` | Internal name of the MCP server | | `tfy.mcp_server.method` | MCP method that was called | | `tfy.mcp_server.primitive_name` | Name of the MCP primitive used | | `tfy.mcp_server.error_code` | Error code if the MCP call failed | | `tfy.mcp_server.is_tool_call_execution_error` | Whether the error was from tool call execution | ### MCP Server Metrics | Attribute | Description | | --------------------------------------- | ---------------------------------------------- | | `tfy.mcp_server.metric.latency_in_ms` | Latency of the MCP server call in milliseconds | | `tfy.mcp_server.metric.number_of_tools` | Number of tools available in the MCP server | ### Guardrail Attributes | Attribute | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------ | | `tfy.guardrail.id` | Unique identifier of the guardrail | | `tfy.guardrail.name` | Display name of the guardrail | | `tfy.guardrail.fqn` | Fully qualified name of the guardrail | | `tfy.guardrail.result` | Outcome of the guardrail check. See the value table below. | | `tfy.guardrail.enforcing_strategy` | The enforcement strategy the guardrail ran under: `enforce`, `enforce_but_ignore_on_error`, or `audit` | #### Guardrail result values | Value | Meaning | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `flag` | The guardrail flagged the content and the request was blocked | | `error` | The guardrail failed to run and the request was blocked. Only possible under the `enforce` strategy | | `mutation` | The guardrail modified the content, for example by redacting or masking it | | `ignored_error` | The guardrail failed to run but the request continued. This is what an error becomes under `enforce_but_ignore_on_error` and `audit` | | `pass` | The guardrail ran and raised nothing. Appears on individual `Guardrail` spans only | | `audit_mode_flag` | The guardrail would have blocked, but ran in `audit` mode so the request continued. Appears on individual `Guardrail` spans only | #### Triggered guardrails on request spans Individual guardrail checks each get their own `Guardrail` child span. Their outcomes are also rolled up onto the enclosing request span, so you can find requests affected by a guardrail without expanding the trace. The roll-up sets both `tfy.triggered_guardrail_fqns` and `tfy.guardrail.result`, and applies to `ChatCompletion`, `AgentResponse`, and `MCPGateway` spans. A few things to know when querying it: * **`pass` and `audit_mode_flag` are not rolled up.** Only outcomes that actually affected the request appear — `flag`, `error`, `mutation`, and `ignored_error`. A request whose guardrails all passed carries neither attribute. * **Errors are included on purpose**, so a guardrail that failed to run is distinguishable from one that ran and passed. * **`tfy.guardrail.result` on a request span is a single worst-case value.** When several guardrails trigger, precedence is `flag` > `error` > `mutation` > `ignored_error`. Per-guardrail detail stays on the `Guardrail` child spans. * **Each guardrail appears once** in `tfy.triggered_guardrail_fqns`. A guardrail that triggers on both input and output is deduplicated, keeping its most severe outcome. * The roll-up does not extend to other request types. Endpoints such as `/v1/messages`, `/v1/responses`, embeddings, and rerank still run guardrails and still record `Guardrail` child spans, but emit no request-span roll-up. Query the child spans for those. The child `Model` span does not carry these attributes either. For a `/chat/completions` request the roll-up lives on the `ChatCompletion` root span, not on the `Model: ` span beneath it. ### Guardrail Applied Entity Attributes | Attribute | Description | | --------------------------------------- | ------------------------------------------- | | `tfy.guardrail.applied_on_entity.type` | Type of entity the guardrail was applied to | | `tfy.guardrail.applied_on_entity.id` | ID of the entity | | `tfy.guardrail.applied_on_entity.name` | Name of the entity | | `tfy.guardrail.applied_on_entity.fqn` | FQN of the entity | | `tfy.guardrail.applied_on_entity.scope` | Scope of the entity | ### Guardrail Metrics | Attribute | Description | | ------------------------------------ | -------------------------------------------------- | | `tfy.guardrail.metric.latency_in_ms` | Time taken for the guardrail check in milliseconds | ### HTTP Response Attributes | Attribute | Description | | --------------------------- | -------------------------------- | | `http.response.status_code` | HTTP status code of the response | ## GenAI attributes The gateway can also dual-write [OpenTelemetry GenAI semantic convention](https://opentelemetry.io/docs/specs/semconv/gen-ai/) attributes (`gen_ai.*`). See [GenAI span attributes](/docs/ai-gateway/fetch-request-logs-span-attributes-genai) for enabling the feature, the full attribute mapping, content/privacy behavior, and current limitations. ## References * [GenAI span attributes](/docs/ai-gateway/fetch-request-logs-span-attributes-genai) * [Query Spans API](/docs/truefoundry_sdk/traces#query-spans) * [`query_spans` method in TrueFoundry SDK](/docs/truefoundry_sdk/traces#query-spans)