improve documentation on CO2

Signed-off-by: Scott Trent <[email protected]>
sustainable-computing-io · Sep 12, 2024 · b5504b6 · b5504b6
1 parent 9a93a06
commit b5504b6
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 18 deletions.
diff --git a/README.md b/README.md
@@ -10,22 +10,11 @@ SusQL is an operator that can be deployed in a Kubernetes/OpenShift cluster. You
 
 ## Carbon Dioxide Emission Calculation
 
-There are two currently CO2 emission calculation methods available, and an additional method is under development.
-- The default CO2 emission calculation method is called "static", and simply uses a grams of CO2 per Joule 
-of electricity consumed coefficient to calculate grams of CO2 emitted. This value is user tunable by
-modifying the `CARBON-INTENSITY` ConfigMap value.  The default value is based on
-[US EPA](https://www.epa.gov/energy/greenhouse-gases-equivalencies-calculator-calculations-and-references)
-data.
-- The "simpledynamic" method periodically queries the carbon intensity value for a user specified location to provide a more accurate estimation of CO2 emission.
-The ConfigMap user configurable items are:
-  - `CARBON-METHOD` - The "simpledynamic" method is enabled when set to `simpledynamic`.
-  - `CARBON-INTENSITY` - This value is set automatically. User specified values will be overwritten.
-  - `CARBON-INTENSITY-URL` - Specifies a web API that returns carbon intensity. The default value works as of the date of this writing.
-  - `CARBON-LOCATION` - The location identifiers are defined by the API provider, but can be selected by he user.
-  - `CARBON-QUERY-RATE` - Interval in seconds at which the carbon intensity is queried. The data available from the source is updated less than hourly, so an interval of greater than 3600 seconds is recommended.
-  - `CARBON-QUERY-FILTER` - When the return value is embedded in a JSON object, this specification enables the extraction of the data. The default value matches the default provider.
-  - `CARBON-QUERY-CONV-2J` - If the carbon data provider does not provide data in the standard "grams of CO2 per Joule" then this factor can be specified to normalize the units displayed. The default value ensures that the default provider data is in the correct unit.
-- The third method "sdk" is still under development, and will offer an integration with the Green Software Foundation's [Carbon Aware SDK](https://github.com/Green-Software-Foundation/carbon-aware-sdk).
+By default SusQL calculates carbon dioxide emission in grams of CO2 using a carbon intensity value from 
+[US EPA](https://www.epa.gov/energy/greenhouse-gases-equivalencies-calculator-calculations-and-references).
+
+Detailed information on configuration of CO2 emission calculation in SusQL is available in the SusQL carbon
+calculation [documentation](doc/carbon.md).
 
 ### Prerequisites
 

diff --git a/doc/carbon.md b/doc/carbon.md
@@ -0,0 +1,44 @@
+# Carbon Dioxide Emission Estimation
+
+There are two currently CO2 emission calculation methods available, and an additional method is under development.
+
+"Out-of-the-box" SusQL reports an estimated CO2 emission value for all measured workloads using the `static` method described below.
+
+### `static` Method
+- The default CO2 emission calculation method is used when the `CARBON-METHOD` ConfigMap value is set to `static`
+which simply uses a grams of CO2 per Joule 
+of electricity consumed coefficient to calculate grams of CO2 emitted. This value is user tunable by
+modifying the `CARBON-INTENSITY` ConfigMap value.  The default value is based on
+[US EPA](https://www.epa.gov/energy/greenhouse-gases-equivalencies-calculator-calculations-and-references)
+data.
+
+### `simpledynamic` Method
+- The `simpledynamic` method periodically queries the carbon intensity value for a user specified location to provide a more accurate estimation of CO2 emission.
+The ConfigMap user configurable items are:
+  - `CARBON-METHOD` - The `simpledynamic` method is enabled when this set to `simpledynamic`.
+  - `CARBON-INTENSITY` - This value is set automatically with `simpledynamic`. User specified values will be overwritten.
+  - `CARBON-INTENSITY-URL` - Specifies a web API that returns carbon intensity. The default value works as of the date of this writing.
+  - `CARBON-LOCATION` - The location identifiers are defined by the API provider, but can be selected by he user.
+  - `CARBON-QUERY-RATE` - Interval in seconds at which the carbon intensity is queried. The data available from the source is updated less than hourly, so an interval of greater than 3600 seconds is recommended.
+  - `CARBON-QUERY-FILTER` - When the return value is embedded in a JSON object, this specification enables the extraction of the data. The default value matches the default provider.
+  - `CARBON-QUERY-CONV-2J` - If the carbon data provider does not provide data in the standard "grams of CO2 per Joule" then this factor can be specified to normalize the units displayed. The default value ensures that the default provider data is in the correct unit.
+
+### `sdk` Method
+- The third method `sdk` is still under development, and will offer an integration with the Green Software Foundation's [Carbon Aware SDK](https://github.com/Green-Software-Foundation/carbon-aware-sdk).
+
+## License
+
+Copyright 2024.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
diff --git a/doc/susql-config.yaml b/doc/susql-config.yaml
@@ -8,7 +8,7 @@ data:
   SUSQL-PROMETHEUS-DATABASE-URL: "https://thanos-querier.openshift-monitoring.svc.cluster.local:9091"
   SUSQL-PROMETHEUS-METRICS-URL: "http://0.0.0.0:8082"
   SAMPLING-RATE: "2"
-  LEADER-ELECT: "true"
+  LEADER-ELECT: "false"
   HEALTH-PROBE-BIND-ADDRESS: ":8081"
   SUSQL-LOG-LEVEL: "-5"
   CARBON-METHOD: "static"
@@ -17,4 +17,4 @@ data:
   CARBON-LOCATION: "JP-TK"
   CARBON-QUERY-RATE: "7200"
   CARBON-QUERY-FILTER: "carbonIntensity"
-  CARBON-QUERY-CONV-2J: "0.0000002777777778"
+  CARBON-QUERY-CONV-2J: "0.0000002777777778"