API reference and v0.8.2 migration

The supported module is praval.observability. The provider-neutral contracts used by both telemetry and evaluation are in praval.models.

Lifecycle API

Symbol

Contract

ObservabilityConfig

Immutable validated signal, sampling, privacy, OTLP, and local configuration.

ObservabilityHandle

Active configuration, providers, optional local store, ownership set, bounded force_flush() and shutdown().

configure_observability()

Configure host-owned or Praval-owned providers; raises PravalConfigurationError for conflicts, missing extras, or invalid topology.

configure_tracing()

Compatibility helper for a Praval-owned trace-only OTLP pipeline.

get_tracer(), get_meter(), get_logger()

Official OpenTelemetry API objects; safe no-ops without configuration.

force_flush()

Flush Praval-owned components within the configured or supplied millisecond bound; returns success.

shutdown_observability()

Flush and close Praval-owned components; idempotent and bounded.

Complete public surface

Area

Symbols

Configuration/lifecycle

ObservabilityConfig, ObservabilityHandle, get_config, configure_observability, configure_tracing, force_flush, shutdown_observability, is_observability_configured

Official APIs

get_tracer, get_meter, get_logger, Span, SpanKind, SpanStatus

Observation recording

CompositeObservationRecorder, configure_observation_recorder, use_observation_recorder, emit_evaluation_result

Context compatibility

Tracer, TraceContext, get_current_span

Local diagnostics

SQLiteTraceStore, get_trace_store, ConsoleViewer, print_traces, show_recent_traces

Instrumentation

initialize_instrumentation, is_instrumented

Export compatibility

OTLPExporter, export_traces_to_otlp

Lifecycle functions may raise PravalConfigurationError for invalid, conflicting, missing-extra, endpoint, header, ownership, or topology settings. force_flush() and shutdown return booleans for bounded delivery/lifecycle failure. Local store access raises when the exporter is not active. Recorder and telemetry export failures are isolated from the completed application operation and logged by bounded exception type.

Observation API

ExecutionObservation is immutable and versioned with schema_version = 1. It contains run and subject identity, UTC timing, terminal status, structured error type, provider/model/request metadata, bounded usage, tool, retry, HITL, handoff and content-reference facts, privacy state, and optional trace/span correlation.

ObservationRecorder is a structural protocol with record(observation: ExecutionObservation) -> None. Use configure_observation_recorder() for the process default, use_observation_recorder() for one sync or async context, and CompositeObservationRecorder to isolate and fan out to consumers. Recorder failure is logged and cannot fail the agent request.

Compatibility surface

Tracer, Span, SpanKind, SpanStatus, TraceContext, get_current_span(), SQLiteTraceStore, get_trace_store(), console viewing, and instrumentation helpers remain available. SpanKind and the tracer facade map to official OpenTelemetry objects.

The old hand-built OTLPExporter and export_traces_to_otlp() remain only for compatibility. New applications configure official OTLP HTTP/protobuf or gRPC pipelines with configure_observability(). A compatibility export helper may flush a matching active pipeline; it must not silently redirect an already configured process.

Migration from v0.8.2

  1. Install praval[observability] when Praval owns SDK providers.

  2. Replace implicit or import-time setup with configure_observability().

  3. Enable SQLite explicitly and treat it as local, single-process diagnostics.

  4. Replace flat sample_rate, otlp_endpoint, and storage_path fields with sample_ratio, otlp, and local; compatibility aliases emit deprecation warnings.

  5. Send all three signals to a Collector and call bounded shutdown during application termination.

  6. Keep content capture off unless an exact allowlist and retention policy have been reviewed.