[](https://pypi.org/project/tracarbon/)
[](https://fvaleye.github.io/tracarbon)
[](https://github.com/fvaleye/tracarbon/blob/main/LICENSE.txt)
## 📌 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](https://medium.com/@florian.valeye/tracarbon-track-your-devices-carbon-footprint-fb051fcc9009).
## 📦 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](https://web.eece.maine.edu/~vweaver/projects/rapl/). See [#1](https://github.com/fvaleye/tracarbon/issues/1). It works with containers on [Kubernetes](https://kubernetes.io/) using the [Metric API](https://kubernetes.io/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/#metrics-api) if available. |
| Windows | ❌ Not yet implemented. See [#184](https://github.com/hubblo-org/scaphandre/pull/184). |
| **Cloud Provider** | **Description** |
|--------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| AWS | ✅ Use the hardware's usage with the EC2 instances carbon emissions datasets of [cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/ccf-coefficients/blob/main/data/aws-instances.csv). |
| 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](http://api.electricitymap.org/v3/zones) for the list of available zones. | [CO2Signal API](https://www.co2signal.com) or [ElectricityMaps](https://static.electricitymaps.com/api/docs/index.html) |
| Europe | Static file created from the European Environment Agency Emission for the co2g/kwh in European countries. | [EEA website](https://www.eea.europa.eu/data-and-maps/daviz/co2-emission-intensity-9#tab-googlechartid_googlechartid_googlechartid_googlechartid_chart_11111) |
| AWS | Static file of the AWS Grid emissions factors. | [cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/cloud-carbon-coefficients/blob/main/data/grid-emissions-factors-aws.csv) |
### ⚙️ Configuration
The environment variables can be set from an environment file `.env`.
| **Parameter** | **Description** |
|-------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| TRACARBON_CO2SIGNAL_API_KEY | The api key received from [CO2Signal](https://www.co2signal.com) or [ElectricityMaps](https://static.electricitymaps.com/api/docs/index.html). |
| TRACARBON_CO2SIGNAL_URL | The url of [CO2Signal](https://docs.co2signal.com/#get-latest-by-country-code) is the default endpoint to retrieve the last known state of the zone, but it could be changed to [ElectricityMaps](https://static.electricitymaps.com/api/docs/index.html#live-carbon-intensity). |
| 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](https://www.co2signal.com/) and get your free API key for non-commercial use, or go to [ElectricityMaps](https://static.electricitymaps.com/api/docs/index.html) 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 Poetry**
```sh
make init
make test-unit
```
## 🛡️ Licence
[Apache License 2.0](https://raw.githubusercontent.com/fvaleye/tracarbon/main/LICENSE.txt)
## 📚 Documentation
The documentation is hosted here: https://fvaleye.github.io/tracarbon/documentation
Raw data
{
"_id": null,
"home_page": null,
"name": "tracarbon",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "energy, sustainability, energy-consumption, electricity-consumption, energy-efficiency, carbon-footprint, carbon-emissions",
"author": "Florian Valeye",
"author_email": "fvaleye@github.com",
"download_url": "https://files.pythonhosted.org/packages/59/e0/9a03669dfca7251c3b7f233ab80a46edd544941de3a09a27547d1334ba3b/tracarbon-0.7.3.tar.gz",
"platform": null,
"description": "![Tracarbon Logo](https://raw.githubusercontent.com/fvaleye/tracarbon/main/logo.png \"Tracarbon logo\")\n\n\n[](https://pypi.org/project/tracarbon/)\n[](https://fvaleye.github.io/tracarbon)\n[](https://github.com/fvaleye/tracarbon/blob/main/LICENSE.txt)\n\n\n## \ud83d\udccc Overview\nTracarbon is a Python library that tracks your device's energy consumption and calculates your carbon emissions.\n\nIt detects your location and your device automatically before starting to export measurements to an exporter.\nIt could be used as a CLI with already defined metrics or programmatically with the API by defining the metrics that you want to have.\n\nRead more in this [article](https://medium.com/@florian.valeye/tracarbon-track-your-devices-carbon-footprint-fb051fcc9009).\n\n## \ud83d\udce6 Where to get it\n\n```sh\n# Install Tracarbon\npip install tracarbon\n```\n\n```sh\n# Install one or more exporters from the list\npip install 'tracarbon[datadog,prometheus,kubernetes]'\n```\n\n### \ud83d\udd0c Devices: energy consumption\n| **Devices** | **Description** |\n|-------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|\n| Mac | \u2705 Global energy consumption of your Mac (must be plugged into a wall adapter). |\n| Linux | \u26a0\ufe0f Only with [RAPL](https://web.eece.maine.edu/~vweaver/projects/rapl/). See [#1](https://github.com/fvaleye/tracarbon/issues/1). It works with containers on [Kubernetes](https://kubernetes.io/) using the [Metric API](https://kubernetes.io/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/#metrics-api) if available. |\n| Windows | \u274c Not yet implemented. See [#184](https://github.com/hubblo-org/scaphandre/pull/184). |\n\n| **Cloud Provider** | **Description** |\n|--------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|\n| AWS | \u2705 Use the hardware's usage with the EC2 instances carbon emissions datasets of [cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/ccf-coefficients/blob/main/data/aws-instances.csv). |\n| GCP | \u274c Not yet implemented. |\n| Azure | \u274c Not yet implemented. |\n\n## \ud83d\udce1 Exporters\n| **Exporter** | **Description** |\n|--------------|:---------------------------------:|\n| Stdout | Print the metrics in Stdout. |\n| JSON | Write the metrics in a JSON file. |\n| Prometheus | Send the metrics to Prometheus. |\n| Datadog | Send the metrics to Datadog. |\n\n### \ud83d\uddfa\ufe0f Locations\n| **Location** | **Description** | **Source** |\n|--------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Worldwide | Get the latest co2g/kwh in near real-time using the CO2Signal or ElectricityMaps APIs. See [here](http://api.electricitymap.org/v3/zones) for the list of available zones. | [CO2Signal API](https://www.co2signal.com) or [ElectricityMaps](https://static.electricitymaps.com/api/docs/index.html) |\n| Europe | Static file created from the European Environment Agency Emission for the co2g/kwh in European countries. | [EEA website](https://www.eea.europa.eu/data-and-maps/daviz/co2-emission-intensity-9#tab-googlechartid_googlechartid_googlechartid_googlechartid_chart_11111) |\n| AWS | Static file of the AWS Grid emissions factors. | [cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/cloud-carbon-coefficients/blob/main/data/grid-emissions-factors-aws.csv) |\n\n### \u2699\ufe0f Configuration\nThe environment variables can be set from an environment file `.env`.\n\n| **Parameter** | **Description** |\n|-------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| TRACARBON_CO2SIGNAL_API_KEY | The api key received from [CO2Signal](https://www.co2signal.com) or [ElectricityMaps](https://static.electricitymaps.com/api/docs/index.html). |\n| TRACARBON_CO2SIGNAL_URL | The url of [CO2Signal](https://docs.co2signal.com/#get-latest-by-country-code) is the default endpoint to retrieve the last known state of the zone, but it could be changed to [ElectricityMaps](https://static.electricitymaps.com/api/docs/index.html#live-carbon-intensity). |\n| TRACARBON_METRIC_PREFIX_NAME | The prefix to use in all the metrics name. |\n| TRACARBON_INTERVAL_IN_SECONDS | The interval in seconds to wait between the metrics evaluation. |\n| TRACARBON_LOG_LEVEL | The level to use for displaying the logs. |\n\n## \ud83d\udd0e Usage\n\n**Request your API key**\n- Go to [CO2Signal](https://www.co2signal.com/) and get your free API key for non-commercial use, or go to [ElectricityMaps](https://static.electricitymaps.com/api/docs/index.html) for commercial use.\n- This API is used to retrieve the last known carbon intensity (in gCO2eq/kWh) of electricity consumed in your location.\n- Set your API key in the environment variables, in the `.env` file or directly in the configuration.\n- If you would like to start without an API key, it's possible, the carbon intensity will be loaded statistically from a file.\n- Launch Tracarbon \ud83d\ude80\n\n**Command Line**\n```sh\ntracarbon run\n```\n\n**API**\n```python\nfrom tracarbon import TracarbonBuilder, TracarbonConfiguration\n\nconfiguration = TracarbonConfiguration() # Your configuration\ntracarbon = TracarbonBuilder(configuration=configuration).build()\ntracarbon.start()\n# Your code\ntracarbon.stop()\n\nwith tracarbon:\n # Your code\n\nreport = tracarbon.report() # Get the report\n```\n\n## \ud83d\udcbb Development\n\n**Local: using Poetry**\n```sh\nmake init\nmake test-unit\n```\n\n## \ud83d\udee1\ufe0f Licence\n[Apache License 2.0](https://raw.githubusercontent.com/fvaleye/tracarbon/main/LICENSE.txt)\n\n## \ud83d\udcda Documentation\nThe documentation is hosted here: https://fvaleye.github.io/tracarbon/documentation\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Tracarbon is a Python library that tracks your device's energy consumption and calculates your carbon emissions.",
"version": "0.7.3",
"project_urls": null,
"split_keywords": [
"energy",
" sustainability",
" energy-consumption",
" electricity-consumption",
" energy-efficiency",
" carbon-footprint",
" carbon-emissions"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bbf311f8778642999e67741070d59dcf15eb0a2111c713170a776380514738db",
"md5": "2a9ffea3a4daa53ee71e9e88ed1688a4",
"sha256": "92a5f8cc85ffc98dafc731d53cb90088513e3175aecebbc8f30a46ea9c55672b"
},
"downloads": -1,
"filename": "tracarbon-0.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a9ffea3a4daa53ee71e9e88ed1688a4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 55401,
"upload_time": "2024-11-13T11:04:05",
"upload_time_iso_8601": "2024-11-13T11:04:05.748578Z",
"url": "https://files.pythonhosted.org/packages/bb/f3/11f8778642999e67741070d59dcf15eb0a2111c713170a776380514738db/tracarbon-0.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "59e09a03669dfca7251c3b7f233ab80a46edd544941de3a09a27547d1334ba3b",
"md5": "bb6976d8308319916b081a28cc7b97e7",
"sha256": "8dcfbe94049fa0c4f16052ef72ef20c5165a307eda54c7fc65965045d50a9a7a"
},
"downloads": -1,
"filename": "tracarbon-0.7.3.tar.gz",
"has_sig": false,
"md5_digest": "bb6976d8308319916b081a28cc7b97e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 48877,
"upload_time": "2024-11-13T11:04:07",
"upload_time_iso_8601": "2024-11-13T11:04:07.416319Z",
"url": "https://files.pythonhosted.org/packages/59/e0/9a03669dfca7251c3b7f233ab80a46edd544941de3a09a27547d1334ba3b/tracarbon-0.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 11:04:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "tracarbon"
}
JSON