Local SQLite diagnostics

SQLite is an opt-in trace diagnostic for local development and CI. Enable observability.local.enabled, keep traces enabled, and set an explicit path. get_trace_store() raises PravalConfigurationError unless that exporter is active.

The exporter uses the official SpanExporter contract behind an official batch processor. It preserves resource and instrumentation scope, span kind and status, events, links, trace state, and privacy-filtered attributes. WAL mode, a bounded busy timeout, and batched writes support concurrent activity within one process.

Count and age retention delete whole old traces, never isolated spans from a retained trace. Existing legacy databases are migrated when opened. Call force_flush() before reading immediately after work because export is batched.

SQLite is not a production aggregation service, durable delivery queue, or multi-container store. Use a Collector and an observability backend for those roles.

Inspecting traces

from praval.observability import (
    force_flush,
    get_trace_store,
    print_traces,
    show_recent_traces,
)

force_flush(5_000)
store = get_trace_store()
trace_ids = store.get_recent_traces(limit=20)
show_recent_traces(limit=5)
if trace_ids:
    print_traces(trace_id=trace_ids[0])

The viewer renders privacy-filtered stored spans; it does not contact an OTLP backend. Query only after a successful bounded flush when immediate visibility matters. Concurrent threads in one process are supported through WAL and busy timeouts, but multiple service instances still need a Collector.

Retention behavior

max_traces keeps the newest complete traces by trace identity. max_age_days=0 disables age pruning while leaving count pruning active. Pruning removes an entire selected trace transactionally so a retained trace does not lose arbitrary children. Back up or export traces that must outlive the local diagnostic window; SQLite retention is not an audit archive.

Common failures are an unexpanded/unwritable parent directory, local export enabled while traces are disabled, reading before batch flush, or opening an unsupported/corrupt database. Configuration and migration failures are explicit; Praval does not silently switch to a different path.