Document carbon accounting approaches (#106)

davidkopp · web-flow · commit 1dd801c1c534 · 2025-07-23T08:27:20.000+02:00
* Create carbon folder
* Add grid carbon intensity and embodied carbon
* Add network carbon intensity
diff --git a/README.md b/README.md
@@ -13,7 +13,6 @@ The main theme is referenced as node_module and thus updating is handled via npm
 Following files have been overloaded and should be checked if they are changed on an update:
 
 - `assets/js/flexsearch.js` (commented out one line due to an Firefox-related issue)
-- `/layouts/_default/single.html` (enable display of the `lead` attribute)
 - `/layouts/partials/*` (Removed integrity protection to run on Cloudflare CDN)
 - `/layouts/index.headers` (Removed CSP netlify)
 
diff --git a/content/en/docs/measuring/carbon/_index.md b/content/en/docs/measuring/carbon/_index.md
@@ -0,0 +1,8 @@
+---
+title: "Carbon Accounting"
+description: "How to account the carbon emissions by IT workloads"
+date: 2025-07-18T08:49:15+00:00
+weight: 2
+sidebar:
+  collapsed: true
+---
diff --git a/content/en/docs/measuring/carbon/embodied-carbon.md b/content/en/docs/measuring/carbon/embodied-carbon.md
@@ -0,0 +1,59 @@
+---
+title: "Embodied Carbon"
+description: "How to account for carbon emissions caused by the manufacturing of IT devices"
+date: 2025-07-18T08:49:15+00:00
+weight: 540
+toc: true
+---
+
+Embodied carbon refers to the greenhouse gas emissions generated throughout the entire lifecycle of IT hardware — from raw material extraction and manufacturing through transportation and disposal — as opposed to operational carbon from running the device. For many IT devices like smartphones, laptops, etc., embodied carbon represents 50-80% of total lifecycle emissions.
+
+## Data Sources
+
+Embodied carbon data comes from Life Cycle Assessment (LCA) studies that analyze the complete environmental impact of devices from cradle to grave. These studies quantify emissions from:
+
+- Raw material extraction
+- Manufacturing processes
+- Transportation
+- End-of-life disposal
+
+You can get data from available databases or directly from the manufacturer.
+
+Example sources:
+
+- Databases:
+  - [Boavizta Database](https://dataviz.boavizta.org/serversimpact) - Open database for IT emissions
+  - [Resilio Database](https://resilio-solutions.com/en/services/database) - Commercial LCA database
+- Manufacturer Data:
+  - [Microsoft Surface TCO Calculator](https://tco.exploresurface.microsoft.com/sustainability/calculator)
+  - [Dell R740 LCA Report](https://www.delltechnologies.com/asset/en-us/products/servers/technical-support/Full_LCA_Dell_R740.pdf)
+
+See also Green Software Foundation's webpage [Datasets](https://sci-guide.greensoftware.foundation/M/Datasets).
+
+## Relevance for the Green Metrics Tool
+
+Embodied carbon is a key component of the [Software Carbon Intensity (SCI)]({{< relref "sci" >}}) metric. The Green Metrics Tool incorporates embodied carbon to provide a complete picture of software's environmental impact by:
+
+- **Proportional allocation**: Calculating how much embodied carbon should be attributed to each measurement run based on its duration and the device's expected lifetime
+- **Hardware accountability**: Ensuring that the environmental cost of hardware is fairly distributed across all software running on it
+- **Complete carbon accounting**: Adding embodied carbon to operational carbon to reflect the true environmental impact of software execution
+- **Comparative analysis**: Enabling fair comparison between different software implementations by including the full lifecycle impact of the hardware they run on
+
+The tool displays embodied carbon emissions for every measurement run, making it visible how hardware choices affect the overall carbon footprint of software.
+
+### Configuration
+
+You can configure the embodied carbon parameters as part of the [SCI]({{< relref "sci" >}}) configuration in `config.yml`:
+
+```yml
+sci:
+    EL: 4 # Expected device lifetime in years
+    RS: 1 # Resource Share (1 = 100% of machine, 0.5 = 50% virtualized)
+    TE: 181000 # Total Embodied emissions in grams CO2e
+```
+
+GMT calculates the embodied carbon per measurement as:
+
+```plain
+(TE / EL) × (measurement_duration / year_duration) × RS
+```
diff --git a/content/en/docs/measuring/carbon/grid-carbon-intensity.md b/content/en/docs/measuring/carbon/grid-carbon-intensity.md
@@ -0,0 +1,38 @@
+---
+title: "Grid Carbon Intensity"
+description: "How to account for carbon emissions caused by grid-supplied power"
+date: 2025-07-18T08:49:15+00:00
+weight: 520
+toc: true
+---
+
+Grid carbon intensity refers to the amount of carbon dioxide equivalent (CO₂e) emissions produced per kilowatt-hour (kWh) of electricity consumed from the power grid. This metric reflects the mix of energy sources (coal, gas, renewables, nuclear) used to generate electricity in a specific location and time.
+
+We have described the conversion from energy to carbon emissions also on our website: [CO₂ Formulas - From kWh to CO₂e](https://www.green-coding.io/co2-formulas/#from-kwh-to-co2e)
+
+## Data Sources
+
+Grid carbon intensity data is available from government agencies, energy databases, and specialized services that track regional electricity carbon intensities.
+
+Examples of available databases and services can be found on the Green Software Foundation's webpage (Grid Carbon Intensity: https://sci-guide.greensoftware.foundation/I/) and on the Green Software Landscape (https://landscape.bundesverband-green-software.de/?group=measurement&view-mode=grid&category=Databases) by the Bundesverband Green Software.
+
+## Relevance for the Green Metrics Tool
+
+Grid carbon intensity is the **I** parameter in the [Software Carbon Intensity (SCI)]({{< relref "sci" >}}) metric. The Green Metrics Tool uses grid carbon intensity to transform the measured energy consumption into carbon emissions based on local grid characteristics.
+
+### Configuration
+
+You can configure the grid carbon intensity as part of the [SCI]({{< relref "sci" >}}) configuration in `config.yml`:
+
+```yml
+sci:
+    I: 334 # Grid carbon intensity in gCO2e/kWh (example value for Germany 2024)
+```
+
+GMT calculates the operational carbon emissions by multiplying measured energy consumption by the grid carbon intensity value.
+
+### Static vs Dynamic Values
+
+The Green Metrics Tool uses **static** grid carbon intensity values rather than dynamic real-time data. This design choice ensures **reproducible measurements** (results remain consistent across different measurement times) and **fair comparisons** (measurements on the same machine with the same configuration use the same baseline for carbon intensity).
+
+You should set the grid carbon intensity to represent the typical or average value for your location.
diff --git a/content/en/docs/measuring/carbon/network-carbon-intensity.md b/content/en/docs/measuring/carbon/network-carbon-intensity.md
@@ -0,0 +1,46 @@
+---
+title: "Network Carbon Intensity"
+description: "How to estimate the carbon emissions of network transfer"
+date: 2025-07-18T08:49:15+00:00
+weight: 530
+toc: true
+---
+
+Network carbon intensity measures the amount of carbon dioxide equivalent (CO₂e) emissions generated per unit of data transferred across network infrastructure.
+Since carbon emissions from network transfers cannot be directly measured, they must be estimated. Network carbon intensity is calculated using two factors:
+
+- Network Energy Intensity (kWh/GB)
+- [Grid Carbon Intensity]({{< relref "grid-carbon-intensity" >}}) (g CO₂e/kWh).
+
+## Methodology
+
+The network carbon intensity methodology and data sources used by the Green Metrics Tool are documented in detail on our [CO₂ Formulas page](https://www.green-coding.io/CO2-formulas/#gigabytes-to-kwh).
+
+## Relevance for the Green Metrics Tool
+
+The Green Metrics Tool aims to provide not just the energy consumption of the device, but also an estimated value for the carbon emissions resulting from network data transfer. To achieve this, it uses the network carbon intensity approach.
+
+Although network emissions are not officially part of the [Software Carbon Intensity (SCI)]({{< relref "sci" >}}) specification, the Green Metrics Tool includes them to offer a more complete view of your software’s carbon footprint.
+
+### Measurement Approach
+
+The Green Metrics Tool aggregates all network traffic from all containers and estimate CO₂ emissions using the [CO₂-Formula](https://www.green-coding.io/CO2-formulas). This approach assumes that all traffic is with external services. However, if your containers only communicate with each other and run on a single machine in production, the calculated emissions will significantly overstate the actual CO₂ impact.
+
+We made this design choice because, during benchmarking, we can't predict how your containers will be orchestrated in production. They might all run on one machine (resulting in zero network emissions), be distributed within a data center (with minimal emissions), or be spread globally (incurring the highest emissions). Since the Green Metrics Tool is meant to provide a baseline for optimization, we chose to report based on the worst-case scenario.
+
+### Configuration
+
+You can configure the network energy intensity as part of the [SCI]({{< relref "sci" >}}) configuration in `config.yml`:
+
+```yml
+sci:
+    N: 0.001875 # unit: kWh/GB
+```
+
+GMT calculates the network carbon intensity as:
+
+```plain
+network_data_transfer × N × I
+```
+
+The factor *I* is described in [Grid Carbon Intensity]({{< relref "grid-carbon-intensity" >}}).
diff --git a/content/en/docs/measuring/carbon/sci.md b/content/en/docs/measuring/carbon/sci.md
@@ -1,8 +1,8 @@
 ---
-title: "SCI (Green Software Foundation)"
+title: "Software Carbon Intensity (SCI)"
 description: "How to measure the Green Software Foundation's SCI metric with the Green Metrics Tool"
 date: 2023-08-04T08:49:15+00:00
-weight: 442
+weight: 550
 toc: true
 ---
 
@@ -53,18 +53,15 @@ If you have an API or similar the output might not happen on the CLI directly, b
 
 An [example configuration](https://github.com/green-coding-solutions/green-metrics-tool/blob/main/config.yml.example) for the `config.yml` is provided when the Green Metrics Tool is installed.
 The values for the respective variables have to be either defined to best knowledge (like lifetime for instance) and / or
-from official databases like:
-- [https://dataviz.boavizta.org/manufacturerdata](https://dataviz.boavizta.org/manufacturerdata)
-- [https://tco.exploresurface.com/sustainability/calculator](https://tco.exploresurface.com/sustainability/calculator)
-- [https://www.delltechnologies.com/asset/en-us/products/servers/technical-support/Full_LCA_Dell_R740.pdf](https://www.delltechnologies.com/asset/en-us/products/servers/technical-support/Full_LCA_Dell_R740.pdf)
+from official databases (like [Embodied Carbon →]({{< relref "embodied-carbon" >}}) and [Grid Carbon Intensity →]({{< relref "grid-carbon-intensity" >}})). See the respective documentation page for possible sources.
 
 Example:
 ```yml
 sci:
     EL: 4 # means 4 years of usage
     RS: 1 # means we use 1/1 = 100% of the machine. Bare metal. No virtualization
     TE: 181000 # Example value for a laptop taken from https://dataviz.boavizta.org/terminalimpact. Value is in g
-    I: 436 # The number 436 that comes as default is for Germany from 2022. Value in gCO2e/kWh
+    I: 334 # The number 334 that comes as default is for Germany from 2024. Value in gCO2e/kWh
 ```
 
 ## Display
@@ -84,7 +81,7 @@ The [SCI formula](https://sci-guide.greensoftware.foundation/) is specified by t
 The components of the SCI are attributed by the GMT as follows:
 
 - *E*: The energy of the total machine + the energy of the network. 
-    - A *PSU Energy* provider must be activated to populate this value with the machine energy like [PSU Energy XGBoost]({{< relref "metric-providers/psu-energy-xgboost-machine" >}}), [PSU Energy MCP]({{< relref "metric-providers/psu-energy-ac-mcp-machine" >}}) etc. 
+    - A *PSU Energy* provider must be activated to populate this value with the machine energy like [PSU Energy XGBoost]({{< relref "../metric-providers/psu-energy-xgboost-machine" >}}), [PSU Energy MCP]({{< relref "../metric-providers/psu-energy-ac-mcp-machine" >}}), etc. 
         - If none is activated machine energy will be excluded from the SCI.
     - A *Network IO* provider must be activated to populate this value with the network energy. 
         - If none is activated network energy will be excluded from the SCI.
diff --git a/content/en/docs/measuring/configuration.md b/content/en/docs/measuring/configuration.md
@@ -168,7 +168,7 @@ optimization:
 
 ## sci
 
-Please see for details: [SCI →]({{< relref "sci" >}}).
+Please see for details: [SCI →]({{< relref "carbon/sci" >}}).
 
 ## electricity_maps_token
 
diff --git a/content/en/docs/measuring/metric-providers/cpu-utilization-cgroup-system-provider.md b/content/en/docs/measuring/metric-providers/cpu-utilization-cgroup-system-provider.md
@@ -1,7 +1,6 @@
 ---
 title: "CPU % - cgroup - sytem"
 description: "Documentation for CpuUtilizationCgroupSystemProvider of the Green Metrics Tool"
-lead: ""
 date: 2025-01-15T08:49:15+00:00
 draft: false
 images: []
diff --git a/content/en/docs/measuring/metric-providers/network-io-cgroup-container.md b/content/en/docs/measuring/metric-providers/network-io-cgroup-container.md
@@ -58,25 +58,12 @@ After having entered the namespace the provider reads from `/proc/net/dev` and:
 - sums up the `r_bytes` and `t_bytes` of all other interfaces
 - does NOT count dropped packets (we assume since most of the traffic is internal, that a dropped received packet shows up in another interface as sent anyway and a dropped sent packet does not attribute much to the energy consumption).
 
-#### Attribution of network traffic
+### Attribution of network traffic
 
 Currently all incoming and outgoing traffic is attributed to every container that sends or receives it.
 
 This may lead to unexpected results when you process the results, but is a design decision.
 
-In our [Green Metrics Dashboard](https://metrics.green-coding.io) we simply accumulate all the network traffic of all containers and then
-apply the [CO2-Formula](https://www.green-coding.io/co2-formulas) on top.
-
-This however assumes that all traffic is with external services. If your containers are however only
-communicating with each other and are in production all on one machine, this number will not
-represent the real CO2 emissions, but is rather greatly overstating them.
-
-This design decision was made cause we cannot know during benchmarking how your containers
-would be orchestrated in production.
-They can very well be all on one machine (which would have zero network emissions), but they also could be distributed in an internal network
-of a datacenter (which would have only marginal network CO2 emissions) or really distributed globally (which would then have the maximum of CO2 emissions).
-
-Since our reporters should give you an optimization baseline we opted for the worst-case scenario to report in our Dashboard.
-
-When processing the metrics you own you may well use a different approach given your knowledge of the network topology.
+In our [Green Metrics Dashboard](https://metrics.green-coding.io) we simply accumulate all the network traffic of all containers and calculate CO2 emissions by applying the [CO2-Formula](https://www.green-coding.io/co2-formulas) on top.
 
+The page [Network Carbon Intensity →]({{< relref "../carbon/network-carbon-intensity" >}}) provides more information and discusses the advantages and disadvantages of this approach.
diff --git a/content/en/docs/measuring/usage-scenario.md b/content/en/docs/measuring/usage-scenario.md
@@ -145,7 +145,7 @@ services:
       + Make sure to also set `log-stdout` to `true`. Format specification is documented below in section [Read-notes-stdout format specification →]({{< relref "#read-notes-stdout-format-specification" >}}).
     - `read-sci-stdout:` **[bool]** *(optional)*
       + Enables the reading of ticks for the unit of work (*R*) required to calculate the SCI metric.
-      + Please see [SCI (Green Software Foundation) →]({{< relref "sci" >}}) for more information.
+      + Please see [Software Carbon Intensity (SCI) →]({{< relref "carbon/sci" >}}) for more information.
     - `docker-run-args:` **[list]** *(optional)*
       + A list of string that should be added to the `docker run` command of that container.
       + The argument needs to be listed in the `user.capabilities` json under `measurement:orchestrators:docker:allow-args`. The string in the `user.capabilities` can be a regex. Opening this up could be a potential security issue!
@@ -221,7 +221,7 @@ flow:
       + Make sure to also set `log-stdout` to `true`. Format specification is documented below in section [Read-notes-stdout format specification →]({{< relref "#read-notes-stdout-format-specification" >}}).
     - `read-sci-stdout:` **[bool]** *(optional)*
       + Enables the reading of ticks for the unit of work (*R*) required to calculate the SCI metric.
-      + Please see [SCI (Green Software Foundation) →]({{< relref "sci" >}}) for more information.
+      + Please see [Software Carbon Intensity (SCI) →]({{< relref "carbon/sci" >}}) for more information.
 
 ### compose-file:
 
