Skip to content

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 10 days ago ✏️ Updated 10 days ago
glenn-jocher