vgi.logging_config

Module overview

Shared logging configuration for VGI worker CLIs.

Provides enums, known-logger registry, and a configure function that mirrors the vgi_rpc CLI logging setup so that --debug, --log-level, --log-logger, and --log-format behave identically across all VGI workers.

function configure_worker_logging

source

configure_worker_logging(
*,
debug: bool = False,
log_level: LogLevel = LogLevel.INFO,
log_loggers: list[str] | None = None,
log_format: LogFormat = LogFormat.text,
access_log_sample: float | None = None,
access_log_async: bool = False,
access_log_queue_size: int | None = None,
) -> int

Configure stdlib logging for a VGI worker process.

VGI_WORKER_LOG_LEVEL, VGI_WORKER_LOG_FORMAT and VGI_WORKER_LOG_LOGGERS override the corresponding arguments when set — see :func:_env_overrides. The access-log arguments have their own VGI_WORKER_ACCESS_LOG_* overrides; see :func:_access_log_overrides.

Sampling and async emission apply only to vgi_rpc.access, and only when that logger is among the configured targets. They are deliberately not applied to the diagnostic loggers: dropping half of a traceback is not a saving.

Trace correlation needs no configuration here — vgi_rpc reads whatever span is current when it emits a record, so trace_id / span_id appear on every record as soon as OpenTelemetry is active (VGI_OTEL_ENABLED=1).

Parameters

debug

If True, force DEBUG on all default loggers (overrides log_level).

log_level

Logging level when debug is False.

log_loggers

Logger names to configure. Defaults to [“vgi”, “vgi_rpc”].

log_format

Stderr output format (text or json).

access_log_sample

Fraction of successful calls to keep in the access log. Errors are always kept, and the decision is per call so every record belonging to one stream shares a fate. None keeps all.

access_log_async

Hand access-log records to a listener thread rather than formatting and writing them on the request thread. Trades durability for latency: the queue is bounded, full means drop, and a crash loses whatever is still queued. The next record through carries dropped_records so a gap is never silent.

access_log_queue_size

Bound on the async queue. Ignored unless access_log_async. None uses 10000.

Returns

The effective numeric log level.

class LogFormat

source

Bases: StrEnum

Description

Stderr log format for --log-format.

Attributes

attribute text

attribute json

class LogLevel

source

Bases: StrEnum

Description

Python logging level for --log-level.

Attributes

attribute DEBUG

attribute INFO

attribute WARNING

attribute ERROR