Skip to content

Commit f39f752

Browse files
fvaleyefvaleye
authored
Merge pull request #3 from fvaleye/feature/improve-carbon-emissions-object
Improve the carbon emissions object.
2 parents 46c3f3e + be9eb1f commit f39f752

20 files changed

+526
-421
lines changed

‎README.md

+49-67
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,16 @@
66

77

88
## 📌 Overview
9-
Tracarbon is a Python library that tracks your device's power consumption and calculates your carbon emissions.
9+
Tracarbon is a Python library that tracks your device's energy consumption and calculates your carbon emissions.
10+
11+
It detects your location and your device automatically before starting to export measurements to an exporter.
12+
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.
1013

1114
## 📦 Where to get it
1215

1316
```sh
1417
# Install Tracarbon
15-
pip install 'tracarbon'
18+
pip install tracarbon
1619
```
1720

1821
```sh
@@ -21,91 +24,70 @@ pip install 'tracarbon[datadog]'
2124
```
2225

2326
### 🔌 Devices: energy consumption
27+
| **Devices** | **Description** |
28+
|-------------|:------------------------------------------------------------------------------:|
29+
| **Mac** | ✅ Global energy consumption of your Mac (must be plugged into a wall adapter). |
30+
| **Linux** | ❌ Not yet implemented. |
31+
| **Windows** | ❌ Not yet implemented. |
2432

25-
| **Device** | **Description** |
26-
|-------------|:-----------------------------------------------:|
27-
| **Mac** | ✅ Battery energy consumption (must be plugged). |
28-
| **Linux** | ❌ Not yet implemented. |
29-
| **Windows** | ❌ Not yet implemented. |
30-
31-
| **Cloud Provider** | **Description** |
32-
|--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------:|
33-
| **AWS** |✅ Estimation based on [cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/cloud-carbon-coefficients/blob/main/data/aws-instances.csv).|
34-
| **GCP** | ❌ Not yet implemented. |
35-
| **Azure** | ❌ Not yet implemented. |
33+
| **Cloud Provider** | **Description** |
34+
|--------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
35+
| **AWS** | ✅ Used the CPU usage with the EC2 instances carbon emissions datasets of [cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/cloud-carbon-coefficients/blob/main/data/aws-instances.csv). |
36+
| **GCP** | ❌ Not yet implemented. |
37+
| **Azure** | ❌ Not yet implemented. |
3638

3739

3840
## 📡 Exporters
39-
40-
| **Exporter** | **Description** |
41-
|--------------|:-----------------------------------------:|
42-
| **Stdout** | Print the metrics in Stdout. |
43-
| **Datadog** | Publish the metrics on Datadog. |
41+
| **Exporter** | **Description** |
42+
|--------------|:----------------------------:|
43+
| **Stdout** | Print the metrics in Stdout. |
44+
| **Datadog** | Send the metrics on Datadog. |
4445

4546
### 🗺️ Locations
47+
| **Location** | **Description** | **Source** |
48+
|--------------|:------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|
49+
| **Europe** | Static file of the European Environment Agency Emission for the co2g/kwh for European countries. | [EEA website](https://www.eea.europa.eu/data-and-maps/daviz/co2-emission-intensity-9#tab-googlechartid_googlechartid_googlechartid_googlechartid_chart_11111) |
50+
| **France** | Get the co2g/kwh in near real-time using the RTE energy consumption. | [RTE API](https://opendata.reseaux-energies.fr) |
51+
| **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) |
4652

47-
48-
| **Location** | **Description** | **Source** |
49-
|-------------------------------|:--------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
50-
| **Europe** | European Environment Agency Emission co2g/kwh for European countries. | [EEA website](https://www.eea.europa.eu/data-and-maps/daviz/co2-emission-intensity-9#tab-googlechartid_googlechartid_googlechartid_googlechartid_chart_11111) |
51-
| **France** | RTE energy consumption API in real-time. | [RTE API](https://opendata.reseaux-energies.fr) |
52-
| **AWS** | AWS Grid emissions factors from cloud-carbon. | [cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/cloud-carbon-coefficients/blob/main/data/grid-emissions-factors-aws.csv) |
53+
### ⚙ Configuration
54+
| **Parameter** | **Description** |
55+
|-----------------------------------|:-------------------------------------------------------------------------------|
56+
| **TRACARBON_API_ACTIVATED** | The activation of the real-time data collection of the carbon emission factor. |
57+
| **TRACARBON_METRIC_PREFIX_NAME** | The prefix to use in all the metrics name. |
58+
| **TRACARBON_INTERVAL_IN_SECONDS** | The interval in seconds to wait between the metrics evaluation. |
59+
| **TRACARBON_LOGURU_LEVEL** | The level to use for displaying the logs. |
5360

5461

5562
## 🔎 Usage
5663

64+
**Command Line**
65+
```sh
66+
tracarbon run Stdout
67+
```
68+
5769
**API**
5870
```python
59-
import asyncio
60-
61-
from tracarbon import CarbonEmission, EnergyConsumption, Country
71+
from tracarbon import CarbonEmission
6272
from tracarbon.exporters import Metric, StdoutExporter
63-
from tracarbon.hardwares import HardwareInfo
64-
65-
exporter = StdoutExporter()
66-
metrics = list()
67-
location = asyncio.run(Country.get_location())
68-
energy_consumption = EnergyConsumption.from_platform()
69-
platform = HardwareInfo.get_platform()
70-
metrics.append(
71-
Metric(
72-
name="energy_consumption",
73-
value=energy_consumption.run,
74-
tags=[f"platform:{platform}", f"location:{location}"]
75-
)
76-
)
77-
metrics.append(
78-
Metric(
79-
name="co2_emission",
80-
value=CarbonEmission(energy_consumption=energy_consumption, location=location).run,
81-
tags=[f"platform:{platform}", f"location:{location}"]
82-
)
83-
)
84-
metrics.append(
85-
Metric(
86-
name="hardware_cpu_usage",
87-
value=HardwareInfo().get_cpu_usage,
88-
tags=[f"platform:{platform}", f"location:{location}"]
89-
)
90-
)
91-
metrics.append(
92-
Metric(
93-
name="hardware_memory_usage",
94-
value=HardwareInfo().get_memory_usage,
95-
tags=[f"platform:{platform}", f"location:{location}"]
96-
)
73+
74+
metric = Metric(
75+
name="co2_emission",
76+
value=CarbonEmission().run,
77+
tags=[],
9778
)
98-
asyncio.run(exporter.launch_all(metrics=metrics))
99-
```
79+
exporter = StdoutExporter(metrics=[metric])
80+
exporter.start()
81+
# Your code
82+
exporter.stop()
10083

101-
**CLI**
102-
```sh
103-
tracarbon run Stdout
84+
with exporter:
85+
# Your code
10486
```
10587

10688
## 💻 Development
10789

108-
**Local**
90+
**Local: using Poetry**
10991
```sh
11092
make setup
11193
make unit-test

‎docs/source/conf.py

+1
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ def get_release_version() -> str:
4747
nitpick_ignore = [
4848
("py:class", "datetime.datetime"),
4949
("py:class", "datadog.threadstats.base.ThreadStats"),
50+
("py:class", "threading.Event"),
5051
]
5152

5253
# Add any paths that contain templates here, relative to this directory.

‎docs/source/usage.rst

+20-2
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ Tracarbon
88
1. Choose :class:`.Exporter`
99
2. Run it!
1010

11-
Scan an external Metadata Source
12-
================================
11+
Run the CLI
12+
===========
1313

1414
Run the tracarbon cli with Stdout exporter:
1515

@@ -19,3 +19,21 @@ Run the tracarbon cli with Datadog exporter:
1919

2020
>>> DATADOG_API_KEY=DATADOG_API_KEY DATADOG_APP_KEY=DATADOG_APP_KEY tracarbon run Datadog
2121

22+
Run the code
23+
============
24+
>>> from tracarbon import CarbonEmission
25+
>>> from tracarbon.exporters import Metric, StdoutExporter
26+
>>>
27+
>>> metric = Metric(
28+
>>> name="co2_emission",
29+
>>> value=CarbonEmission().run,
30+
>>> tags=[],
31+
>>> )
32+
>>> exporter = StdoutExporter(metrics=[metric])
33+
>>> exporter.start()
34+
>>> # Your code
35+
>>> exporter.stop()
36+
>>>
37+
>>> with exporter:
38+
>>> # Your code
39+

0 commit comments

Comments
 (0)