corvix.observability.logging

Structured JSON logging for Corvix.

Provides configure_logging(), which installs a single stdout handler on the root logger emitting one JSON object per line with a consistent schema: timestamp, level, logger, module, event and any extra fields passed via logger.*(..., extra={...}).

A contextvars-based context (see bind_log_context()) lets request scoped fields such as request_id be attached to every log line emitted while handling a request without threading them through every call.

Attributes

_RESERVED_RECORD_KEYS
_log_context
_LOG_FORMAT_JSON
_LOG_FORMAT_CONSOLE
_handler

Classes

JsonFormatter

Render log records as single-line JSON objects.

Functions

_current_context(→ dict[str, object])
bind_log_context(→ dict[str, object] | None)	Merge fields into the current logging context and return the previous one.
reset_log_context(→ None)	Restore a logging context previously returned by bind_log_context().
_build_handler(→ logging.Handler)
configure_logging(→ None)	Install the structured logging handler on the root logger.

Module Contents

corvix.observability.logging._RESERVED_RECORD_KEYS: frozenset[str]

corvix.observability.logging._log_context: contextvars.ContextVar[dict[str, object] | None]

corvix.observability.logging._LOG_FORMAT_JSON = 'json'

corvix.observability.logging._LOG_FORMAT_CONSOLE = 'console'

corvix.observability.logging._handler: logging.Handler | None = None

corvix.observability.logging._current_context() → dict[str, object]

corvix.observability.logging.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.logging.reset_log_context(previous: dict[str, object] | None) → None

Restore a logging context previously returned by bind_log_context().

class corvix.observability.logging.JsonFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: logging.Formatter

Render log records as single-line JSON objects.

format(record: logging.LogRecord) → str

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

corvix.observability.logging._build_handler(log_format: str) → logging.Handler

corvix.observability.logging.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.