# Span and Resource Attributes

## Overview

{% hint style="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.
{% endhint %}

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             |

{% hint style="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.
{% endhint %}

***

## 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](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/documentation/monitoring/agentic/custom-metrics.md) 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                    |

{% hint style="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.
{% endhint %}

### 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
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-and-llm-frameworks/agentic-ai/otel-trace-export.md)), you must set the correct `AnyValue` field explicitly:

```python
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-and-llm-frameworks/agentic-ai/otel-trace-export.md#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](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/documentation/monitoring/agentic/custom-metrics.md) 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)) |

{% hint style="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.
{% endhint %}

***

## Related Documentation

* [OTel Trace Export](/integrations/agentic-ai-and-llm-frameworks/agentic-ai/otel-trace-export.md) — protobuf serialization and attribute mapping for client-side export
* [OpenTelemetry Integration](/integrations/agentic-ai-and-llm-frameworks/agentic-ai/opentelemetry-integration.md) — live agent instrumentation via the OTel SDK
* [Custom Metrics](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/documentation/monitoring/agentic/custom-metrics.md) — define FQL metrics over span attributes
* [Fiddler OTel SDK](/integrations/agentic-ai-and-llm-frameworks/agentic-ai/fiddler-otel-sdk.md) — `@trace` decorator and `set_attribute()` usage
* [Agentic AI Overview](/integrations/agentic-ai-and-llm-frameworks/agentic-ai.md) — compare all integration options


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fiddler.ai/integrations/agentic-ai-and-llm-frameworks/agentic-ai/attributes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.