Metadata-Version: 2.4
Name: zcy-loguru
Version: 0.3.1
Summary: Unified Loguru logging helpers with standard logging interception and trace context support.
Author: zfane
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/zcy-loguru/
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: loguru==0.7.3
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.29.0; extra == "otel"
Requires-Dist: opentelemetry-instrumentation>=0.50b0; extra == "otel"

# zcy-loguru

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

## Install

```bash
pip install zcy-loguru
```

Install optional OpenTelemetry support with:

```bash
pip install "zcy-loguru[otel]"
```

## Usage

```python
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:

```bash
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:

```python
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.
