Description

AI Disclaimer : code created with Codex-CLI and GPT5-mini, then Copilot+Claude Sonnet 4.5

Problem

CodeCarbon was not properly handling systems with multiple RAPL providers (e.g., intel-rapl and intel-rapl-mmio in /sys/devices/virtual/powercap/). Permission errors on one provider (like intel-rapl-mmio) would cause the entire tracker to fail, even when another provider had readable domains.

Solution

Updated the RAPL scanning logic to:

1. Scan all common RAPL locations (when using the default path):

   • /sys/class/powercap/intel-rapl/subsystem
   • /sys/class/powercap/intel-rapl (parent)
   • /sys/class/powercap
   • /sys/devices/virtual/powercap ← Now includes intel-rapl-mmio

2. Gracefully handle permission errors:

   • Permission errors on individual domains are logged as warnings
   • Tracker continues to work with readable domains
   • Only fails if NO readable main/package domain is found

3. Smart path selection for testing:

   • Production (default path): Scans all system locations
   • Testing (custom path): Only scans the provided directory to avoid system interference

Files Modified

codecarbon/core/cpu.py

• is_rapl_available(): Updated to scan all RAPL providers, distinguish between default and custom paths
• IntelRAPL._fetch_rapl_files(): Updated to scan all providers, handle permission errors gracefully, track availability

Test Files

• tests/test_cpu.py: Updated TestIntelRAPL.setUp() to create proper RAPL hierarchy (rapl_dir/intel-rapl/intel-rapl:N/)
• tests/test_rapl_permissions.py: Updated tests to use proper RAPL provider structure
• tests/test_rapl_mmio_scanning.py: New comprehensive tests for multi-provider scenarios

Behavior

Production (Default Path)

rapl = IntelRAPL()  # Uses default path
# Scans:
# - /sys/class/powercap/intel-rapl/subsystem
# - /sys/class/powercap/intel-rapl
# - /sys/class/powercap
# - /sys/devices/virtual/powercap  ← Finds intel-rapl-mmio here

Testing (Custom Path)

rapl = IntelRAPL(rapl_dir="/tmp/test/rapl")
# Only scans:
# - /tmp/test/rapl
# - /tmp/test  (parent)
# Avoids interference with system /sys files

Example Real System Structure

/sys/devices/virtual/powercap/
├── intel-rapl/
│   ├── intel-rapl:0/  (package-0)
│   │   ├── energy_uj
│   │   ├── intel-rapl:0:0/  (core)
│   │   ├── intel-rapl:0:1/  (uncore)
│   │   └── intel-rapl:0:2/  (dram)
│   └── intel-rapl:1/  (psys)
│       └── energy_uj
└── intel-rapl-mmio/
    └── intel-rapl-mmio:0/  (package-0)
        ├── energy_uj  ← May have permission errors
        └── intel-rapl-mmio:0:0/  (core)
            └── energy_uj

Key Features

✅ Discovers all RAPL providers (intel-rapl, intel-rapl-mmio, etc.)
✅ Handles permission errors gracefully (warns and continues)
✅ Only fails if no readable main domain is found
✅ Test isolation (custom paths don't scan system files)
✅ Backward compatible (existing code continues to work)

Test Coverage

All tests passing:

• tests/test_cpu.py::TestIntelRAPL (2 tests)
• tests/test_rapl_permissions.py (2 tests)
• tests/test_rapl_mmio_scanning.py (2 tests - NEW)

Example Output

When intel-rapl-mmio has permission issues:

[codecarbon WARNING] Permission denied reading RAPL file /sys/devices/virtual/powercap/intel-rapl-mmio/intel-rapl-mmio:0/energy_uj. You can grant read permission with: sudo chmod -R a+r /sys/class/powercap/*; skipping.
[codecarbon INFO] Tracking Intel CPU via RAPL interface
✓ Using readable domains from intel-rapl provider

Migration Notes

No changes required for existing code. The tracker will automatically:

1. Discover and use all available RAPL providers
2. Skip unreadable domains with warnings
3. Continue working with any readable main/package domain

To grant permissions for all RAPL files:

sudo chmod -R a+r /sys/class/powercap/*
sudo chmod -R a+r /sys/devices/virtual/powercap/*

Related Issue

Will close #915

How Has This Been Tested?

• tests/test_rapl_permissions.py:
  • test_main_rapl_permission_error: ensures initialization raises when the main intel-rapl:0/energy_uj is unreadable.
  • test_non_main_rapl_permission_warning_and_skip: ensures unreadable non-main domains are skipped and a warning is logged.
• Tests use tmp_path and are Linux-only (they simulate sysfs trees and change file permissions).

Types of changes

What types of changes does your code introduce? Put an x in all the boxes that apply:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

Go over all the following points, and put an x in all the boxes that apply.

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING.md document.
• I have added tests to cover my changes.
• All new and existing tests passed.