perf: reduce tracker cold-start and concurrent measurement overhead

[davidberenstein1957]

Summary

This PR reduces CodeCarbon measurement launch latency and improves concurrent-run throughput while preserving existing behavior. Changes focus on deferring work until it is needed, caching hardware detection within a process, and slimming import paths.

Performance results — cold launch (offline Mac ARM)

Metric	Before	After	Improvement
Tracker __init__	~15.7 s	~94 ms	~99% faster
start() (cold)	~1.0 s	~194 ms	~81% faster
First sample (cold)	~18.2 s	~288 ms	~98% faster (~63×)
Warm lifecycle (init+start+stop, same process)	~62 ms	~6 ms	~10×
CLI monitor subprocess overhead (codecarbon monitor … sleep 2)	~1.5 s	~900–1000 ms	~35–40% faster

Cold-path numbers are the first tracker in a fresh process; warm-path numbers reuse cached hardware within the same process.

Performance results — run throughput (offline, warm, same process)

Repeated OfflineEmissionsTracker(output_methods=[]) lifecycles (init → start → stop) in one Python process:

Mode	Before	After	Improvement
Sequential runs / min	~926	~2,200	~2.4×
Parallel runs / min (8 threads)	~7,268	~12,300	~1.7×
Warm run latency (p50)	~62 ms	~6 ms	~10×

Before = master baseline (2026-06-17); after = hardware cache + warm lifecycle optimizations. Parallel benchmark: 8 worker threads, 15 s sustained load.

What changed

Tracker lifecycle

• Lazy-import heavy modules; defer hardware probing, geo validation, and emissions engine until first use
• Skip 1 Hz power monitor when output_methods=[]; skip redundant measurement on stop() when a sample was just taken
• Global cpu_percent prime once per process

Hardware detection

• Process-level hardware setup cache (hardware_cache.py) — CPU/GPU/RAM detection reused across instances
• Platform-aware CPU backend order; cached GPU/CPU/PowerMetrics probes via @lru_cache

API write path

• Lazy POST /runs — deferred until first emission upload (create_run_automatically=False + _ensure_api_run)

CLI

• Lazy imports in cli/main.py for faster codecarbon monitor startup
• Single entry point: codecarbon monitor (with optional --log-level)

Docs

• Fix --log-level default in CLI reference (ERROR, not INFO)
• FAQ note explaining warm hardware reuse within one Python process

Intentionally not included

These were explored during the perf work but removed to keep the diff focused on high-impact changes:

• Process-level output handler cache, config cache, HTTP session pooling, and ApiClient pooling
• Separate codecarbon-monitor console script
• Benchmark scripts and carbonserver Docker startup shortcuts

Test plan

• CODECARBON_ALLOW_MULTIPLE_RUNS=True pytest --ignore=tests/test_viz_data.py -m 'not integ_test' tests/ (541 passed locally)
• tests/test_hardware_cache.py — cache hit/miss, clear_cache, round-trip reuse
• CLI monitor tests — offline validation, --log-level, wrapped-command delegation
• Manual: codecarbon monitor --offline --country-iso-code FRA -- sleep 1
• Manual: codecarbon monitor --offline --country-iso-code FRA --log-level debug -- python train.py

Notes

Throughput numbers captured on offline Mac ARM (2026-06-18). The first tracker in a process is slower than subsequent ones because hardware detection runs once and is reused — see the FAQ.

[codecov]

Codecov Report

❌ Patch coverage is 97.33728% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.35%. Comparing base (58acafa) to head (8ccb30e).

Files with missing lines	Patch %	Lines
codecarbon/core/resource_tracker.py	86.00%	7 Missing ⚠️
codecarbon/core/hardware_cache.py	98.30%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1246      +/-   ##
==========================================
+ Coverage   89.17%   89.35%   +0.17%     
==========================================
  Files          47       48       +1     
  Lines        4510     4762     +252     
==========================================
+ Hits         4022     4255     +233     
- Misses        488      507      +19     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[inimaz]

Nice @davidberenstein1957 thanks a lot for taking a look at this. There are many improvements done at once here. Maybe can you split it into smaller PRs? Like this it will be easier to review. I add some comments already.

[inimaz]

Do not delete this, if we are using pandas only for typing we can do

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    import pandas as pd

[inimaz]

Same

[inimaz]

Same in this file

[inimaz]

Let's do an Enum out of these strings