# Logging Mechanisms in LingBot‑Map: Module‑Level and Centralized Strategies

> Explore LingBot-Map's logging mechanisms, combining module-level Python loggers and centralized setup_logging for granular debug output and structured experimental logs.

- Repository: [Robbyant/lingbot-map](https://github.com/Robbyant/lingbot-map)
- Tags: deep-dive
- Published: 2026-07-19

---

**LingBot‑Map employs a hybrid logging architecture that combines module‑level Python loggers for library components with a centralized `setup_logging()` utility for benchmark operations, ensuring granular debug output from neural network layers while providing structured, timestamped log files for experimental runs.**

The Robbyant/lingbot-map repository implements a sophisticated **logging mechanism** strategy using Python’s standard `logging` module. This approach balances decentralized loggers for the core mapping and vision models with a unified configuration utility for the benchmark framework, allowing developers to trace execution from individual transformer layers through complete experimental pipelines.

## Module‑Level Loggers for Core Components

Most Python modules in the LingBot‑Map library create dedicated loggers using `logging.getLogger(__name__)`. This standard pattern assigns each file its own logger namespace, enabling fine‑grained control over verbosity for specific model components.

In [`lingbot_map/models/gct_base.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_base.py) (line 22), the module initializes its logger as:

```python
logger = logging.getLogger(__name__)

```

Similarly, [`lingbot_map/layers/vision_transformer.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/layers/vision_transformer.py) (line 25) demonstrates targeting a specific functional area by using a custom name:

```python
logger = logging.getLogger("dinov2")

```

These **module‑level loggers** inherit the global logging configuration but can be independently tuned, making it easy to suppress noisy layers or elevate debug output from critical model sections without affecting the entire application.

## Centralized Logging for the Benchmark Framework

While the library uses distributed loggers, the benchmark suite relies on a **centralized logging utility** located at [`benchmark/benchmark/utils/logging.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/benchmark/utils/logging.py). This file exposes a `setup_logging()` function (lines 11‑56) that standardizes how experimental runs are recorded.

Entry points such as [`benchmark/run.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/run.py) and [`benchmark/prepare.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/prepare.py) import and invoke this helper to ensure consistent log formatting and output destinations across all benchmark scripts.

### Timestamped Log File Generation

The utility automatically names log files using the pattern `{name}_YYYYMMDD_HHMMSS.log`. As implemented in lines 33‑41 of [`benchmark/benchmark/utils/logging.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/benchmark/utils/logging.py), this timestamped naming prevents file overwrites and creates a chronological record of experimental runs. Log files are written to a user‑specified directory, with debug‑level details captured for post‑hoc analysis.

### Handler Configuration and Propagation Control

The `setup_logging()` function configures a dual‑handler system:

- **File Handler**: Captures all messages at the `DEBUG` level for comprehensive traceability.
- **Console Handler**: Outputs messages at the `INFO` level (configurable) for real‑time monitoring.

To prevent duplicate log lines from bubbling up to the root logger, line 54 explicitly sets `logger.propagate = False`. This isolation ensures that benchmark logs remain clean and that module‑level loggers elsewhere in the codebase do not interfere with the benchmark output format.

## Basic Configuration for Standalone Scripts

For utility scripts that do not require the full benchmark infrastructure, LingBot‑Map uses `logging.basicConfig()` to establish simple console logging. In [`benchmark/report.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/report.py) (lines 13‑18), the script configures a straightforward formatter:

```python
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s"
)

```

This **basic configuration** approach provides immediate feedback for reporting tools without importing the heavier benchmark utilities.

## Summary

- **Hybrid Strategy**: LingBot‑Map uses module‑level loggers (`logging.getLogger(__name__)`) in model files and a centralized `setup_logging()` utility for benchmark operations.
- **Standard Files**: Key implementations reside in [`lingbot_map/models/gct_base.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_base.py), [`lingbot_map/layers/vision_transformer.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/layers/vision_transformer.py), and [`benchmark/benchmark/utils/logging.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/benchmark/utils/logging.py).
- **Timestamped Outputs**: Benchmark logs are automatically named with timestamps (`{name}_YYYYMMDD_HHMMSS.log`) and stored in user‑defined directories.
- **Handler Separation**: The benchmark utility writes debug details to files while streaming info messages to the console, with propagation disabled to prevent duplication.
- **Lightweight Alternative**: Standalone scripts use `logging.basicConfig()` for quick console output.

## Frequently Asked Questions

### How do I add logging to a new benchmark script in LingBot‑Map?

Import the centralized utility from `benchmark.benchmark.utils.logging` and call `setup_logging()` with your desired output directory and log name. This ensures your script respects the project's logging standards, including timestamped filenames and dual handler configuration.

### Why does the benchmark utility set `logger.propagate = False`?

This prevents log messages from being passed to the root logger and appearing multiple times in the output. According to the source code in [`benchmark/benchmark/utils/logging.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/benchmark/utils/logging.py) (line 54), disabling propagation isolates the benchmark logger’s handlers, ensuring clean, non‑duplicate entries in both the log file and console.

### Where are log files stored when running the benchmark suite?

By default, log files are saved to the directory specified when calling `setup_logging()`. The utility automatically generates filenames using the pattern `{name}_YYYYMMDD_HHMMSS.log` (as defined in lines 33‑41 of [`benchmark/benchmark/utils/logging.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/benchmark/utils/logging.py)), making it easy to locate logs for specific runs.

### How do I change the console log level for benchmark runs?

Pass the `console_level` parameter to `setup_logging()`. While the default is `logging.INFO`, you can set it to `logging.DEBUG` or `logging.WARNING` to increase or decrease verbosity in the terminal output. The file handler always captures `DEBUG` level messages regardless of this setting.