📌 Overview

Tracarbon is a Python library that tracks your device's energy consumption and calculates your carbon emissions.

It detects your location and your device automatically before starting to export measurements to an exporter. It could be used as a CLI with already defined metrics or programmatically with the API by defining the metrics that you want to have.

Read more in this article.

📦 Where to get it

```sh

Install Tracarbon

pip install tracarbon ```

```sh

Install one or more exporters from the list

pip install 'tracarbon[datadog,prometheus,kubernetes]' ```

🔌 Devices: energy consumption

| Devices | Description | | ----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | Mac | ✅ Global energy consumption of your Mac (must be plugged into a wall adapter). | | Linux | ⚠️ Only with RAPL. See #1. It works with containers on Kubernetes using the Metric API if available. | | Windows | ❌ Not yet implemented. See #184. |

| Cloud Provider | Description | | ------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | AWS | ✅ Use the hardware's usage with the EC2 instances carbon emissions datasets of cloud-carbon-coefficients. | | GCP | ❌ Not yet implemented. | | Azure | ❌ Not yet implemented. |

📡 Exporters

| Exporter | Description | | ------------ | :-------------------------------: | | Stdout | Print the metrics in Stdout. | | JSON | Write the metrics in a JSON file. | | Prometheus | Send the metrics to Prometheus. | | Datadog | Send the metrics to Datadog. |

🗺️ Locations

| Location | Description | Source | | ------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Worldwide | Get the latest co2g/kwh in near real-time using the CO2Signal or ElectricityMaps APIs. See here for the list of available zones. | CO2Signal API or ElectricityMaps | | Europe | Static file created from the European Environment Agency Emission for the co2g/kwh in European countries. | EEA website | | AWS | Static file of the AWS Grid emissions factors. | cloud-carbon-coefficients |

⚙️ Configuration

The environment variables can be set from an environment file .env.

| Parameter | Description | | ----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | TRACARBONCO2SIGNALAPIKEY | The api key received from CO2Signal or ElectricityMaps. | | TRACARBONCO2SIGNALURL | The url of CO2Signal is the default endpoint to retrieve the last known state of the zone, but it could be changed to ElectricityMaps. | | TRACARBONMETRICPREFIXNAME | The prefix to use in all the metrics name. | | TRACARBONINTERVALINSECONDS | The interval in seconds to wait between the metrics evaluation. | | TRACARBONLOG_LEVEL | The level to use for displaying the logs. |

🔎 Usage

Request your API key

• Go to CO2Signal and get your free API key for non-commercial use, or go to ElectricityMaps for commercial use.
• This API is used to retrieve the last known carbon intensity (in gCO2eq/kWh) of electricity consumed in your location.
• Set your API key in the environment variables, in the .env file or directly in the configuration.
• If you would like to start without an API key, it's possible, the carbon intensity will be loaded statistically from a file.
• Launch Tracarbon 🚀

Command Line

sh tracarbon run

API

```python from tracarbon import TracarbonBuilder, TracarbonConfiguration

configuration = TracarbonConfiguration() # Your configuration tracarbon = TracarbonBuilder(configuration=configuration).build() tracarbon.start()

Your code

tracarbon.stop()

with tracarbon: # Your code

report = tracarbon.report() # Get the report ```

💻 Development

Local: using uv

sh make init make test-unit

🛡️ Licence

Apache License 2.0

📚 Documentation

The documentation is hosted here: https://fvaleye.github.io/tracarbon/documentation