Parameters¶
Parameters can be set via EmissionsTracker(), OfflineEmissionsTracker(), the
@track_emissions decorator, config files, or environment variables. See
Configuration for priority order.
PUE
PUE is a multiplication factor provided by the user. Old datacenters have PUE up to 2.2, new greener ones as low as 1.1.
GPU selection
If you use CUDA_VISIBLE_DEVICES to set GPUs, CodeCarbon will automatically
populate gpu_ids. Manual gpu_ids overrides this.
EmissionsTracker / BaseEmissionsTracker¶
EmissionsTracker and OfflineEmissionsTracker inherit from BaseEmissionsTracker.
All parameters are documented below:
codecarbon.emissions_tracker.BaseEmissionsTracker
¶
Bases: ABC
Primary abstraction with Emissions Tracking functionality.
Has two abstract methods, _get_geo_metadata and _get_cloud_metadata
that are implemented by two concrete classes: OfflineCarbonTracker
and CarbonTracker.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_name
|
Optional[str]
|
Project name for current experiment run, default name is "codecarbon". |
_sentinel
|
measure_power_secs
|
Optional[float]
|
Interval (in seconds) to measure hardware power usage, defaults to 15. |
_sentinel
|
api_call_interval
|
Optional[int]
|
Number of measurements between API calls (default: 8). -1: call API only on flush() and at the end. 1: at every measure. 2: every 2 measures, and so on. |
_sentinel
|
api_endpoint
|
Optional[str]
|
Optional URL of Code Carbon API endpoint for sending emissions data. |
_sentinel
|
api_key
|
Optional[str]
|
API key for Code Carbon API (mandatory!). |
_sentinel
|
output_dir
|
Optional[str]
|
Directory path to which the experiment details are logged, defaults to current directory. |
_sentinel
|
output_file
|
Optional[str]
|
Name of the output CSV file, defaults to |
_sentinel
|
save_to_file
|
Optional[bool]
|
Indicates if the emission artifacts should be logged to a file, defaults to True. |
_sentinel
|
save_to_api
|
Optional[bool]
|
Indicates if the emission artifacts should be sent to the CodeCarbon API, defaults to False. |
_sentinel
|
save_to_logger
|
Optional[bool]
|
Indicates if the emission artifacts should be written to a dedicated logger, defaults to False. |
_sentinel
|
logging_logger
|
Optional[LoggerOutput]
|
LoggerOutput object encapsulating a logging.logger or a Google Cloud logger. |
_sentinel
|
save_to_prometheus
|
Optional[bool]
|
Indicates if the emission artifacts should be pushed to prometheus, defaults to False. |
_sentinel
|
save_to_logfire
|
Optional[bool]
|
Indicates if the emission artifacts should be written to a logfire observability platform, defaults to False. |
_sentinel
|
prometheus_url
|
Optional[str]
|
url of the prometheus server, defaults to |
_sentinel
|
output_handlers
|
Optional[List[BaseOutput]]
|
List of custom output handlers to use. Defaults to []. |
_sentinel
|
gpu_ids
|
Optional[List]
|
Comma-separated list of GPU ids to track, defaults to None. Can be integer indexes of GPUs on the system, or prefixes to match against GPU identifiers. See NVIDIA docs on CUDA environment variables. |
_sentinel
|
emissions_endpoint
|
Optional[str]
|
Optional URL of http endpoint for sending emissions data. |
_sentinel
|
experiment_id
|
Optional[str]
|
Id of the experiment. |
_sentinel
|
experiment_name
|
Optional[str]
|
Label of the experiment |
_sentinel
|
electricitymaps_api_token
|
Optional[str]
|
API token for electricitymaps.com (formerly co2signal.com) |
_sentinel
|
co2_signal_api_token
|
Optional[str]
|
[DEPRECATED] Use electricitymaps_api_token instead. Old parameter name for backward compatibility. |
_sentinel
|
tracking_mode
|
Optional[str]
|
One of "process" or "machine" in order to measure the power consumption due to the entire machine or to try and isolate the tracked processe's in isolation. Defaults to "machine". |
_sentinel
|
log_level
|
Optional[Union[int, str]]
|
Global codecarbon log level. Accepts one of: {"debug", "info", "warning", "error", "critical"}. Defaults to "info". |
_sentinel
|
on_csv_write
|
Optional[str]
|
When calling tracker.flush() manually: "update" to overwrite the existing run_id row, or "append" to add a new row to the CSV file. Defaults to "append". |
_sentinel
|
logger_preamble
|
Optional[str]
|
String to systematically include in the logger. messages. Defaults to "". |
_sentinel
|
force_cpu_power
|
Optional[int]
|
Force the CPU max power consumption in watts. Use this if you know the TDP of your machine. |
_sentinel
|
force_ram_power
|
Optional[int]
|
Force the RAM power consumption in watts. Use this if you know
the power consumption of your RAM. Estimate with
|
_sentinel
|
pue
|
Optional[float]
|
PUE (Power Usage Effectiveness) of the data center where the experiment is being run. |
_sentinel
|
force_mode_cpu_load
|
Optional[bool]
|
Force the addition of a CPU in MODE_CPU_LOAD |
_sentinel
|
allow_multiple_runs
|
Optional[bool]
|
Allow multiple CodeCarbon instances on the same machine. Defaults to True since v3 (was False in v2). |
_sentinel
|
wue
|
Optional[float]
|
WUE (Water Usage Effectiveness) of the data center. Units of L/kWh: litres of water consumed per kilowatt-hour of electricity consumed. |
_sentinel
|
rapl_include_dram
|
Optional[bool]
|
Include DRAM (memory) power in RAPL measurements on Linux, defaults to False. When True, measures CPU package + DRAM. Only affects systems where RAPL exposes separate DRAM domains. |
_sentinel
|
rapl_prefer_psys
|
Optional[bool]
|
Prefer psys (platform) RAPL domain over package domains on Linux, defaults to False. When True, uses total platform power (CPU + chipset + PCIe). When False, uses package domains which are more reliable. Note: psys can report higher values than CPU TDP and may be unreliable on older systems. |
_sentinel
|
OfflineEmissionsTracker (additional parameters)¶
OfflineEmissionsTracker adds these parameters for offline mode:
codecarbon.emissions_tracker.OfflineEmissionsTracker
¶
Bases: BaseEmissionsTracker
Offline implementation of the EmissionsTracker
In addition to the standard arguments, the following are required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso_code
|
Optional[str]
|
3-letter ISO code of the country where the experiment is being run. See global_energy_mix.json for available countries. |
_sentinel
|
region
|
Optional[str]
|
Optional Province/State/City where the infrastructure is hosted. Supported for US States and Canada (e.g. California, New York). |
_sentinel
|
cloud_provider
|
Optional[str]
|
The cloud provider specified for estimating emissions intensity, defaults to None. See https://github.com/mlco2/codecarbon/ blob/master/codecarbon/data/cloud/impact.csv for a list of cloud providers |
_sentinel
|
cloud_region
|
Optional[str]
|
The region of the cloud data center, defaults to None. See https://github.com/mlco2/codecarbon/ blob/master/codecarbon/data/cloud/impact.csv for a list of cloud regions. |
_sentinel
|
country_2letter_iso_code
|
Optional[str]
|
For use with the Electricity Maps emissions API. See http://api.electricitymap.org/v3/zones for a list of codes and their corresponding locations. |
_sentinel
|
@track_emissions Decorator¶
The decorator accepts the same parameters as EmissionsTracker, plus offline
and country_iso_code for offline mode:
codecarbon.emissions_tracker.track_emissions
¶
Decorator that supports both EmissionsTracker and OfflineEmissionsTracker
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fn
|
Callable
|
Function to be decorated |
None
|
project_name
|
Optional[str]
|
Project name for current experiment run, default name is "codecarbon". |
_sentinel
|
measure_power_secs
|
Optional[int]
|
Interval (in seconds) to measure hardware power usage, defaults to 15. |
_sentinel
|
api_call_interval
|
int
|
Number of measure to make before calling the Code Carbon API. |
_sentinel
|
api_endpoint
|
Optional[str]
|
Optional URL of Code Carbon API endpoint for sending emissions data. |
_sentinel
|
api_key
|
Optional[str]
|
API key for Code Carbon API (mandatory!). |
_sentinel
|
output_dir
|
Optional[str]
|
Directory path to which the experiment details are logged, defaults to current directory. |
_sentinel
|
output_file
|
Optional[str]
|
Name of output CSV file, defaults to |
_sentinel
|
save_to_file
|
Optional[bool]
|
Indicates if the emission artifacts should be logged to a file, defaults to True. |
_sentinel
|
save_to_api
|
Optional[bool]
|
Indicates if the emission artifacts should be send to the CodeCarbon API, defaults to False. |
_sentinel
|
save_to_logger
|
Optional[bool]
|
Indicates if the emission artifacts should be written to a dedicated logger, defaults to False. |
_sentinel
|
logging_logger
|
Optional[LoggerOutput]
|
LoggerOutput object encapsulating a logging.logger or a Google Cloud logger. |
_sentinel
|
save_to_prometheus
|
Optional[bool]
|
Indicates if the emission artifacts should be pushed to prometheus, defaults to False. |
_sentinel
|
save_to_logfire
|
Optional[bool]
|
Indicates if the emission artifacts should be pushed to logfire, defaults to False. |
_sentinel
|
prometheus_url
|
Optional[str]
|
url of the prometheus server, defaults to |
_sentinel
|
output_handlers
|
Optional[List[BaseOutput]]
|
List of output handlers to use. |
_sentinel
|
gpu_ids
|
Optional[List]
|
User-specified known gpu ids to track. Defaults to None, which means that all available gpus will be tracked. It needs to be a list of integers or a comma-separated string. Valid examples: [1, 3, 4] or "1,2". |
_sentinel
|
emissions_endpoint
|
Optional[str]
|
Optional URL of http endpoint for sending emissions data. |
_sentinel
|
experiment_id
|
Optional[str]
|
Id of the experiment. |
_sentinel
|
experiment_name
|
Optional[str]
|
Label of the experiment |
_sentinel
|
electricitymaps_api_token
|
Optional[str]
|
API token for electricitymaps.com (formerly co2signal.com) |
_sentinel
|
co2_signal_api_token
|
Optional[str]
|
[DEPRECATED] Use electricitymaps_api_token instead. Old parameter name for backward compatibility. |
_sentinel
|
tracking_mode
|
Optional[str]
|
One of "process" or "machine" in order to measure the power consumption due to the entire machine or to try and isolate the tracked processe's in isolation. Defaults to "machine". |
_sentinel
|
log_level
|
Optional[Union[int, str]]
|
Global codecarbon log level. Accepts one of: {"debug", "info", "warning", "error", "critical"}. Defaults to "info". |
_sentinel
|
on_csv_write
|
Optional[str]
|
When calling tracker.flush() manually: "update" to overwrite the existing run_id row, or "append" to add a new row. Defaults to "append". |
_sentinel
|
logger_preamble
|
Optional[str]
|
String to systematically include in the logger. messages. Defaults to "". |
_sentinel
|
allow_multiple_runs
|
Optional[bool]
|
Allow multiple CodeCarbon instances on the same machine. Defaults to True since v3 (was False in v2). |
_sentinel
|
offline
|
Optional[bool]
|
Run the tracker in offline mode, defaults to False. |
_sentinel
|
country_iso_code
|
Optional[str]
|
3-letter ISO code of the country where the experiment is being run. Required if offline=True. See global_energy_mix.json. |
_sentinel
|
region
|
Optional[str]
|
Optional Province/State/City where the infrastructure is hosted. Supported for US States (e.g. California, New York). |
_sentinel
|
cloud_provider
|
Optional[str]
|
The cloud provider specified for estimating emissions intensity, defaults to None. See https://github.com/mlco2/codecarbon/ blob/master/codecarbon/data/cloud/impact.csv for a list of cloud providers. |
_sentinel
|
cloud_region
|
Optional[str]
|
The region of the cloud data center, defaults to None. See https://github.com/mlco2/codecarbon/ blob/master/codecarbon/data/cloud/impact.csv for a list of cloud regions. |
_sentinel
|
country_2letter_iso_code
|
Optional[str]
|
For use with the Electricity Maps emissions API. See http://api.electricitymap.org/v3/zones for a list of codes and their corresponding locations. |
_sentinel
|
force_cpu_power
|
Optional[int]
|
Force the CPU max power consumption in watts. Use if you know the TDP of your machine. |
_sentinel
|
force_ram_power
|
Optional[int]
|
Force the RAM power consumption in watts. Estimate with
|
_sentinel
|
pue
|
Optional[float]
|
PUE (Power Usage Effectiveness) of the data center. |
_sentinel
|
wue
|
Optional[float]
|
WUE (Water Usage Effectiveness) of the data center. Units of L/kWh: litres of water consumed per kilowatt-hour of electricity consumed. |
_sentinel
|
rapl_include_dram
|
Optional[bool]
|
Include DRAM in RAPL measurements on Linux (default: False). When True, measures CPU package + DRAM. |
_sentinel
|
rapl_prefer_psys
|
Optional[bool]
|
Prefer psys over package domains for RAPL on Linux (default: False). When True, uses total platform power. |
_sentinel
|
Returns:
| Type | Description |
|---|---|
|
The decorated function |