Module observability 

Observability — oxi-sdk 0.26.2 tracing, cost tracking, and audit.

Provides global instances of oxi-sdk’s Tracer, CostTracker, and AuditLog for use across the kernel. These complement the existing metrics module (Prometheus counters/gauges) with distributed tracing, per-agent cost accounting, and structured audit logging.

Architecture

Global instances (OnceLock):
  tracer()     → Tracer      (distributed spans: AgentSpan, ToolSpan, etc.)
  cost_tracker() → CostTracker (per-agent token/cost tracking)
  audit_log()  → AuditLog    (structured security audit entries)

Usage

use oxios_kernel::observability;

// Start a span for an agent execution
let _span = observability::tracer().start("seed-execution", observability::SpanKind::Agent);

// Log audit entry
observability::audit_log()
    .log(observability::AuditEntry::tool_execution(
        "agent-1".into(),
        "exec".into(),
        "ls -la".into(),
        true,
        42,
    ));

Structs

AuditFilter

Filter criteria for querying the audit log.

AuditLog

Audit log — append-only event recorder with query and subscription.

CostBreakdown

Cost breakdown by category (USD).

CostSnapshot

Per-agent cost snapshot.

CostTracker

Cost tracker — accumulates token usage and computed costs per agent.

CostTrackerConfig

Configuration for the cost tracker.

GlobalCostSnapshot

Global cost snapshot across all agents.

Span

SpanContext

SpanGuard

SpanId

Unique span identifier.

TokenUsage

Token usage broken down by component.

TraceId

Unique trace identifier.

Tracer

Enums

AuditEntry

An audit trail entry.

SpanKind

SpanStatus

Functions

audit_log

Get the global AuditLog.

cost_tracker

Get the global CostTracker.

init

Initialize all observability instances.

tracer

Get the global Tracer.