> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fiddler.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Span and Resource Attributes

> Understand how Fiddler uses span and resource attributes from OpenTelemetry traces — required vs optional fields, typing, custom attributes, and how attributes flow into metrics, alerts, and dashboards.

## Overview

<Info>
  Use this page as a reference for which attributes Fiddler indexes, how to type their values, and how they map to FQL `attribute()` and `Span::` filters.
</Info>

Attributes are key-value pairs attached to OpenTelemetry spans and resources. They carry the data that powers Fiddler's dashboards, alerts, evaluators, and custom metrics.

Getting attributes right means:

* **Attributes** are present in OpenTelemetry spans.
* **Values use the correct type** so numeric attributes are aggregatable and alertable (not silently treated as strings).
* **Custom attributes** follow the naming convention so they appear in the trace explorer and are queryable via FQL.

This page is the single reference for how attributes work across all Fiddler integrations.

***

## Attribute Levels

Attributes are set at two levels in the OTLP hierarchy:

| Level        | Scope                                | Set on                | Example                                     |
| ------------ | ------------------------------------ | --------------------- | ------------------------------------------- |
| **Resource** | Entire trace (all spans share these) | `Resource.attributes` | `application.id`                            |
| **Span**     | Individual operation                 | `Span.attributes`     | `fiddler.span.type`, `gen_ai.request.model` |

***

## Required Attributes

These must be present on every trace sent to Fiddler. Fiddler rejects traces that omit either field.

| Attribute           | Level    | Description                                           |
| ------------------- | -------- | ----------------------------------------------------- |
| `application.id`    | Resource | Your Fiddler application UUID (UUID4 format)          |
| `fiddler.span.type` | Span     | Type of operation: `llm`, `tool`, `chain`, or `agent` |

***

## System Attributes

System attributes are stored under the `fiddler.span.system.*` prefix internally. They are registered in the attribute catalog and available for FQL custom metrics via `attribute('...', type='system', scope='span')`. Some are also available as dedicated span columns for fast filtering (via `Span::` redirects); the rest are filtered via `SpanAttribute::`.

| Attribute                    | Type   | Trace explorer filter                                                               | Description                                                |
| ---------------------------- | ------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `gen_ai.agent.name`          | string | Agent (`Span::agent_name`)                                                          | Name of the AI agent                                       |
| `fiddler.span.type`          | string | Type (`Span::span_type`)                                                            | Type of operation: `llm`, `tool`, `chain`, or `agent`      |
| `gen_ai.tool.name`           | string | gen\_ai.tool.name (system) (`SpanAttribute::gen_ai.tool.name`)                      | Tool or function name                                      |
| `gen_ai.usage.input_tokens`  | int    | gen\_ai.usage.input\_tokens (system) (`SpanAttribute::gen_ai.usage.input_tokens`)   | Input tokens consumed                                      |
| `gen_ai.usage.output_tokens` | int    | gen\_ai.usage.output\_tokens (system) (`SpanAttribute::gen_ai.usage.output_tokens`) | Output tokens consumed                                     |
| `gen_ai.usage.total_tokens`  | int    | gen\_ai.usage.total\_tokens (system) (`SpanAttribute::gen_ai.usage.total_tokens`)   | Total tokens consumed                                      |
| `latency`                    | int    | Duration (`Span::duration`)                                                         | Span duration (computed automatically from start/end time) |

***

## Identity Attributes

Identity attributes are stored as metadata internally and materialized into dedicated span columns. They appear as **Session ID** and **Agent ID** columns in the trace explorer. They are **not** registered in the attribute catalog and cannot be used in FQL custom metrics.

| Attribute                | Type   | Trace explorer filter           | Description                                 |
| ------------------------ | ------ | ------------------------------- | ------------------------------------------- |
| `gen_ai.conversation.id` | string | Session ID (`Span::session_id`) | Groups spans into a multi-turn conversation |
| `gen_ai.agent.id`        | string | Agent ID (`Span::agent_id`)     | Unique identifier for the agent             |

<Info>
  **Set agent attributes on every span.** If you provide `gen_ai.agent.name` or `gen_ai.agent.id`, set them on **every span within the trace**. Fiddler uses these to attribute spans to the correct agent — spans missing these fields will be unattributed even if other spans in the same trace carry them.
</Info>

***

## Content Attributes

These attributes are visible in the trace explorer but are **not** registered as queryable attributes — they cannot be used in FQL custom metrics or span filters.

### LLM Content

| Attribute                 | Type   | Description                                  |
| ------------------------- | ------ | -------------------------------------------- |
| `gen_ai.request.model`    | string | Model name (e.g., `gpt-4o`, `claude-3-opus`) |
| `gen_ai.system`           | string | LLM provider (e.g., `openai`, `anthropic`)   |
| `gen_ai.llm.input.system` | string | System prompt                                |
| `gen_ai.llm.input.user`   | string | User input (last user message)               |
| `gen_ai.llm.output`       | string | LLM response text                            |
| `gen_ai.llm.context`      | string | Conversation history (prior messages)        |

### Tool Content

| Attribute            | Type          | Description                  |
| -------------------- | ------------- | ---------------------------- |
| `gen_ai.tool.input`  | string (JSON) | Arguments passed to the tool |
| `gen_ai.tool.output` | string (JSON) | Result returned by the tool  |

***

## Custom User Attributes

Attach business-level metadata to spans using two namespaces:

| Namespace                    | Scope                  | Description                                   |
| ---------------------------- | ---------------------- | --------------------------------------------- |
| `fiddler.span.user.{key}`    | Individual span        | Metadata for a specific operation             |
| `fiddler.session.user.{key}` | All spans in the trace | Session-wide context shared across every span |

`fiddler.span.user.*` attributes are indexed, appear as filterable columns in the trace explorer, and are available for [custom metrics](/observability/agentic/custom-metrics) via the FQL `attribute()` function. `fiddler.session.user.*` attributes are visible in the trace detail side panel only — they do not appear as columns in the trace explorer grid and are not available for custom metrics or filtering.

***

## Attribute Value Types

Under the hood, every attribute value is wrapped in an OTel `AnyValue` protobuf message. **Using the correct typed field is critical** — it determines whether Fiddler classifies the attribute as numeric (enabling aggregation, charting, and alerting) or string.

| Python type | `AnyValue` field | Fiddler storage type      |
| ----------- | ---------------- | ------------------------- |
| `str`       | `string_value`   | String                    |
| `int`       | `int_value`      | Numeric (stored as float) |
| `float`     | `double_value`   | Numeric (stored as float) |
| `bool`      | `bool_value`     | String                    |

<Warning>
  **Use `int_value` / `double_value` for numeric attributes.** If you wrap a number in `string_value` (e.g., `AnyValue(string_value="150")`), Fiddler treats it as a string column. You lose the ability to compute aggregations (sum, average, percentiles) and set numeric alerts on that attribute.
</Warning>

### SDK usage (high-level)

When using the Fiddler OTel SDK, LangGraph SDK, or Strands SDK, pass native Python types and the SDK handles typing automatically:

```python theme={null}
span.set_attribute("gen_ai.usage.input_tokens", 150)       # int → int_value
span.set_attribute("fiddler.span.user.confidence", 0.97)    # float → double_value
span.set_attribute("fiddler.span.user.region", "us-west")   # str → string_value
span.set_attribute("fiddler.span.user.is_internal", False)   # bool → bool_value
```

### Protobuf usage (low-level)

When building protobuf `Span` objects directly (e.g., for [OTel trace export](/integrations/agentic-ai/otel-trace-export)), you must set the correct `AnyValue` field explicitly:

```python theme={null}
from opentelemetry.proto.common.v1.common_pb2 import AnyValue, KeyValue

# Numeric — use int_value / double_value
KeyValue(key="gen_ai.usage.input_tokens",       value=AnyValue(int_value=150))
KeyValue(key="fiddler.span.user.confidence",    value=AnyValue(double_value=0.97))

# String
KeyValue(key="fiddler.span.user.region",        value=AnyValue(string_value="us-west"))

# Boolean
KeyValue(key="fiddler.span.user.is_internal",   value=AnyValue(bool_value=False))
```

For a copy-pastable `to_any_value()` helper that handles type dispatch automatically, see the [OTel Trace Export — AnyValue Typing](/integrations/agentic-ai/otel-trace-export#anyvalue-typing) section.

***

## How Attributes Flow into Fiddler

Once ingested, attributes power several Fiddler features:

| Feature                 | How attributes are used                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| **Trace Explorer**      | Filter, search, and group traces by any attribute                                              |
| **Dashboards & Charts** | Built-in charts use system attributes (tokens, latency); custom charts reference any attribute |
| **Custom Metrics**      | FQL expressions use `attribute('name', type, scope)` to define computed metrics                |
| **Alerts**              | Set threshold or anomaly alerts on numeric attributes (requires correct typing)                |
| **Evaluators**          | Enrichment evaluators can read span attributes as input context                                |

### Querying attributes with FQL

The `attribute()` function is the FQL primitive for referencing span data in custom metrics. Only `system` and `user` attributes are queryable — see [Attribute Quick Overview](#attribute-quick-overview) for the full classification.

```
attribute(name='name', type='system'|'user', scope='span'[, value='...'])
```

| Parameter | Required | Description                                                                                                                                                                                                                                              |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | Yes      | Attribute key. For `type='system'`, use the OTel key (e.g., `gen_ai.usage.input_tokens`). For `type='user'`, use the bare key without the `fiddler.span.user.` prefix (e.g., `confidence`, not `fiddler.span.user.confidence`).                          |
| `type`    | Yes      | `'system'` for system attributes (see [System Attributes](#system-attributes)), `'user'` for custom `fiddler.span.user.*` attributes                                                                                                                     |
| `scope`   | Yes      | Currently only `'span'` is supported                                                                                                                                                                                                                     |
| `value`   | No       | Filters to spans where the attribute equals this string value. When set, the attribute is treated as a string. Used with `count()` for categorical breakdowns (e.g., `count(attribute('fiddler.span.type', type='system', scope='span', value='llm'))`). |

**System attribute examples:**

```
-- Average input tokens per span
average(attribute('gen_ai.usage.input_tokens', type='system', scope='span'))

-- Count spans by agent name
count(attribute('gen_ai.agent.name', type='system', scope='span', value='my-agent'))

-- Ratio of LLM spans
count(attribute('fiddler.span.type', type='system', scope='span', value='llm'))
  / count(attribute('fiddler.span.type', type='system', scope='span'))
```

**User attribute examples:**

```
-- P95 of a custom latency attribute
quantile(attribute('response_time_ms', type='user', scope='span'), level=0.95)

-- Ratio of premium-tier spans
count(attribute('tier', type='user', scope='span', value='premium'))
  / count(attribute('tier', type='user', scope='span'))
```

See [Custom Metrics](/observability/agentic/custom-metrics) for the full FQL reference and more examples.

***

## Attribute Quick Overview

All attributes listed below are visible in the trace explorer. The **Custom metrics** and **Trace explorer filter** columns indicate additional availability for FQL and UI filtering respectively.

The trace explorer filter column shows both the UI column name (what you see in the DataGrid header) and the API filter field (used in programmatic `filter.rules[].field` requests). The UI automatically maps column filters to the API syntax.

| Attribute                    | Level    | Required | Custom metrics | Trace explorer filter                                                               | Type                                  | `AnyValue` field                                                                         |
| ---------------------------- | -------- | -------- | -------------- | ----------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
| `application.id`             | Resource | Yes      | —              | —                                                                                   | UUID string                           | `string_value`                                                                           |
| `gen_ai.agent.name`          | Span     | No       | `system`       | Agent (`Span::agent_name`)                                                          | string                                | `string_value`                                                                           |
| `fiddler.span.type`          | Span     | Yes      | `system`       | Type (`Span::span_type`)                                                            | `llm` \| `tool` \| `chain` \| `agent` | `string_value`                                                                           |
| `gen_ai.agent.id`            | Span     | No       | —              | Agent ID (`Span::agent_id`)                                                         | string                                | `string_value`                                                                           |
| `gen_ai.conversation.id`     | Span     | No       | —              | Session ID (`Span::session_id`)                                                     | string                                | `string_value`                                                                           |
| `gen_ai.tool.name`           | Span     | No       | `system`       | gen\_ai.tool.name (system) (`SpanAttribute::gen_ai.tool.name`)                      | string                                | `string_value`                                                                           |
| `gen_ai.usage.input_tokens`  | Span     | No       | `system`       | gen\_ai.usage.input\_tokens (system) (`SpanAttribute::gen_ai.usage.input_tokens`)   | int                                   | `int_value`                                                                              |
| `gen_ai.usage.output_tokens` | Span     | No       | `system`       | gen\_ai.usage.output\_tokens (system) (`SpanAttribute::gen_ai.usage.output_tokens`) | int                                   | `int_value`                                                                              |
| `gen_ai.usage.total_tokens`  | Span     | No       | `system`       | gen\_ai.usage.total\_tokens (system) (`SpanAttribute::gen_ai.usage.total_tokens`)   | int                                   | `int_value`                                                                              |
| `latency`                    | Span     | No       | `system`       | Duration (`Span::duration`)                                                         | int                                   | — (computed)                                                                             |
| `gen_ai.request.model`       | Span     | No       | —              | —                                                                                   | string                                | `string_value`                                                                           |
| `gen_ai.system`              | Span     | No       | —              | —                                                                                   | string (provider name)                | `string_value`                                                                           |
| `gen_ai.llm.input.system`    | Span     | No       | —              | —                                                                                   | string                                | `string_value`                                                                           |
| `gen_ai.llm.input.user`      | Span     | No       | —              | —                                                                                   | string                                | `string_value`                                                                           |
| `gen_ai.llm.output`          | Span     | No       | —              | —                                                                                   | string                                | `string_value`                                                                           |
| `gen_ai.llm.context`         | Span     | No       | —              | —                                                                                   | string                                | `string_value`                                                                           |
| `gen_ai.tool.input`          | Span     | No       | —              | —                                                                                   | string (JSON)                         | `string_value`                                                                           |
| `gen_ai.tool.output`         | Span     | No       | —              | —                                                                                   | string (JSON)                         | `string_value`                                                                           |
| `fiddler.span.user.*`        | Span     | No       | `user`         | \<key> (user) (`SpanAttribute::<key>`)                                              | any                                   | Use typed field matching the value (see [Attribute Value Types](#attribute-value-types)) |

<Warning>
  **Only `system` and `user` attributes support custom metrics.** Content fields (like `gen_ai.llm.output`, `gen_ai.request.model`) are visible in the trace explorer but cannot be used in FQL `attribute()` expressions or aggregations. Identity fields (`gen_ai.agent.id`, `gen_ai.conversation.id`) are filter-only. If you need to compute metrics over a non-queryable field, attach it as a `fiddler.span.user.*` custom attribute instead.
</Warning>

***

## Upcoming Changes

The `fiddler.span.system.*`, `fiddler.span.user.*`, and `fiddler.contents.*` prefix conventions described on this page are being phased out. In the new approach, Fiddler stores attribute keys exactly as sent by your application — no prefix transformation or renaming is required.

Instead of relying on prefix conventions, Fiddler uses **semantic mappings** to resolve raw attribute keys to canonical concepts (like `input_tokens`, `model_name`, `input`) in the backend. This enables cross-framework analytics without requiring any specific key naming conventions from your instrumentation. Fiddler ships with 140+ pre-configured mappings covering 13+ frameworks, and you can add custom mappings for unsupported frameworks or proprietary attribute names.

Existing data stored with `fiddler.*` prefixes will continue to work — the default mappings include entries for all legacy prefixed keys, so both old and new data resolve to the same semantic concepts.

For more details, see [Semantic Mappings](/concepts/semantic-mappings).

***

## Related Documentation

* [Semantic Mappings](/concepts/semantic-mappings) — how Fiddler maps raw attribute keys to canonical concepts across frameworks
* [OTel Trace Export](/integrations/agentic-ai/otel-trace-export) — protobuf serialization and attribute mapping for client-side export
* [OpenTelemetry Integration](/integrations/agentic-ai/opentelemetry-integration) — live agent instrumentation via the OTel SDK
* [Custom Metrics](/observability/agentic/custom-metrics) — define FQL metrics over span attributes
* [Fiddler OTel SDK](/integrations/agentic-ai/fiddler-otel-sdk) — `@trace` decorator and `set_attribute()` usage
* [Agentic AI Overview](/integrations/agentic-ai-and-llm-frameworks/agentic-ai) — compare all integration options