SDK Observability

The ArmorIQ SDKs record one OpenTelemetry trace for each session. The trace holds spans for the plan, each policy decision, each model call, and each tool or command call. You add no span code, no trace ID code, and no flush code. This page is for developers who want the short version, with links to the full guides.

Session
└── Trace (one OpenTelemetry trace)
    ├── Plan
    ├── Policy decisions
    ├── Model calls
    └── Tool and command work

Shared Behavior

• Tracing is on by default. You can turn it off for one session, for a process, or for the whole organization.
• The SDK builds a private tracer provider. A tracer provider is the OpenTelemetry object that creates spans and passes them to an exporter. The SDK does not use or change the provider that your application has.
• Spans go to ArmorIQ over OTLP (POST /v1/traces), by default. OTLP is the standard OpenTelemetry way to send trace data over HTTP. You can send them to your own OTLP endpoint or Collector, or to your own tracer provider. See Choose who exports your traces.
• Your organization capture policy is the upper limit for the data that the SDK records. A local setting can only lower it. See Organization controls.
• Prompts, completions, and tool inputs and outputs are not recorded by default. Secrets and personal identifiers are removed in every mode. See What data is captured.
• Telemetry errors are fail-open and do not change policy decisions.
• The SDK never falls back to another route, endpoint, or storage path. If an export destination is missing or not reachable, it exports nothing.
• Closing a session waits a short, fixed time to send the last spans. This is at most 3 seconds in Python and 1.5 seconds in TypeScript.

What replaced the span primitives

Older SDKs exported low-level functions such as startTrace, endTrace, openSpan, closeSpan, recordSpan, recordPolicyCall, recordEvent, and deriveTraceSummary, and the classes ObservabilityRecorder and ObservabilityShipper. The current releases do not have them. The SDK now builds the span tree from the session API and the framework adapters. In Python, session.record_generation(...) and session.flush_observability() remain. See the Python SDK and TypeScript SDK pages for the calls that are optional, and the migration guide for the full list of removed names.

Explore and Diagnose

• Observability overview for architecture, freshness, retention, and supported producers
• Data model and schema for span names, attributes, status, token, and cost fields
• Observability dashboard for the screens and 30-second polling behavior
• Troubleshooting for missing, delayed, or incomplete telemetry