Output

CSV

The package has an in-built logger that logs data into a CSV file named emissions.csv in the output_dir, provided as an input parameter (defaults to the current directory), for each experiment tracked across projects.

Data Fields Logged for Each Experiment

Field

Description

timestamp

Time of the experiment in %Y-%m-%dT%H:%M:%S format

project_name

Name of the project, defaults to codecarbon

run-id

id of the run

duration

Duration of the compute, in seconds

emissions

Emissions as CO₂-equivalents [CO₂eq], in kg

emissions_rate

emissions divided per duration, in Kg/s

cpu_power

CPU power (W)

gpu_power

GPU power (W)

ram_power

RAM power (W)

cpu_energy

Energy used per CPU (kWh)

gpu_energy

Energy used per GPU (kWh)

ram_energy

Energy used per RAM (kWh)

energy_consumed

sum of cpu_energy, gpu_energy and ram_energy (kWh)

country_name

Name of the country where the infrastructure is hosted

country_iso_code

3-letter alphabet ISO Code of the respective country

region

Province/State/City where the compute infrastructure is hosted

on_cloud

Y if the infrastructure is on cloud, N in case of private infrastructure

cloud_provider

One of the 3 major cloud providers, aws/azure/gcp

cloud_region

Geographical Region for respective cloud provider,
examples us-east-2 for aws, brazilsouth for azure, asia-east1 for gcp

os

os on the device
example Windows-10-10.0.19044-SP0

python_version

example 3.8.10

cpu_count:

number of CPU

cpu_model

example Intel(R) Core(TM) i7-1065G7 CPU @ 1.30GHz

gpu_count

number of GPU

gpu_model

example 1 x NVIDIA GeForce GTX 1080 Ti

longitude

Longitude, with reduced precision to a range of 11.1 km / 123 km².
This is done for privacy protection.

latitude

Latitude, with reduced precision to a range of 11.1 km / 123 km².
This is done for privacy protection.

ram_total_size

total RAM available (Go)

Tracking_mode:

machine or process``(default to ``machine)

Note

Developers can enhance the Output interface, based on requirements. For example, to log into a database, by implementing a custom Class that is a derived implementation of base class BaseOutput at codecarbon/output.py

Prometheus

Using CodeCarbon with prometheus

Prometheus is a systems and service monitoring system. It collects metrics from configured targets at given intervals, evaluates rule expressions, displays the results, and can trigger alerts when specified conditions are observed.

CodeCarbon exposes all its metrics with the suffix codecarbon_.

Current version uses pushgateway mode. If your pushgateway server needs auth, set your environment values PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD so codecarbon is able to push the metrics.

How to test in local

Deploy a local version of Prometheus + Prometheus Pushgateway

docker-compose up

Run your EmissionTracker as usual, but with the parameter save_to_prometheus as True. e.g.

...
tracker = OfflineEmissionsTracker(
            project_name=self.project_name,
            country_iso_code="USA",
            save_to_prometheus=True,
        )
tracker.start()
...

Go to localhost:9090. Search for codecarbon_. You will see all the metrics there.

Logfire

Using CodeCarbon with logfire

Logfire is an observability platform.

CodeCarbon exposes all its metrics with the suffix codecarbon_.

How to use it

Run your EmissionTracker as usual, but with the parameter save_to_logfire as True. e.g.

...
tracker = OfflineEmissionsTracker(
            project_name=self.project_name,
            country_iso_code="USA",
            save_to_logfire=True,
        )
tracker.start()
...

The first time it will ask to log in into Logfire. Once you log in and set the default logfire project, you are good to go, the metrics will appear following the format codecarbon_*.

HTTP Output

The HTTP Output allow the call of a webhook with emission data when the tracker is stopped.

CodeCarbon API

You can send all the data to the CodeCarbon API. So you have all your historical data in one place. By default, nothing is sent to the API.

Logger Output

See Collecting emissions to a logger.