Observability Overview

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 turn or monitor activity across an organization.

Who This Is For

Observability is for agent developers debugging execution, integration owners validating SDK and product telemetry, security teams reviewing policy outcomes, and operators monitoring reliability, latency, and usage across an organization.

How telemetry moves

The producer creates telemetry. The backend authenticates, validates, and stores it. The dashboard reads data scoped to the selected organization.

Session, trace, and span

Session
└── Trace
    ├── Policy call
    ├── Tool execution
    ├── Model generation
    └── Event or error

• A session is a continuous agent run or conversation. It groups related traces under one stable UUID.
• A trace is one IAP plan, agent turn, or other logical operation.
• A span is one operation inside a trace, such as a policy evaluation, tool execution, model generation, or event.

The SDKs use the current Model A lifecycle: one IAP plan becomes one trace, and policy checks, tool activity, reports, generations, and related operations become child spans. Starting a new plan closes the previous plan trace. A session can therefore contain multiple traces.

Supported producers

See ArmorCodex and ArmorClaude for the product-specific lifecycle.

What is captured

Depending on the producer and integration point, a trace can include:

• session, trace, span, parent-span, agent, user, and product identifiers;
• start and end times, duration, and ok, error, or denied status;
• policy decision, source, matched rule, enforcement action, reason, obligations, and data classes;
• tool name, input, output, and error details;
• model, input and output tokens, cache tokens, finish reason, prompt, completion, and estimated cost;
• trace tags and input/output previews.

Not every producer supplies every field. Some optional values render as --, but backend token and cost aggregates are initialized to numeric zero. The current dashboard therefore cannot always distinguish unreported generation usage from a measured zero. Unknown model pricing is also encoded as zero, so $0.00 can mean pricing unavailable. See Missing values and zero values.

Freshness and retention

• SDK shippers default to a 5-second flush interval.
• 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

Shipping is best-effort. Invalid data, authentication failures, network failures, and exhausted retries are logged and dropped without raising into the agent workflow. Policy decisions remain independent from telemetry success, although an awaited flush can add latency before a hook or shutdown boundary returns.

Telemetry can contain tool inputs, tool outputs, policy payloads, prompts, and completions. The SDK recorders do not automatically redact arbitrary application payloads. Product bridges apply their own bounded sanitization in some paths, but you should still avoid recording secrets and restrict dashboard access appropriately.

Next steps

• Set up the TypeScript SDK
• Set up the Python SDK
• Understand the data model
• Use the dashboard
• Call the backend API
• Troubleshoot missing or delayed telemetry