Skip to content

Register now for

# Reference for `ultralytics/utils/logger.py`

Note

This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/utils/logger.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!

## `` ultralytics.utils.logger.ConsoleLogger

    ConsoleLogger(destination)

Console output capture with API/file streaming and deduplication.

Captures stdout/stderr output and streams it to either an API endpoint or local file, with intelligent deduplication to reduce noise from repetitive console output.

Attributes:

Name | Type | Description
--- | --- | ---
`destination` | `str | Path` | Target destination for streaming (URL or Path object).
`is_api` | `bool` | Whether destination is an API endpoint (True) or local file (False).
`original_stdout` |  | Reference to original sys.stdout for restoration.
`original_stderr` |  | Reference to original sys.stderr for restoration.
`log_queue` | `Queue` | Thread-safe queue for buffering log messages.
`active` | `bool` | Whether console capture is currently active.
`worker_thread` | `Thread` | Background thread for processing log queue.
`last_line` | `str` | Last processed line for deduplication.
`last_time` | `float` | Timestamp of last processed line.
`last_progress_line` | `str` | Last progress bar line for progress deduplication.
`last_was_progress` | `bool` | Whether the last line was a progress bar.

Examples:

Basic file logging:

    >>> logger = ConsoleLogger("training.log")
    >>> logger.start_capture()
    >>> print("This will be logged")
    >>> logger.stop_capture()

API streaming:

    >>> logger = ConsoleLogger("https://api.example.com/logs")
    >>> logger.start_capture()
    >>> # All output streams to API
    >>> logger.stop_capture()

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`destination` | `str | Path` | API endpoint URL (http/https) or local file path for streaming output. | required

Source code in `ultralytics/utils/logger.py`

    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    def __init__(self, destination):
        """
        Initialize with API endpoint or local file path.

        Args:
            destination (str | Path): API endpoint URL (http/https) or local file path for streaming output.
        """
        self.destination = destination
        self.is_api = isinstance(destination, str) and destination.startswith(("http://", "https://"))
        if not self.is_api:
            self.destination = Path(destination)

        # Console capture
        self.original_stdout = sys.stdout
        self.original_stderr = sys.stderr
        self.log_queue = queue.Queue(maxsize=1000)
        self.active = False
        self.worker_thread = None

        # State tracking
        self.last_line = ""
        self.last_time = 0.0
        self.last_progress_line = ""  # Track last progress line for deduplication
        self.last_was_progress = False  # Track if last line was a progress bar

### `` start_capture

    start_capture()

Start capturing console output and redirect stdout/stderr to custom capture objects.

Source code in `ultralytics/utils/logger.py`

    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    def start_capture(self):
        """Start capturing console output and redirect stdout/stderr to custom capture objects."""
        if self.active:
            return

        self.active = True
        sys.stdout = self._ConsoleCapture(self.original_stdout, self._queue_log)
        sys.stderr = self._ConsoleCapture(self.original_stderr, self._queue_log)

        # Hook Ultralytics logger
        try:
            handler = self._LogHandler(self._queue_log)
            logging.getLogger("ultralytics").addHandler(handler)
        except Exception:
            pass

        self.worker_thread = threading.Thread(target=self._stream_worker, daemon=True)
        self.worker_thread.start()

### `` stop_capture

    stop_capture()

Stop capturing console output and restore original stdout/stderr.

Source code in `ultralytics/utils/logger.py`

     99
    100
    101
    102
    103
    104
    105
    106
    107
    def stop_capture(self):
        """Stop capturing console output and restore original stdout/stderr."""
        if not self.active:
            return

        self.active = False
        sys.stdout = self.original_stdout
        sys.stderr = self.original_stderr
        self.log_queue.put(None)

## `` ultralytics.utils.logger.SystemLogger

    SystemLogger()

Log dynamic system metrics for training monitoring.

Captures real-time system metrics including CPU, RAM, disk I/O, network I/O, and NVIDIA GPU statistics for training performance monitoring and analysis.

Attributes:

Name | Type | Description
--- | --- | ---
`pynvml` |  | NVIDIA pynvml module instance if successfully imported, None otherwise.
`nvidia_initialized` | `bool` | Whether NVIDIA GPU monitoring is available and initialized.
`net_start` |  | Initial network I/O counters for calculating cumulative usage.
`disk_start` |  | Initial disk I/O counters for calculating cumulative usage.

Examples:

Basic usage:

    >>> logger = SystemLogger()
    >>> metrics = logger.get_metrics()
    >>> print(f"CPU: {metrics['cpu']}%, RAM: {metrics['ram']}%")
    >>> if metrics["gpus"]:
    ...     gpu0 = metrics["gpus"]["0"]
    ...     print(f"GPU0: {gpu0['usage']}% usage, {gpu0['temp']}°C")

Training loop integration:

    >>> system_logger = SystemLogger()
    >>> for epoch in range(epochs):
    ...     # Training code here
    ...     metrics = system_logger.get_metrics()
    ...     # Log to database/file

Source code in `ultralytics/utils/logger.py`

    259
    260
    261
    262
    263
    264
    265
    266
    def __init__(self):
        """Initialize the system logger."""
        import psutil  # scoped as slow import

        self.pynvml = None
        self.nvidia_initialized = self._init_nvidia()
        self.net_start = psutil.net_io_counters()
        self.disk_start = psutil.disk_io_counters()

### `` get_metrics

    get_metrics()

Get current system metrics.

Collects comprehensive system metrics including CPU usage, RAM usage, disk I/O statistics, network I/O statistics, and GPU metrics (if available). Example output:

    metrics = {
        "cpu": 45.2,
        "ram": 78.9,
        "disk": {"read_mb": 156.7, "write_mb": 89.3, "used_gb": 256.8},
        "network": {"recv_mb": 157.2, "sent_mb": 89.1},
        "gpus": {
            0: {"usage": 95.6, "memory": 85.4, "temp": 72, "power": 285},
            1: {"usage": 94.1, "memory": 82.7, "temp": 70, "power": 278},
        },
    }

- cpu (float): CPU usage percentage (0-100%)
- ram (float): RAM usage percentage (0-100%)
- disk (dict):
  - read_mb (float): Cumulative disk read in MB since initialization
  - write_mb (float): Cumulative disk write in MB since initialization
  - used_gb (float): Total disk space used in GB
- network (dict):
  - recv_mb (float): Cumulative network received in MB since initialization
  - sent_mb (float): Cumulative network sent in MB since initialization
- gpus (dict): GPU metrics by device index (e.g., 0, 1) containing:
  - usage (int): GPU utilization percentage (0-100%)
  - memory (float): CUDA memory usage percentage (0-100%)
  - temp (int): GPU temperature in degrees Celsius
  - power (int): GPU power consumption in watts

Returns:

Name | Type | Description
--- | --- | ---
`metrics` | `dict` | System metrics containing 'cpu', 'ram', 'disk', 'network', 'gpus' with respective usage data.

Source code in `ultralytics/utils/logger.py`

    279
    280
    281
    282
    283
    284
    285
    286
    287
    288
    289
    290
    291
    292
    293
    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333
    334
    335
    336
    337
    338
    339
    340
    341
    342
    343
    def get_metrics(self):
        """
        Get current system metrics.

        Collects comprehensive system metrics including CPU usage, RAM usage, disk I/O statistics,
        network I/O statistics, and GPU metrics (if available). Example output:

        ```python
        metrics = {
            "cpu": 45.2,
            "ram": 78.9,
            "disk": {"read_mb": 156.7, "write_mb": 89.3, "used_gb": 256.8},
            "network": {"recv_mb": 157.2, "sent_mb": 89.1},
            "gpus": {
                0: {"usage": 95.6, "memory": 85.4, "temp": 72, "power": 285},
                1: {"usage": 94.1, "memory": 82.7, "temp": 70, "power": 278},
            },
        }
        ```

        - cpu (float): CPU usage percentage (0-100%)
        - ram (float): RAM usage percentage (0-100%)
        - disk (dict):
            - read_mb (float): Cumulative disk read in MB since initialization
            - write_mb (float): Cumulative disk write in MB since initialization
            - used_gb (float): Total disk space used in GB
        - network (dict):
            - recv_mb (float): Cumulative network received in MB since initialization
            - sent_mb (float): Cumulative network sent in MB since initialization
        - gpus (dict): GPU metrics by device index (e.g., 0, 1) containing:
            - usage (int): GPU utilization percentage (0-100%)
            - memory (float): CUDA memory usage percentage (0-100%)
            - temp (int): GPU temperature in degrees Celsius
            - power (int): GPU power consumption in watts

        Returns:
            metrics (dict): System metrics containing 'cpu', 'ram', 'disk', 'network', 'gpus' with respective usage data.
        """
        import psutil  # scoped as slow import

        net = psutil.net_io_counters()
        disk = psutil.disk_io_counters()
        memory = psutil.virtual_memory()
        disk_usage = shutil.disk_usage("/")

        metrics = {
            "cpu": round(psutil.cpu_percent(), 3),
            "ram": round(memory.percent, 3),
            "disk": {
                "read_mb": round((disk.read_bytes - self.disk_start.read_bytes) / (1 << 20), 3),
                "write_mb": round((disk.write_bytes - self.disk_start.write_bytes) / (1 << 20), 3),
                "used_gb": round(disk_usage.used / (1 << 30), 3),
            },
            "network": {
                "recv_mb": round((net.bytes_recv - self.net_start.bytes_recv) / (1 << 20), 3),
                "sent_mb": round((net.bytes_sent - self.net_start.bytes_sent) / (1 << 20), 3),
            },
            "gpus": {},
        }

        # Add GPU metrics (NVIDIA only)
        if self.nvidia_initialized:
            metrics["gpus"].update(self._get_nvidia_metrics())

        return metrics

📅 Created 28 days ago ✏️ Updated 28 days ago