Overview
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.
- 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 |
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.
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 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 |
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.
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:
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), you must set the correct AnyValue field explicitly:
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))
to_any_value() helper that handles type dispatch automatically, see the 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 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), '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'))). |
-- 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'))
-- 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'))
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) |
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.
