Parameters

A set of parameters are supported by API to help users provide additional details per project.

Input Parameters

Input Parameters

Parameter

Description

project_name

Name of the project, defaults to codecarbon

experiment_id

Id of the experiment

measure_power_secs

Interval (in seconds) to measure hardware power usage, defaults to 15

tracking_mode

machine measure the power consumptions of the entire machine (defaults)
process try and isolate the tracked processes in isolation

gpu_ids

Comma-separated list of GPU ids to track, defaults to None
These can either be integer indexes of GPUs on the system, or prefixes
to match against GPU identifiers as described here

log_level

Global codecarbon log level (by order of verbosity): “debug”, “info” (defaults),
“warning”, “error”, or “critical”

co2_signal_api_token

API token for co2signal.com (requires sign-up for free beta)

pue

PUE (Power Usage Effectiveness) of the data center
where the experiment is being run.

force_cpu_power

Force the CPU max power consumption in watts,
use this if you know the TDP of your machine.
(POWER_CONSTANT x CONSUMPTION_PERCENTAGE)

force_ram_power

Force the RAM power consumption in watts,
use this if you know the power consumption of your RAM.
Estimate it with sudo lshw -C memory -short | grep DIMM
to get the number of RAM slots used, then do
RAM power in W = Number of RAM Slots * 5 Watts

allow_multiple_runs

Boolean variable indicating if multiple instance of CodeCarbon
on the same machine is allowed,
defaults to True since v3. Used to be False in v2.

PUE is a multiplication factor provided by the user, so it is up to the user to get it from his cloud provider. Old data-centers have a PUE up to 2.2, where new green one could be as low as 1.1.

If you, or your provider, use CUDA_VISIBLE_DEVICES to set the GPU you want to use, CodeCarbon will automaticly set this value to gpu_ids. If you set gpu_ids manually, it will override the CUDA_VISIBLE_DEVICES for CodeCarbon measures.

Output parameters

Output Parameters

Parameter

Description

save_to_file

Boolean variable indicating if the emission artifacts should be logged
to a CSV file, defaults to True

output_dir

Directory path to which the experiment details are logged
defaults to current directory

output_file

Name of output CSV file
defaults to emissions.csv

on_csv_write

When calling tracker.flush() manually choose if
- update the existing run_id row (erasing former data)
- append add a new row to CSV file (defaults)

save_to_api

Boolean variable indicating if emissions artifacts should be logged
to the CodeCarbon API, defaults to False

api_endpoint:

Optional URL of CodeCarbon API endpoint for sending emissions data
defaults to “https://api.codecarbon.io

api_key

API key for the CodeCarbon API (mandatory to use this API!)

api_call_interval

Number of measurements between API calls (defaults to 8):
-1 : call API on flush() and at the end
1 : at every measure
2 : at every 2 measure, and so on

save_to_logger

Boolean variable indicating if the emission artifacts should be written
to a dedicated logger, defaults to False

logging_logger

LoggerOutput object encapsulating a logging.Logger or a Google Cloud logger

logger_preamble

String to systematically include in the logger’s messages (defaults to “”)

save_to_prometheus

Boolean variable indicating if the emission artifacts should be written
to a Prometheus server, defaults to False

prometheus_url

URL of the Prometheus server

save_to_logfire

Boolean variable indicating if the emission artifacts should be written
to a LogFire server, defaults to False

output_handlers

List of output handlers to use for saving the emissions data
defaults to []

Specific parameters for offline mode

Input Parameters to OfflineEmissionsTracker

Parameter

Description

country_iso_code

3-letter ISO Code of the country
where the experiment is being run.
Available countries are listed in global_energy_mix.json

region

Optional Name of the Province/State/City, where the infrastructure is hosted
Currently, supported only for US States and Canada
for example - California or New York, from the list

cloud_provider

The cloud provider specified for estimating emissions intensity,
defaults to None. See impact.csv for a list of cloud providers

cloud_region

The region of the cloud data center, defaults to None
See impact.csv for a list of cloud regions.

country_2letter_iso_code

For use with the Electricity Maps emissions API.
See Electricity Maps zones for a list of codes and their locations.

@track_emissions

Decorator track_emissions in addition to standard arguments, requires the following parameters:

Input Parameters to @track_emissions

Parameter

Description

fn

function to be decorated

offline

Boolean variable indicating if the tracker should be run in offline mode
defaults to False

country_iso_code

3 letter ISO Code of the country where the experiment is being run.
Available countries are listed in global_energy_mix.json

region

Optional Name of the Province/State/City, where the infrastructure is hosted
Currently, supported only for US States
for example - California or New York, from the list

cloud_provider

The cloud provider specified for estimating emissions intensity,
defaults to None. See impact.csv for a list of cloud providers

cloud_region

The region of the cloud data center, defaults to None
See impact.csv for a list of cloud regions.