> ## 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:<br />• `"ChatCompletion"` - Complete chat request lifecycle<br />• `"Completion"` - Text completion requests without chat context<br />• `"MCP"` - Model Context Protocol server interactions and tool calls<br />• `"Rerank"` - Document reranking operations for search relevance<br />• `"Embedding"` - Vector embedding generation operations<br />• `"Model"` - Actual LLM model inference processing<br />• `"AgentResponse"` - Multi-tool agent orchestration workflows<br />• `"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.error_type` | Gateway error classification when the span failed. See [Authorization vs missing model](#authorization-vs-missing-model) for `tfy-forbidden` vs `tfy-model-not-found`. Other common values include `tfy-rate-limit`, `tfy-budget-limit`, `request-failure`, `client-disconnected`, `ttft-timeout`, and `provider-stream-error`. Dual-written as `error.type` when [GenAI attributes](/docs/ai-gateway/fetch-request-logs-span-attributes-genai) are enabled |
| `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). |

#### Authorization vs missing model

A request for a model the caller cannot use and a request for a model that does not exist both return **HTTP 403** with the same client message (`…not authorized… or model does not exist`) and the same `error_origin_level` (`authorization`). That is intentional so the API does not reveal whether a model exists.

Use `tfy.error_type` on the **Model** span (not the root `ChatCompletion` / `Embedding` span) to tell them apart:

| `tfy.error_type` | Meaning |
| - | - |
| `tfy-forbidden` | The model exists. The user or virtual account is not allowed to use it |
| `tfy-model-not-found` | The requested model name is missing from the gateway catalog (typo, unpublished model, or wrong provider-account prefix) |

Do not use HTTP 403, `error_origin_level`, Prometheus `error_code`, or the Model Metrics `errorCode` field to separate these cases — those stay the same for both. Filter request logs on `tfy.error_type` ([example](/docs/ai-gateway/fetch-request-logs-use-cases-advanced#filter-missing-model-vs-forbidden-spans)), or Model Metrics on `errorType`.

### 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 |
| `tfy.model.tokens_estimated` | `true` when any part of the token usage was estimated rather than provider-reported — typical on a mid-stream client disconnect. See [Cancelled and disconnected streams](/docs/ai-gateway/cost-tracking#cancelled-and-disconnected-streams) |

### 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.cost_savings.prompt_cache_in_usd` | USD saved by provider prompt caching versus billing every input token at the uncached rate. Omitted when the request did not touch the prompt cache. Can be negative on cache-write-heavy requests. See [Cost Savings](/docs/ai-gateway/cost-savings) |
| `tfy.model.metric.cost_savings.auto_routing_estimated_in_usd` | USD saved by Auto Routing versus pricing the same tokens on the baseline (usually `complex`) model. `0` when the baseline served the request. Omitted when Auto Routing did not apply, the served bill is `$0`, or baseline pricing cannot be resolved |
| `tfy.model.cache.potential_cost_savings_in_usd` | USD saved by a gateway exact-match or semantic cache hit — the cost of the original cached request. Present on cache hits |
| `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.

<Note>
  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: <model>` span beneath it.
</Note>

### 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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.