corvix.observability

Observability for Corvix: structured logging, Prometheus metrics, OTel tracing.

• Structured JSON logging via configure_logging() (always available).

• Prometheus metrics via the corvix.observability.metrics module and the /metrics web endpoint.

• Optional OpenTelemetry tracing via setup_tracing() and span() (requires the otel extra and CORVIX_OTEL_ENABLED).

Submodules

• corvix.observability.logging
• corvix.observability.metrics
• corvix.observability.middleware
• corvix.observability.tracing

Functions

bind_log_context(→ dict[str, object] | None)	Merge fields into the current logging context and return the previous one.
configure_logging(→ None)	Install the structured logging handler on the root logger.
reset_log_context(→ None)	Restore a logging context previously returned by bind_log_context().
is_enabled(→ bool)	Return whether tracing has been successfully configured.
setup_tracing(→ bool)	Configure the global tracer provider when tracing is requested.
span(→ collections.abc.Iterator[Any])	Start a span as the current context, or no-op when tracing is disabled.

Package Contents

corvix.observability.bind_log_context(**fields: object) → dict[str, object] | None

Merge fields into the current logging context and return the previous one.

The returned value should be passed to reset_log_context() to restore the prior state (typically in a finally block).

corvix.observability.configure_logging(level: str | None = None, log_format: str | None = None) → None

Install the structured logging handler on the root logger.

level defaults to CORVIX_LOG_LEVEL (then INFO) and log_format to CORVIX_LOG_FORMAT (then json; console selects a human-readable formatter for local development). Safe to call multiple times — the Corvix handler is only installed once.

corvix.observability.reset_log_context(previous: dict[str, object] | None) → None

Restore a logging context previously returned by bind_log_context().

corvix.observability.is_enabled() → bool

Return whether tracing has been successfully configured.

corvix.observability.setup_tracing(service_name: str | None = None) → bool

Configure the global tracer provider when tracing is requested.

Returns True when tracing is active afterwards. A no-op (returning False) when CORVIX_OTEL_ENABLED is not truthy or the otel extra is not installed. Safe to call multiple times.

corvix.observability.span(name: str, attributes: collections.abc.Mapping[str, Any] | None = None) → collections.abc.Iterator[Any]

Start a span as the current context, or no-op when tracing is disabled.

Yields the active span (or None when disabled). Exceptions raised in the block are recorded on the span and re-raised.