Install and five-minute quickstart

Base-package instrumentation

python -m pip install praval

The base install includes the OpenTelemetry API and Praval’s provider-neutral observation contracts. It does not include the SDK or exporters. Existing agent code works unchanged and telemetry is a no-op until a provider is configured.

Check the installed API, SDK, OTLP transports, and tested OpenTelemetry minor without printing credentials:

praval doctor --json

Local development

Install the managed pipelines and opt in to local SQLite diagnostics:

python -m pip install "praval[observability]"

from praval.observability import (
    ObservabilityConfig,
    configure_observability,
    force_flush,
    get_trace_store,
    shutdown_observability,
)

config = ObservabilityConfig(
    enabled=True,
    local={"enabled": True, "path": ".praval/telemetry.db"},
    otlp={"traces": True, "metrics": False, "logs": False},
)
handle = configure_observability(config, service_name="local-demo")

# Run agents or workflows here. Their completed observations create spans.
force_flush(5_000)
recent_trace_ids = get_trace_store().get_recent_traces(limit=10)
shutdown_observability(5_000)

SQLite is explicit, local, and single-process. It is not a shared backend for multiple containers.

Host-owned SDK

An application that already owns OpenTelemetry can pass its providers. Praval uses them without replacing global providers and does not shut them down.

from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.trace import TracerProvider

from praval.observability import configure_observability

handle = configure_observability(
    service_name="host-owned-demo",
    tracer_provider=TracerProvider(shutdown_on_exit=False),
    meter_provider=MeterProvider(shutdown_on_exit=False),
    logger_provider=LoggerProvider(shutdown_on_exit=False),
)
assert handle.owned_signals == set()

Configure processors and readers on those providers in the host application. A Praval OTLP endpoint cannot be attached to a host-owned meter provider because the OpenTelemetry SDK requires metric readers at provider construction time.

Praval-owned SDK

Point all three signals at a local Collector:

from praval.observability import configure_observability, shutdown_observability

handle = configure_observability(
    service_name="orders-agent",
    service_version="0.8.3",
    deployment_environment="development",
    otlp_endpoint="http://127.0.0.1:4318",
    otlp_protocol="http/protobuf",
)
assert handle.owned_signals == {"traces", "metrics", "logs"}

try:
    # Run the application.
    pass
finally:
    shutdown_observability(5_000)

For gRPC use otlp_protocol="grpc" and an endpoint such as 127.0.0.1:4317. See Collectors and deployment.