ArmorClaude Observability

ArmorClaude records one trace for each Claude turn. Use it to connect the turn prompt with policy checks, allow, deny, or ask decisions, and the tool results that followed.

Observability is enabled automatically when ArmorClaude has an ArmorIQ API key. It is additive and fail-open: telemetry errors do not change the decision returned by a hook.

What a Turn Records

ArmorClaude session
└── Turn trace
    ├── Plan start
    ├── Tool check
    │   └── Policy decision
    └── Tool result or error

The current bridge records:

• a bounded preview of the turn prompt;
• allow, deny, or ask policy decisions;
• policy reasons and the enforcement action;
• tool names, bounded inputs, outputs, and error status;
• trace duration, agent identity, tags, and an output summary.

ArmorClaude reports transcript token totals through the separate dashboard token-usage path at Stop. It does not currently add transcript-derived generation spans to the turn's observability trace. See the shared observability data model for the fields that can appear on each span kind.

Daemon and Session Correlation

ArmorClaude normally sends hooks to a long-lived daemon. The daemon keeps a per-session registry of SDK recorders, so one recorder and active trace persist across UserPromptSubmit, tool hooks, and Stop.

Each hook forwards its current authentication and observability settings. The daemon creates an effective configuration snapshot for that request instead of relying only on the environment it saw when it first started. A new session recorder is initialized from that effective configuration.

The registry uses the Claude hook session ID for in-process correlation. The backend receives the session and user IDs only when they are valid UUIDs; the free-form ArmorClaude agent ID is still preserved. The in-process fallback is best-effort and cannot provide the same cross-hook nesting as the long-lived daemon.

Turn and Session Lifecycle

Ending a trace at Stop moves it into the SDK shipping queue. The background shipper flushes every five seconds by default. A new trace opens on the next UserPromptSubmit, or lazily if a later hook needs one first.

SessionEnd explicitly waits for the final flush. That wait can include network timeout and retry time even though a telemetry failure never changes enforcement.

Delivery and Failure Behavior

Shipping is best-effort and fail-open:

• bridge exceptions are caught; bridge details appear in debug mode, while the SDK shipper logs delivery warnings;
• telemetry failures do not turn an allow into a deny or a deny into an allow;
• ended traces are batched and retried for network or server failures;
• malformed, rejected, or exhausted batches can be dropped;
• forced process termination can prevent the final session flush.

Close Claude sessions normally when possible so SessionEnd can flush and remove their recorder.

Enable or Disable Observability

Observability is on by default when an API key is configured. It uses the selected ArmorIQ backend and reports product armorclaude.

Disable it in the ArmorClaude plugin configuration with disable_observability, or set:

export ARMORIQ_OBSERVABILITY_DISABLED=true

The plugin option takes precedence over the environment fallback. Accepted true values are true, 1, yes, y, and on. Without an API key, production observability remains inactive.

When Traces Appear

ArmorClaude does not stream the in-progress span tree. Stop ends the trace, the shipper normally sends it within the next five-second flush interval, and the ArmorIQ dashboard polls every 30 seconds. The completed turn can therefore appear before its trace.

Use the observability dashboard guide for screen and refresh behavior. For missing sessions, agent names, or tool spans, use the observability troubleshooting guide.

Privacy Boundary

Observability can contain prompt previews, policy inputs, tool inputs, and tool outputs. ArmorClaude applies bounded depth, key-count, item-count, and string-length sanitization, and applies known secret-pattern redaction to tool responses.

This is not general-purpose data-loss prevention. Prompts and policy inputs are not guaranteed to be free of credentials or personal information. Keep secrets out of recorded payloads, use synthetic values when debugging, and restrict dashboard access to the appropriate organization members.

For the complete producer, backend, and dashboard flow, see the observability overview.