praval.observability.lifecycle

Explicit OpenTelemetry provider lifecycle for Praval.

This module imports only the OpenTelemetry API at module load. SDK providers, processors, and exporters are imported lazily when Praval is asked to own a pipeline.

Functions

configure_observability([config, ...])	Configure Praval telemetry explicitly and return its ownership handle.
configure_tracing(*, service_name, otlp_endpoint)	Configure a Praval-owned trace-only OTLP pipeline.
force_flush([timeout_millis])	Flush the active Praval-owned telemetry resources.
get_logger([name])	Return an official OpenTelemetry logger from the active provider.
get_meter([name])	Return an official OpenTelemetry meter from the active provider.
get_tracer([name])	Return an official OpenTelemetry tracer from the active provider.
is_observability_configured()	Return whether the explicit Praval observability facade is active.
shutdown_observability([timeout_millis])	Flush and shut down only the active resources owned by Praval.

Classes

ObservabilityHandle(config, tracer_provider, ...)

Configured providers and the resources owned by Praval.

class praval.observability.lifecycle.ObservabilityHandle(config, tracer_provider, meter_provider, logger_provider, local_trace_store=None, owned_signals=frozenset({}), _owned_components=<factory>, _provider_identity=(None, None, None))

Bases: object

Configured providers and the resources owned by Praval.

Parameters:

• config (PravalConfig)

• tracer_provider (Any)

• meter_provider (Any)

• logger_provider (Any)

• local_trace_store (Any | None)

• owned_signals (frozenset[str])

• _owned_components (tuple[_OwnedComponent, ...])

• _provider_identity (tuple[int | None, int | None, int | None])

config: PravalConfig

tracer_provider: Any

meter_provider: Any

logger_provider: Any

local_trace_store: Any | None = None

owned_signals: frozenset[str] = frozenset({})

property active: bool

Return whether this handle remains active.

force_flush(timeout_millis=None)

Flush only components owned by Praval within a total time bound.

Return type:

bool

Parameters:

timeout_millis (int | None)

shutdown(timeout_millis=None)

Flush and close only components owned by Praval.

Return type:

bool

Parameters:

timeout_millis (int | None)

__init__(config, tracer_provider, meter_provider, logger_provider, local_trace_store=None, owned_signals=frozenset({}), _owned_components=<factory>, _provider_identity=(None, None, None))

Parameters:

• config (PravalConfig)

• tracer_provider (Any)

• meter_provider (Any)

• logger_provider (Any)

• local_trace_store (Any | None)

• owned_signals (frozenset[str])

• _owned_components (tuple[_OwnedComponent, ...])

• _provider_identity (tuple[int | None, int | None, int | None])

Return type:

None

praval.observability.lifecycle.configure_observability(config=None, *, service_name=None, service_version=None, deployment_environment=None, otlp_endpoint=None, otlp_protocol=None, traces_enabled=None, metrics_enabled=None, logs_enabled=None, tracer_provider=None, meter_provider=None, logger_provider=None)

Configure Praval telemetry explicitly and return its ownership handle.

Return type:

ObservabilityHandle

Parameters:

• config (PravalConfig | ObservabilityConfig | None)

• service_name (str | None)

• service_version (str | None)

• deployment_environment (str | None)

• otlp_endpoint (str | None)

• otlp_protocol (str | None)

• traces_enabled (bool | None)

• metrics_enabled (bool | None)

• logs_enabled (bool | None)

• tracer_provider (Any | None)

• meter_provider (Any | None)

• logger_provider (Any | None)

praval.observability.lifecycle.configure_tracing(*, service_name, otlp_endpoint, protocol='http/protobuf')

Configure a Praval-owned trace-only OTLP pipeline.

Return type:

ObservabilityHandle

Parameters:

• service_name (str)

• otlp_endpoint (str)

• protocol (str)

praval.observability.lifecycle.force_flush(timeout_millis=None)

Flush the active Praval-owned telemetry resources.

Return type:

bool

Parameters:

timeout_millis (int | None)

praval.observability.lifecycle.get_logger(name='praval')

Return an official OpenTelemetry logger from the active provider.

Return type:

Any

Parameters:

name (str)

praval.observability.lifecycle.get_meter(name='praval')

Return an official OpenTelemetry meter from the active provider.

Return type:

Meter

Parameters:

name (str)

praval.observability.lifecycle.get_tracer(name='praval')

Return an official OpenTelemetry tracer from the active provider.

Return type:

Tracer

Parameters:

name (str)

praval.observability.lifecycle.is_observability_configured()

Return whether the explicit Praval observability facade is active.

Return type:

bool

praval.observability.lifecycle.shutdown_observability(timeout_millis=None)

Flush and shut down only the active resources owned by Praval.

Return type:

bool

Parameters:

timeout_millis (int | None)