Skip to main content

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

Project description

Tracarbon Logo

example workflow pypi doc licence

📌 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 ✅ 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
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.

🔎 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

tracarbon run

API

from tracarbon import TracarbonBuilder, TracarbonConfiguration

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

with tracarbon:
    # Your code

💻 Development

Local: using Poetry

make init
make test-unit

🛡️ Licence

Apache License 2.0

📚 Documentation

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tracarbon-0.6.4.tar.gz (48.0 kB view details)

Uploaded Source

Built Distribution

tracarbon-0.6.4-py3-none-any.whl (54.6 kB view details)

Uploaded Python 3

File details

Details for the file tracarbon-0.6.4.tar.gz.

File metadata

  • Download URL: tracarbon-0.6.4.tar.gz
  • Upload date:
  • Size: 48.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.2 CPython/3.8.16 Linux/5.15.0-1034-azure

File hashes

Hashes for tracarbon-0.6.4.tar.gz
Algorithm Hash digest
SHA256 086048491728088210c5ec01a165574ebc4289df33a11ad32f75d21299764d43
MD5 483920a0531cc16748fd9ae2204e4f85
BLAKE2b-256 57f361b16fc1e39719d49c98cdd18fe48e5db4471f7f944ed6128bcb9235168a

See more details on using hashes here.

Provenance

File details

Details for the file tracarbon-0.6.4-py3-none-any.whl.

File metadata

  • Download URL: tracarbon-0.6.4-py3-none-any.whl
  • Upload date:
  • Size: 54.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.2 CPython/3.8.16 Linux/5.15.0-1034-azure

File hashes

Hashes for tracarbon-0.6.4-py3-none-any.whl
Algorithm Hash digest
SHA256 343546b51191ca871fcbe1791d19a85eecbdc26b9a92bd94e4749350213e0644
MD5 4971552a83c532c9c1a4fc0e152c8424
BLAKE2b-256 a221a6f02a3b976c2e16a002c8003849e02ac671c06d5c244e405788de0a47c1

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page