📌 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
# Install Tracarbon
pip install tracarbon
# Install one or more exporters from the list
pip install 'tracarbon[datadog,prometheus,kubernetes]'
🔌 Devices: energy consumption
| Devices | Description |
|---|---|
| Mac | ✅ Apple Silicon CPU, GPU, memory and Neural Engine energy via IOReport (no sudo). Excludes display and peripherals. Fallbacks: powermetrics (sudo), then ioreg. |
| Linux | ✅ Supports Intel and AMD processors via RAPL. Intel uses the powercap interface. AMD is supported on kernel 5.8+ (powercap) or via the amd_energy driver (HWMON). 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 | ✅ Use the hardware's usage with the GCP instances carbon emissions datasets of cloud-carbon-coefficients. |
| Azure | ✅ Use the hardware's usage with the Azure instances carbon emissions datasets of cloud-carbon-coefficients. |
🎮 GPU: power tracking
| GPU | Description |
|---|---|
| NVIDIA | ✅ Supported via nvidia-smi. Works on Linux, Windows, and Intel Macs. Supports multiple GPUs. |
| AMD | ✅ Supported via rocm-smi or amd-smi on Linux. Supports multiple GPUs. |
| Apple Silicon | ✅ Integrated GPU power via IOReport, without sudo. Falls back to powermetrics (requires sudo). |
| Intel | ❌ 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 available Electricity Maps query modes. | 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 |
| GCP | Static file of the GCP Grid emissions factors (2024 yearly data). | GoogleCloudPlatform/region-carbon-info |
| Azure | Static file of the Azure Grid emissions factors. | cloud-carbon-coefficients |
⚙️ Configuration
The environment variables can be set from an environment file .env.
| Parameter | Description |
|---|---|
| TRACARBON_CO2SIGNAL_API_KEY | The api key received from CO2Signal or ElectricityMaps. |
| TRACARBON_CO2SIGNAL_URL | The url of CO2Signal is the default endpoint to retrieve the last known state of the zone, but it could be changed to ElectricityMaps. |
| TRACARBON_METRIC_PREFIX_NAME | The prefix to use in all the metrics name. |
| TRACARBON_INTERVAL_IN_SECONDS | The interval in seconds to wait between the metrics evaluation. |
| TRACARBON_LOG_LEVEL | The level to use for displaying the logs. |
| TRACARBON_IPINFO_TOKEN | An optional ipinfo.io API token used for country detection from the IP address, lifting the anonymous rate limit. |
| TRACARBON_KUBERNETES_NODE_NAME | The Kubernetes node name used to scope container metrics to the node being measured. Falls back to NODE_NAME when unset. |
🔎 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
.envfile 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
tracarbon run
Prometheus with Kubernetes containers
tracarbon run --exporter-name Prometheus --containers
With the default metric prefix, container metrics are exposed with these Prometheus names:
| Metric | Labels |
|---|---|
| tracarbon_energy_consumption_kubernetes_total | pod_name, pod_namespace, container_name, platform, containers, location, units |
| tracarbon_energy_consumption_kubernetes_cpu | pod_name, pod_namespace, container_name, platform, containers, location, units |
| tracarbon_energy_consumption_kubernetes_memory | pod_name, pod_namespace, container_name, platform, containers, location, units |
| tracarbon_carbon_emission_kubernetes_total | pod_name, pod_namespace, container_name, platform, containers, location, source, units |
| tracarbon_carbon_emission_kubernetes_cpu | pod_name, pod_namespace, container_name, platform, containers, location, source, units |
| tracarbon_carbon_emission_kubernetes_memory | pod_name, pod_namespace, container_name, platform, containers, location, source, units |
Zero values are exported. If Kubernetes returns no pod metrics, the CLI logs No Kubernetes container metrics were collected. Host metrics are still exported.
When running in Kubernetes, deploy Tracarbon per node and set NODE_NAME from spec.nodeName with the Downward API so container metrics are scoped to the measured node.
API
from tracarbon import TracarbonBuilder, TracarbonConfiguration
configuration = TracarbonConfiguration() # Your configuration
tracarbon = TracarbonBuilder(configuration=configuration).build()
tracarbon.start()
# Your code
total_co2g = tracarbon.stop() # The CO2 grams emitted while it was running
with tracarbon:
# Your code
report = tracarbon.report # Get the report
print(report.total_co2g)
total_co2g is None when no host carbon emission metric was collected. The total reflects collected samples.
💻 Development
Local: using uv
make init
make test-unit
🛡️ Licence
📚 Documentation
The documentation is hosted here: https://fvaleye.github.io/tracarbon/documentation
1 maintainer
Metadata
1 maintainer
Release files for tracarbon 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tracarbon-0.11.0.tar.gz | 77.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tracarbon-0.11.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 161.1 kB
Release files / tracarbon-0.11.0.tar.gz
| Download URL | tracarbon-0.11.0.tar.gz |
|---|---|
| Size | 77.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
205932a784c9008d18acbfdd18ece6b9ac74e34dc0f4a842033ea241e90c070f
|
|
BLAKE2b-256 checksum How to use checksums |
8c7c29fd38fdf0d4273ec84f9f53c7aee418b51280b16016ad9e9d4fd4814048
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / tracarbon-0.11.0-py3-none-any.whl
| Download URL | tracarbon-0.11.0-py3-none-any.whl |
|---|---|
| Size | 83.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b4348c57f5dbc757032f105bbc0d923c03dae4030736d6fd1e10131a3e5da1f9
|
|
BLAKE2b-256 checksum How to use checksums |
8a6b834c34b4704356bfa32288d112d147eb99400e09c4f452e5fd49eb5c3eed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
