Span Attributes#

Span attributes are the key/value metadata payload attached to every span in Phoenix. They follow OpenInference semantic conventions (e.g. input.value, output.mime_type, llm.token_count.prompt) and are persisted as a single JSON blob in the database.

Storage: JSON Column on Span#

The Span ORM model stores attributes in a single attributes: Mapped[dict[str, Any]] column. The column uses the JsonDict custom TypeDecorator, which wraps JSON_ — a dialect-aware type alias that resolves to JSONB on both SQLite and PostgreSQL 1. JsonDict.process_bind_param guarantees a safe write: if the value is not a dict it is stored as {} rather than raising 2.

Attributes are always stored in nested form (e.g. {"input": {"value": "...", "mime_type": "text/plain"}}), not flat dot-notation. The unflatten / flatten helpers in phoenix/trace/attributes.py handle conversion when spans are received over OTLP.

Attribute Key Path Constants#

models.py pre-splits dotted OpenInference attribute names into path lists at module load time 3:

INPUT_MIME_TYPE = SpanAttributes.INPUT_MIME_TYPE.split(".") # ["input", "mime_type"]
INPUT_VALUE = SpanAttributes.INPUT_VALUE.split(".") # ["input", "value"]
OUTPUT_MIME_TYPE = SpanAttributes.OUTPUT_MIME_TYPE.split(".")
OUTPUT_VALUE = SpanAttributes.OUTPUT_VALUE.split(".")
METADATA = SpanAttributes.METADATA.split(".")

This pays the string-split cost once and makes SQL subscript expressions like cls.attributes[INPUT_VALUE] possible.

Hybrid Properties for Attribute Access#

The Span model exposes frequently-needed attribute sub-paths as @hybrid_property fields. Each has two sides 4:

• Instance side — calls get_attribute_value(self.attributes, KEY) to traverse the in-memory Python dict.
• Expression side — uses the SQLAlchemy JSON subscript operator cls.attributes[KEY] to push the lookup into SQL.

The *_first_101_chars variants avoid fetching large attribute values when only a preview is needed — the GraphQL input/output resolvers use these to prefetch a truncated snippet before lazy-loading the full value 5.

get_attribute_value Helper#

get_attribute_value (phoenix/trace/attributes.py) is the shared traversal utility used by hybrid property instance sides, the insertion layer, and the GraphQL resolvers. It accepts a key as either a dot-separated string or a pre-split sequence, iterates through intermediate keys requiring each to be a dict, and returns None on any missing or wrong-type intermediate 6.

Insertion Flow#

insert_span (db/insertion/span.py) stores span.attributes directly as the JSON dict — no transformation at this layer 7. Token-count attributes are extracted separately with get_attribute_value and stored in dedicated scalar columns for efficient aggregation 8.

Normalization happens earlier, in the OTLP decoding pipeline (phoenix/trace/otel.py):

1. Unflatten — dot-notation OTLP keys become nested dicts.
2. load_json_strings — METADATA, TOOL_PARAMETERS, DOCUMENT_METADATA, and LLM_PROMPT_TEMPLATE_VARIABLES are JSON-parsed from strings into dicts 9.
3. Non-string input coercion — if input.value is not a string, it is JSON-serialized and input.mime_type is automatically set to application/json 10.

MIME Type Handling#

input.mime_type and output.mime_type indicate how to interpret the corresponding value field. Valid values come from trace_schemas.MimeType:

The GraphQL MimeType Strawberry enum mirrors these values and adds a _missing_ fallback: a falsy/empty raw value defaults to MimeType.text; any other unrecognised value returns None 11.

SpanIOValue surfaces mime_type alongside the span's I/O content to GraphQL clients. The Span GraphQL resolver reads the hybrid property (input_mime_type / output_mime_type) and passes it directly to MimeType(mime_type) when constructing the response 12 13.

Key Source Files#