zcy-loguru 0.3.1

Unified Loguru logging helpers with standard logging interception and trace context support.

zcy-loguru

zcy-loguru provides a small wrapper around loguru for structured logging, standard library logging interception, and trace/span propagation.

Install

pip install zcy-loguru

Install optional OpenTelemetry support with:

pip install "zcy-loguru[otel]"

Usage

from zcy_logger import init_logging, logger

init_logging()
logger.info("hello")

init_logging() replaces Loguru's default sink with the configured JSON (or human-readable) sink and forwards standard-library logging records to it. It can be called explicitly when an application needs custom options.

OpenTelemetry auto-instrumentation

Install the optional dependency and start the application through the standard OpenTelemetry launcher:

pip install "zcy-loguru[otel]"
opentelemetry-instrument python main.py

The ZcyLoguruInstrumentor entry point calls init_logging() before the application is imported. Explicit init_logging(...) calls remain supported for applications that need non-default output settings.

When a log record has an active OpenTelemetry span, its trace and span IDs are included in the output. Without one, zcy-loguru creates and ends a root zcy.log span for that record. If no usable OpenTelemetry provider is configured, it generates local IDs instead, so trace_id and span_id are always present. Creating one root span per uncorrelated log record can increase trace volume substantially.

Taking over legacy loggers

Applications with named standard-library loggers that install private handlers or set propagate = False can explicitly route them through zcy-loguru:

from zcy_logger import init_logging, intercept_loggers

init_logging()
intercept_loggers("seal_agent.log", "err.log")

Call intercept_loggers() before legacy logger setup when possible. It replaces the named logger's handlers with the zcy-loguru bridge, preventing duplicate output even if the legacy setup disables propagation.