Telemetry reference

Radiant stores received span attributes and interprets the fields below for its agent, model and tool views. Use the connection guide for your framework to configure export or add instrumentation.

Configure export

Send OTLP traces over HTTP to the project’s ingestion address at /v1/traces. Both application/x-protobuf and application/json are accepted. The ingestion endpoint does not accept OTLP logs or metrics.

For exporters that read standard OpenTelemetry variables:

Exporter configuration

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='https://YOUR_INGESTION_HOST/v1/traces'
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL='http/protobuf'
export OTEL_EXPORTER_OTLP_TRACES_HEADERS='Authorization=Bearer%20YOUR_INGESTION_KEY'
export OTEL_SERVICE_NAME='YOUR_SERVICE_NAME'

A traces-specific endpoint includes /v1/traces. SDKs using a base OTLP endpoint may append that path; include it exactly once. Disable request compression: the receiver accepts absent or identity content encoding.

The standard environment-variable header format percent-encodes the space after Bearer. A header supplied directly in code uses an ordinary space: Authorization: Bearer YOUR_INGESTION_KEY.

The ingestion key selects the destination project. Resource attributes and agent identifiers do not route activity to another project.

Attribute scope

Span attributes describe one recorded operation. Set request or conversation identifiers on the relevant invocation or operation before its span ends. They are not automatically copied to child spans. Resource attributes describe the process producing telemetry, such as its service and deployment environment, and apply to that process’s exported spans.

Framework metadata can use different exported keys. Mastra exports custom metadata with a mastra.metadata. prefix, while Pydantic AI records additional run metadata inside a JSON metadata attribute. Both can record a conversation identifier as gen_ai.conversation.id. Use the exported field, not the framework option’s name, when filtering or grouping in Logs.

For custom instrumentation, add attributes to the existing OpenTelemetry span. Keep a per-conversation identifier on the invocation rather than setting one process-wide value for every request.

Agent runs

An agent invocation is recognized when its gen_ai.operation.name attribute equals invoke_agent. The span’s display name does not need a particular prefix.

Radiant also recognizes native Codex turns: a session_task.turn span from service.name = codex_exec with target or code.module.name set to codex_core::tasks. This mapping treats each turn as one invocation, rather than treating every internal operation or the whole CLI session as a run.

Attribute	Interpretation
gen_ai.agent.id	Preferred stable identity discriminator.
gen_ai.agent.name	Display name; identity discriminator when no ID is supplied.
gen_ai.agent.description	Description shown in the agent catalog.
gen_ai.agent.version	Version used for filtering and comparison within the agent.
Resource service.namespace and service.name	Service scope for the derived agent identity.

The discriminator’s kind, its value and both service fields form the identity. Changing from a name-based identity to an explicit ID creates a different agent, even if their text matches. Version, replica and deployment-environment attributes do not create a new agent.

When no agent ID or name is supplied, recognized claude_code.interaction invocations use Claude Code as their agent name, and recognized Codex turns use Codex. Their CLI version comes from resource service.version unless gen_ai.agent.version is present. Other recognized invocations without an ID or name remain runs without a catalog association.

A run’s outcome is based on its invocation span: it remains in progress until that span ends, then is an error if the span has OpenTelemetry status ERROR or a non-empty error.type; otherwise it is successful. Child-span errors do not independently change that outcome.

Model requests

The execution view recognizes chat operations by the span name or gen_ai.operation.name.

Attribute	Interpretation
gen_ai.provider.name	Provider; gen_ai.system is accepted as a fallback.
gen_ai.request.model	Requested model.
gen_ai.response.model	Model reported in the response.
gen_ai.response.finish_reasons	Recorded completion reasons.
gen_ai.prompt.name, gen_ai.prompt.version	Prompt identification attributes retained with the operation.

Message content uses the message attributes; usage uses the token and cost fields.

Tool calls

The agent’s tool-call catalog recognizes a span when gen_ai.operation.name is execute_tool or gen_ai.tool.name is present.

Attribute	Interpretation
gen_ai.tool.name	Tool name.
gen_ai.tool.description	Tool description.
gen_ai.tool.type	Recorded tool type.
gen_ai.tool.call.id	Call identifier.
gen_ai.tool.call.arguments	Input; falls back to gen_ai.tool.call.input.
gen_ai.tool.call.result	Output; falls back to gen_ai.tool.call.output.

For each payload, the first present field wins. In the agent’s tool-call detail, those payloads become dedicated input/output fields and are omitted from its generic attribute map. The trace record’s Attributes tab retains the received span attributes.

Messages

Thread reads these attributes on the selected operation. Values can be structured values or JSON-encoded strings.

Attribute	Format
gen_ai.system_instructions	Array of message parts.
gen_ai.input.messages	Input message or array of messages.
gen_ai.output.messages	Output message or array of messages.

A message has a role and a parts array. For example, these are the values of two message attributes:

Message attribute values

{
  "gen_ai.input.messages": [
    { "role": "user", "parts": [{ "type": "text", "content": "What changed?" }] }
  ],
  "gen_ai.output.messages": [
    { "role": "assistant", "parts": [{ "type": "text", "content": "The configuration changed." }] }
  ]
}

Supported part types are text and reasoning with content; tool_call with name, arguments and an optional id; and tool_call_response with id and response. Matching tool-call IDs associate results with calls. Other parts are displayed as their recorded data.

Tokens and costs

Attribute	Interpretation
gen_ai.usage.input_tokens	Input token count.
gen_ai.usage.output_tokens	Output token count.
gen_ai.usage.cache_creation.input_tokens	Cache-creation input tokens shown in model details.
gen_ai.usage.cache_read.input_tokens	Cache-read input tokens shown in model details.
gen_ai.usage.reasoning.output_tokens	Reasoning output tokens shown in model details.
gen_ai.usage.cost	Exported cost in USD; falls back to llm.cost.total.

Base token counts and costs accept finite, non-negative numbers or numeric strings. Token counts are converted to whole numbers. The additional cache and reasoning counters are displayed when recorded as numbers. gen_ai.usage.cost_usd is not a recognized cost field. Radiant does not calculate provider prices from a model name.

Inclusive usage covers an invocation and its descendants. When a span reports a value, it is used as that subtree’s aggregate instead of adding its children again. Otherwise, descendant values are summed.

Direct usage applies the same rule but stops at nested agent invocations. Run lists show inclusive usage; agent metrics use direct usage. The trace view shows both when they differ. Model cost remains separate from Radiant credits.

For recognized Codex turns, Radiant reads codex.turn.token_usage.input_tokens and codex.turn.token_usage.output_tokens when standard usage attributes are absent. These turn totals take precedence over descendant usage. For Claude Code model requests, native input_tokens, cache_read_tokens and cache_creation_tokens contribute to input usage, and output_tokens supplies output usage. Standard usage attributes take precedence when present.

Events

An OTLP span event has a name, timestamp and attributes. The Events tab takes its level from the string attribute level and its message from the string attribute message. The event’s name and all attributes remain available when it is expanded.

An event named exception can provide exception.type, exception.message and exception.stacktrace for the operation’s error details. A non-empty span attribute error.type or OpenTelemetry status ERROR marks the span as failed. Use low-cardinality error types; the agent failure breakdown groups missing types as unknown.

Inspection events

The Inspection tab projects Polaris inspection events into inputs and outputs. An event needs polaris.inspection.system, polaris.inspection.param and a supported phase to be included.

Event attribute	Interpretation
polaris.inspection.system	System that produced the capture.
polaris.inspection.param	Parameter name used to group captures.
polaris.inspection.phase	Before for inputs or After for outputs.
polaris.inspection.value	Captured value.
polaris.inspection.type_name	Optional type metadata.
polaris.inspection.kind	Optional parameter or return kind.
polaris.inspection.rendering	Rendering format; text values are decoded where possible.
polaris.inspection.truncated	Whether the capture was truncated.

Repeated captures for one parameter are retained together. The presentation can unwrap supported successful-result and agent-input envelopes; the original event is retained unchanged.

Correlation and grouping

Trace and span identity is scoped to the project. A trace ID is 16 bytes and a span ID is 8 bytes. Propagate trace context across service boundaries to preserve parent-child relationships.

Conversations

Export a non-empty string gen_ai.conversation.id on agent invocations to associate related runs across requests. The Conversations view groups agent runs by this identifier within the selected project and time range. The identifier can also be inherited from an ancestor operation. Runs without it remain available in All agent runs.

For positively identified Codex telemetry, Radiant also resolves conversation.id from an ancestor codex.turn_input span. The original attributes are retained. Generic session.id, thread.id and conversation.id attributes are not automatic conversation identifiers for other telemetry.

Other application attributes remain available for custom grouping. Grouping does not create parent-child span relationships or a combined message transcript.

vapi.call.id must be a string on the selected span for Vapi recordings.

Group membership and filters

A group contains operations with the selected grouping value, together with their descendants. A child operation without the grouping attribute remains in its parent’s group. A child with a different value is excluded from that group.

Filters determine which groups appear, rather than removing individual operations from a group. Different operations can satisfy different filter conditions: one may match the error status and another the selected model. Opening the result shows the complete group, including operations that did not match those filters. See Grouping in Logs for the controls.

Simulation correlation

Simulation participants and the application under test produce separate records. Application traces appear in a run’s Evidence when they carry its run identifier in the same project:

Span attribute	Meaning
hubble.simulation.batch_id	String containing the Radiant simulation run ID. Associates the operation with that run.
hubble.simulation.simulated	true identifies the simulator’s own activity, which is excluded from application Evidence. Application spans leave this unset or false.

When application instrumentation already receives the run ID, set the batch attribute on the relevant operation before its span ends. Opening the run’s Logs group includes matching operations and their descendants. The association does not establish a parent-child relationship between separate traces.

The hosted browser and phone network do not automatically pass that identifier or OpenTelemetry trace context into the application. An exporter alone cannot establish the association. Application activity without the run identifier remains available in Logs using its own request or conversation identifiers and time range. See Application evidence.

Control captured content

Configure content capture in the framework guide. Apply redaction before export, including custom attributes and event fields. Project retention and deletion settings govern stored telemetry.

Troubleshoot tracing

No traces appear in Logs

Check the selected project, time range and query. Inspect exporter errors, then verify the ingestion URL, bearer header and protocol against Configure export. For a short-lived process, flush or shut down its exporter before exit.

The exporter returns 401

Use an active ingestion key for the intended project, not an MCP credential. Check key status in Settings → Project settings → API keys and the header encoding above.

The trace appears, but the agent does not

Check the invocation’s gen_ai.operation.name against Agent runs, or the native Codex detection fields for that integration. A catalog entry also needs an agent ID or name, except where a supported coding-agent mapping supplies one. Exporting a model request alone does not create an agent invocation.