feat: codecarbon monitor -- any_command

[inimaz]

Description

Add to the cli the ability to run codecarbon with any other tool.

codecarbon run -- bash -c 'echo "Processing..."; sleep 20; echo "Done!"'

Output in my console

~/: uv run codecarbon run -- bash -c 'echo "Processing..."; sleep 30; e
cho "Done!"'

🌱 CodeCarbon: Starting emissions tracking...
   Command: bash -c echo "Processing..."; sleep 30; echo "Done!"

Processing...
Done!

============================================================
🌱 CodeCarbon Emissions Report
============================================================
   Command: bash -c echo "Processing..."; sleep 30; echo "Done!"
   Emissions: 0.0317 g CO2eq
   Saved to: /home/inigo/personal/codecarbon/emissions.csv
   ⚠️  Note: Measured entire machine (includes all system processes)
============================================================

Motivation and Context

Non-python users will be able to run their commands and measure the machine emissions while running those commands.

Basic Usage

codecarbon run -- <command> [arguments...]

The -- separator is required to separate CodeCarbon options from your command.

Simple Examples

• Track a bash one-liner:

codecarbon run -- bash -c 'echo "Processing..."; sleep 3; echo "Done!"'

• Track a CPU-intensive calculation:

codecarbon run -- bash -c 'for i in {1..1000}; do echo "scale=100; a(1)*4" | bc -l > /dev/null; done; echo "Calculation complete!"'

• Track a Node.js script:

codecarbon run -- node my_script.js

• Track a Python script (although better to use the EmissionTracker directly):

codecarbon run -- python examples/mnist.py

• Track file compression:

codecarbon run -- tar -czf archive.tar.gz large_directory/

• Track image processing (requires ImageMagick):

codecarbon run -- convert input.jpg -resize 50% output.jpg

• Track video encoding (requires ffmpeg):

codecarbon run -- ffmpeg -i input.mp4 -c:v libx264 output.mp4

• Any command you can run on the cli

codecarbon run -- YOUR_COMMAND_HERE

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)
• [x ] 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.

• [x ] My code follows the code style of this project.
• [ x] 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.

[benoit-cty]

Nice !
It will close #382

Did you have a look to #431 ?

Do we need to add a warning about code execution ? Maybe not as the command is for this purpose and won't change user privilege ?

[inimaz]

Ah sorry I was not at all aware of #431! Checking it now

[inimaz]

Do we need to add a warning about code execution ? Maybe not as the command is for this purpose and won't change user privilege ?

@benoit-cty it launches exactly what the user wants to launch, so I guess no need for a warning? If it is unsafe code it is unsafe with or without codecarbon run

[SaboniAmine]

Thanks Inigo!

[benoit-cty]

@copilot Please add a documentation in docs/edit/usage.rst for this new feature.

[Copilot]

@benoit-cty I've opened a new pull request, #1045, to work on those changes. Once the pull request is ready, I'll request review from you.

[benoit-cty]

I was about to merge this PR in the 3.2.2 release but with all my modification for sub-process it's more a 3.3.

I think it's better to have sub-process monitor for this PR as it make sense to monitor only the program in parameter.

What do you think ?

[inimaz]

Sounds good @benoit-cty , does this mean we can monitor now exactly the process and the other processes do not affect the measurement?
Another topic, just about semantics. I proposed codecarbon run -- but now thinking about it, should we use instead codecarbon monitor --? Since codecarbon is just monitoring what is being run and not editing anything...

[benoit-cty]

Sounds good @benoit-cty , does this mean we can monitor now exactly the process and the other processes do not affect the measurement?

Process monitoring works for RAM and CPU, not for GPU.

Another topic, just about semantics. I proposed codecarbon run -- but now thinking about it, should we use instead codecarbon monitor --? Since codecarbon is just monitoring what is being run and not editing anything...

Yes, I'm OK with that proposition 👍

[inimaz]

Sounds good, will take a look at it tmw

[codecov]

Codecov Report

❌ Patch coverage is 73.78641% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.75%. Comparing base (cc62d32) to head (db49e56).
⚠️ Report is 5 commits behind head on master.

Files with missing lines	Patch %	Lines
codecarbon/cli/monitor.py	67.27%	18 Missing ⚠️
codecarbon/external/hardware.py	86.84%	5 Missing ⚠️
codecarbon/cli/main.py	60.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1004      +/-   ##
==========================================
+ Coverage   68.73%   69.75%   +1.02%     
==========================================
  Files          41       42       +1     
  Lines        3873     3971      +98     
==========================================
+ Hits         2662     2770     +108     
+ Misses       1211     1201      -10     

☔ View full report in Codecov by Sentry.
📢 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.