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

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, 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.

# 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 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.

# 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 creating run_<timestamp>.log files
• Configuration location: 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}