# Logging Mechanisms in Colibri: A Deep Dive into Python Standard Library Implementation

> Explore Colibri's logging mechanisms, leveraging Python's standard logging module and custom wrappers. Understand how Colibri captures diagnostic data and progress.

- Repository: [Vincenzo Fornaro/colibri](https://github.com/JustVugg/colibri)
- Tags: deep-dive
- Published: 2026-09-12

---

**Colibri relies on the Python standard `logging` module combined with custom file-based logging wrappers to capture diagnostic data, model conversion progress, and subprocess execution details.**

The JustVugg/colibri repository implements a lightweight, two-tier logging strategy that leverages built-in Python capabilities rather than third-party frameworks. By analyzing the source code, you will find that logging mechanisms in Colibri are concentrated in diagnostic and conversion tools, using structured file outputs for subprocess monitoring and standard library calls for conversion workflows.

## Standard Python Logging for FP8 Conversion

Colibri configures the standard `logging` module for model quantization tasks. In [`c/tools/convert_fp8_to_int4.py`](https://github.com/JustVugg/colibri/blob/main/c/tools/convert_fp8_to_int4.py), the script initializes the logging infrastructure before downloading model shards.

### Configuration in convert_fp8_to_int4.py

The conversion script sets up a timestamped format at lines 40-42 using `logging.basicConfig`. This establishes a consistent pattern for all subsequent log calls throughout the quantization process.

```python

# From c/tools/convert_fp8_to_int4.py (lines 40-42)

import logging
logging.basicConfig(
    format="%(asctime)s %(name)s: %(message)s",
    datefmt="%H:%M:%S"
)

logging.info("Starting FP8-to-INT4 conversion")

```

This configuration ensures that every **INFO**, **WARNING**, or **ERROR** level message includes a precise timestamp and the logger name. The simplicity of this approach avoids external dependencies while providing sufficient traceability for long-running model conversion operations.

## Custom File-Based Logging in the Diagnostic Harness

For subprocess execution and system diagnostics, Colibri implements a manual file-writing mechanism rather than using the standard logging handlers. The `DiagnosticHarness` class in [`c/tools/diag_harness.py`](https://github.com/JustVugg/colibri/blob/main/c/tools/diag_harness.py) creates structured log files that capture comprehensive execution metadata.

### Log Structure and Content

Between lines 174-202, the harness generates timestamped log files named `run_<timestamp>.log`. Each file records the exact command executed, elapsed time, return code, and the complete stdout/stderr streams from the subprocess.

```python

# From c/tools/diag_harness.py (lines 174-202 context)

log_path = self.out_dir / (log_name or f"run_{int(t0)}.log")
with open(log_path, "w", encoding="utf-8") as f:
    f.write(f"=== CMD: {' '.join(cmd)}\n")
    f.write(f"=== ELAPSED: {elapsed:.1f}s\n")
    f.write(f"=== RC: {rc}\n\n")
    f.write("--- STDOUT ---\n"); f.write(stdout or ""); f.write("\n")
    f.write("--- STDERR ---\n"); f.write(stderr or ""); f.write("\n")

```

This implementation creates a forensic record of each execution, enabling developers to debug failed runs without relying on console output that might be lost in ephemeral CI environments.

## Absence of Third-Party Logging Frameworks

Unlike many modern Python projects that adopt **structlog** or **loguru**, Colibri deliberately avoids external logging dependencies. The codebase relies exclusively on:

- **Standard library `logging`** for conversion scripts
- **Direct file I/O** for diagnostic harnesses
- **Plain `print` statements** in CLI interfaces

This design choice minimizes dependency bloat while maintaining full compatibility across different Python environments and deployment targets.

## Summary

- **Primary mechanism**: Python's built-in `logging` module with timestamp formatting
- **Diagnostic logging**: Custom file writers in [`c/tools/diag_harness.py`](https://github.com/JustVugg/colibri/blob/main/c/tools/diag_harness.py) creating `run_<timestamp>.log` files
- **Configuration location**: [`c/tools/convert_fp8_to_int4.py`](https://github.com/JustVugg/colibri/blob/main/c/tools/convert_fp8_to_int4.py) sets `basicConfig` at import time
- **Log content**: Commands, elapsed time, return codes, and full stdout/stderr capture
- **No external dependencies**: Colibri avoids structlog, loguru, or similar frameworks

## Frequently Asked Questions

### What logging library does Colibri use?

Colibri uses the standard Python `logging` library exclusively. The [`c/tools/convert_fp8_to_int4.py`](https://github.com/JustVugg/colibri/blob/main/c/tools/convert_fp8_to_int4.py) file configures this via `logging.basicConfig` to output timestamps with each message, while other components use direct file writing for structured logs.

### Where are Colibri's log files stored?

Log files are stored in the output directory specified to the `DiagnosticHarness` class, with filenames following the pattern `run_<timestamp>.log`. Each file contains the executed command, elapsed time, return code, and captured output streams from subprocess executions.

### Why doesn't Colibri use Loguru or Structlog?

The project maintains zero third-party logging dependencies to reduce installation footprint and avoid version conflicts. This approach uses Python's built-in capabilities and manual file handling to achieve similar structured output without additional package management overhead.

### How do I enable debug logging in Colibri?

To enable debug-level output, modify the `logging.basicConfig` call in [`c/tools/convert_fp8_to_int4.py`](https://github.com/JustVugg/colibri/blob/main/c/tools/convert_fp8_to_int4.py) to include `level=logging.DEBUG`, or adjust the log level on specific loggers. For the diagnostic harness, verbosity is controlled through the command execution wrapper rather than traditional logging levels.