Observability

Praval emits OpenTelemetry traces, metrics, and logs from the same completed ExecutionObservation. Observability is disabled by default and importing Praval never installs an SDK, starts a worker, opens SQLite, or replaces a provider. The base package contains OpenTelemetry API instrumentation. Install praval[observability] only when Praval should own SDK pipelines.

The runtime produces one observation per agent or workflow and aggregates bounded facts for model use, tools, retries, HITL decisions, and Reef handoffs. That provider-neutral observation is offered independently to telemetry and to evaluation consumers. Evaluation therefore does not need to query a tracing backend.

• Install and five-minute quickstart
  • Base-package instrumentation
  • Local development
  • Host-owned SDK
  • Praval-owned SDK
• Configuration reference
  • praval.toml
  • Fields and defaults
  • Environment variables
• Instrumentation map
  • Root identity and completion
  • Instrumentation ownership
• Distributed tracing
  • Propagation sequence
  • Sampling and trust
• Traces, metrics, and logs
  • Traces
  • Metrics
  • Logs
  • Attribute policy
  • Backend queries
• Collectors and deployment
  • Local Collector
  • Multiple containers
  • Headers and TLS
• Sampling and performance
  • Choosing a ratio
  • Queue and batch tradeoffs
• Privacy and security
  • Content enablement checklist
  • Threat boundaries
• Local SQLite diagnostics
  • Inspecting traces
  • Retention behavior
• Lifecycle and troubleshooting
  • Graceful shutdown
  • Diagnosis
  • Provider ownership
  • Failure sequence
  • Async and process boundaries
• API reference and v0.8.2 migration
  • Lifecycle API
  • Complete public surface
  • Observation API
  • Compatibility surface
  • Migration from v0.8.2

Ownership model

• With no configuration, OpenTelemetry API calls are safe no-ops.

• In host-owned mode, the application constructs providers and remains responsible for their processors, exporters, flush, and shutdown.

• In Praval-owned mode, configure_observability() constructs selected SDK providers and returns an ObservabilityHandle. Praval flushes and shuts down only the components recorded in handle.owned_signals.

• A Collector is the recommended deployment boundary. Use HTTP/protobuf or gRPC rather than adding vendor SDK dependencies to Praval.

Executed tutorial matrix

Each recipe is backed by an executable release test.

Recipe	Guide	Executable evidence
Local development	Quickstart	tests/observability/test_sqlite_exporter.py
Host-owned SDK	Quickstart	tests/observability/test_lifecycle.py
Praval-owned SDK	Quickstart	tests/observability/test_lifecycle.py
Collector	Collectors	tests/integration/test_otel_collector.py
Multi-container	Collectors	tests/integration/test_otel_collector.py
RabbitMQ	Distributed tracing	tests/integration/test_rabbitmq_trace_propagation.py
Privacy	Privacy and security	tests/observability/test_privacy.py
Failure isolation	Lifecycle and troubleshooting	tests/observability/test_health.py
Shutdown	Lifecycle and troubleshooting	tests/observability/test_lifecycle.py

The external-service tests are explicit gates. Run ./scripts/run_otel_collector_tests.sh for a real Collector and the RabbitMQ integration test against a real broker before a release.