Span and Resource Attributes

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 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 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 common cross-framework concepts (tokens, agent and tool names, span type) that Fiddler recognizes automatically. They are registered in the attribute catalog and can be referenced in FQL custom metrics — by semantic_name (the recommended, framework-independent form) or by their verbatim key. Some are also available as dedicated span columns for fast filtering (via Span:: redirects); the rest are filtered via SpanAttribute::.

Attribute	Type	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 Explorer. They are not registered in the attribute catalog and cannot be used in FQL custom metrics.

Attribute	Type	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 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 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 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))

For a copy-pastable 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
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()` to define computed metrics over span attributes
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. Reference an attribute by its verbatim key (exactly as your application emits it) or by its semantic_name (a canonical concept that Fiddler resolves across frameworks). See Attribute Quick Overview for the full classification.

attribute('verbatim_key')
attribute(semantic_name='input_tokens')
attribute('status', value='error')

As of release 26.16, you provide exactly one of name or semantic_name, and the scope and type arguments are optional — they default to 'span' and 'user'. The value argument filters to spans where the attribute equals a given string, for categorical breakdowns. See Custom Metrics for Agentic Applications for the full parameter reference and the supported semantic concepts. System attribute examples — reference recognized concepts by semantic_name, so the metric works regardless of which framework emitted the trace:

-- Average input tokens per span
average(attribute(semantic_name='input_tokens'))

-- Count spans by agent name
count(attribute(semantic_name='agent_name', value='my-agent'))

-- Ratio of LLM spans
count(attribute(semantic_name='span_type', value='llm'))
  / count(attribute(semantic_name='span_type'))

User attribute examples — reference custom fiddler.span.user.* attributes by their verbatim key:

-- P95 of a custom latency attribute
quantile(attribute('response_time_ms'), level=0.95)

-- Ratio of premium-tier spans
count(attribute('tier', value='premium'))
  / count(attribute('tier'))

See Custom Metrics for the full FQL reference and more examples.

Attribute Quick Overview

All attributes listed below are visible in the Explorer. The Custom metrics and Explorer filter columns indicate additional availability for FQL and UI filtering respectively. The 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	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	—	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 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.

Deprecated Prefix Conventions

The fiddler.* prefix conventions on this page predate semantic mappings. They still work, but they are no longer the recommended way to instrument new applications.

The fiddler.span.system.*, fiddler.span.user.*, and fiddler.contents.* prefix conventions described on this page are deprecated. Semantic mappings are now the default mechanism for resolving span attributes and are the recommended approach for all new instrumentation.

In the semantic mapping 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 continues to work — the default mappings include entries for all legacy prefixed keys, so both old and new data resolve to the same semantic concepts. New instrumentation should send attribute keys in their native framework format and rely on semantic mappings rather than adopting the fiddler.* prefixes. For more details, see Semantic Mappings.

Semantic Mappings — how Fiddler maps raw attribute keys to canonical concepts across frameworks
OTel Trace Export — protobuf serialization and attribute mapping for client-side export
OpenTelemetry Integration — live agent instrumentation via the OTel SDK
Custom Metrics — define FQL metrics over span attributes
Fiddler OTel SDK — @trace decorator and set_attribute() usage
Agentic AI Overview — compare all integration options

Agentic AI & LLM Frameworks

Data Platforms & Pipelines

ML Platforms & Tools

Cloud Platforms & Deployment

Monitoring & Alerting

Overview

Attribute Levels

Required Attributes

System Attributes

Identity Attributes

Content Attributes

LLM Content

Tool Content

Custom User Attributes

Attribute Value Types

SDK usage (high-level)

Protobuf usage (low-level)

How Attributes Flow into Fiddler

Querying attributes with FQL

Attribute Quick Overview

Deprecated Prefix Conventions

​Overview

​Attribute Levels

​Required Attributes

​System Attributes

​Identity Attributes

​Content Attributes

​LLM Content

​Tool Content

​Custom User Attributes

​Attribute Value Types

​SDK usage (high-level)

​Protobuf usage (low-level)

​How Attributes Flow into Fiddler

​Querying attributes with FQL

​Attribute Quick Overview

​Deprecated Prefix Conventions

​Related Documentation

Overview

Attribute Levels

Required Attributes

System Attributes

Identity Attributes

Content Attributes

LLM Content

Tool Content

Custom User Attributes

Attribute Value Types

SDK usage (high-level)

Protobuf usage (low-level)

How Attributes Flow into Fiddler

Querying attributes with FQL

Attribute Quick Overview

Deprecated Prefix Conventions

Related Documentation