Observability Overview
Follow agent sessions from policy evaluation through tool execution, model usage, and errors, with OpenTelemetry traces that you control.
ArmorIQ Observability shows what an agent did, why an action was allowed or denied, how long each operation took, and how many model tokens it used. Use it to investigate a single run or to watch activity across an organization.
The SDKs record each agent run as an OpenTelemetry trace. OpenTelemetry is an open standard for trace data. You add no tracing code. Your administrators decide how much data ArmorIQ keeps.
Who this is for
Observability is for agent developers who debug runs, integration owners who check SDK and product telemetry, security teams who review policy outcomes and data capture, and operators who watch reliability, latency, and usage across an organization.
Observability is telemetry, not an enforcement dependency. A telemetry error does not change a policy decision or fail the agent operation. Ending a session waits a short, fixed time to send the last spans, so a destination that is not reachable can add that wait at the end of a run.
How telemetry moves
- The SDK reads your organization capture policy. It records only what the policy allows.
- The SDK builds spans for plans, policy decisions, model calls, and tool work, and exports them. By default they go to ArmorIQ over OTLP, the standard OpenTelemetry way to send traces over HTTP.
- ArmorIQ checks your API key, applies the organization policy again, removes secrets, and stores the spans.
- The dashboard reads the stored data for the organization that you select.
You can also send traces to your own destination, with or instead of ArmorIQ. See Choose who exports your traces and Deploy an OpenTelemetry Collector.
Session, trace, and span
- A session is one continuous agent run or conversation. It has one stable UUID.
- A trace is the set of spans that belong to one run. The SDKs make one trace for each session.
- A span is one timed step inside a trace.
A trace contains spans such as:
armoriq.agent.run, the root span of the run;armoriq.intent.plan, the plan that the agent made;armoriq.policy.evaluate, one for each policy decision;gen_ai.chat, one for each model call;armoriq.tool,mcp.execute,bash.execute,cli.execute, andcommand.execute, for tool and command work;armoriq.approval.waitandarmoriq.delegation.wait, when a hold waits for a person.
See the data model for the attributes.
Where to go next
| I want to... | Read |
|---|---|
| Turn on tracing for an agent | Set up tracing |
| Know which frameworks work and which versions are tested | Framework support |
| Send traces to my own tool, or use my own tracer provider | Choose who exports your traces |
| Run a Collector with batching, retry, and TLS | Deploy an OpenTelemetry Collector |
| Know what data is stored and what is never stored | What data is captured |
| Set capture mode, scopes, debug capture, quota, and alerts | Organization controls |
| Move from an older SDK | Migrate from the legacy recorder |
| Fix a missing or incomplete trace | Troubleshooting |
Supported producers
| Producer | How it records telemetry | When data normally becomes visible |
|---|---|---|
| TypeScript SDK 0.8.23 | OpenTelemetry spans, exported in batches over OTLP | After the spans end and are sent. The last spans send when the session closes. |
| Python SDK 0.8.17 | OpenTelemetry spans, exported in batches over OTLP | After the spans end and are sent. The last spans send when the session closes. |
| ArmorCodex and ArmorClaude | Per-turn bridges. Builds that use the current SDK send over OTLP. Builds that use an older SDK send to the old route. | After the turn ends and the bridge sends it |
| Any OTLP source | A Collector or another sender that follows the ingest rules | After ArmorIQ accepts the request |
See ArmorCodex and ArmorClaude for the product-specific lifecycle.
What is captured
By default ArmorIQ keeps metadata: the shape of the run, policy decisions, status, timing, token counts, cost, and safe error types. Prompts, completions, and tool inputs and outputs are kept only when your organization chooses the Enhanced or Debug capture mode and allows content capture. Secrets and personal identifiers are always removed. Read What data is captured for the full table.
Not every producer supplies every field. A value can show as -- or Not reported in the dashboard. See Missing values and zero values.
Freshness and retention
- The SDK sends spans in batches, and sends the rest when the session closes.
- The dashboard polls every 30 seconds. It does not use WebSocket or server-sent event streaming.
- ArmorCodex and ArmorClaude normally complete a trace at the end of a turn, so data can appear after the turn finishes.
- The backend retains observability traces and sessions for 30 days by default. Operators can change the server-side retention period with
OBSERVABILITY_RETENTION_DAYS.
Failure and privacy boundaries
Sending is best-effort. An SDK retries a failed send a few times, then drops the batch and logs a warning. It does not raise into the agent workflow, and it never switches to another path. Policy decisions stay independent from telemetry success.
The SDK and the ArmorIQ backend both remove secrets and personal identifiers from every mode. Redaction uses patterns, so it cannot find every secret. Do not put secrets in prompts or tool arguments, and limit dashboard access to the people who need it. If you export spans to another tool, ArmorIQ cannot take them back. See What the Off setting does and does not do.