From d312a21175d3574bfe88bf98d66e789f8712a036 Mon Sep 17 00:00:00 2001 From: olivier de Meringo Date: Wed, 15 Nov 2023 12:31:59 +0100 Subject: [PATCH] chore(doc): update docs and add link checker --- docs/book.toml | 2 +- docs/src/SUMMARY.md | 7 +++++-- docs/src/explanations/methodology.md | 16 ++++++++++++++++ docs/src/explanations/source-of-data.md | 7 ------- docs/src/reference/limits.md | 2 +- docs/src/reference/source-of-data.md | 5 ----- docs/src/reference/testing.md | 4 ++-- .../src/tutorials/quickstart-dashboard-docker.md | 10 ++++++---- 8 files changed, 31 insertions(+), 22 deletions(-) create mode 100644 docs/src/explanations/methodology.md delete mode 100644 docs/src/explanations/source-of-data.md delete mode 100644 docs/src/reference/source-of-data.md diff --git a/docs/book.toml b/docs/book.toml index af7ee8c1..0e60cfcc 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -7,7 +7,7 @@ title = "Boavizta cloud scanner 📡" # Deactivate link checker by default # cargo install mdbook-linkcheck -# [output.linkcheck] +[output.linkcheck] [output.html] #theme = "my-theme" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index f7466cd8..e476bf32 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -7,6 +7,11 @@ - [Quickstart - using cargo 🦀](tutorials/quickstart-rust-cli.md) - [Quickstart as serverless ⚡](tutorials/quickstart-serverless.md) +# Explanations + +- [Methodology](explanations/methodology.md) +- [How we process workload](explanations/processing-workload.md) + # How-to guides - [Building CLI](how-to/building-cli.md) @@ -16,8 +21,6 @@ - [Setup monitoring dashboard](how-to/set-up-dashboard.md) - [Filtering by tags](how-to/filter-by-tags.md) - [Using a private instance of Boavizta API](how-to/using-private-boaviztapi.md) -- [Source of data](explanations/source-of-data.md) -- [How we process workload](explanations/processing-workload.md) # Reference diff --git a/docs/src/explanations/methodology.md b/docs/src/explanations/methodology.md new file mode 100644 index 00000000..7a6edc69 --- /dev/null +++ b/docs/src/explanations/methodology.md @@ -0,0 +1,16 @@ +# Methodology and source of data + +Cloud scanner uses the Boavizta methodology to estimate the impacts of cloud resources. + +The methodology of Boavizta is described in [Digital & environment : How to evaluate server manufacturing footprint, beyond greenhouse gas emissions? | Boavizta](https://boavizta.org/en/blog/empreinte-de-la-fabrication-d-un-serveur) + +Impact data is retrieved from [BOAVIZTA reference data API](https://github.com/Boavizta/boaviztapi/) v1.0.x. + +The results are similar to what you can visualize in [Datavizta](http://datavizta.boavizta.org/cloudimpact), but with automated inventory. + +⚠ Cloud scanner **underestimate the impacts of the cloud resources**. Because it only considers the _instances_ and _block storage_ a lot of impacts (network, potential redundancy, cloud control plan) are not included in the estimation. + +See also [other limits](../reference/limits.md). + +- https://www.boavizta.org/en +- https://boavizta.org/en/blog/empreinte-de-la-fabrication-d-un-serveur diff --git a/docs/src/explanations/source-of-data.md b/docs/src/explanations/source-of-data.md deleted file mode 100644 index 52d25e0a..00000000 --- a/docs/src/explanations/source-of-data.md +++ /dev/null @@ -1,7 +0,0 @@ -# Source of data - -Impact data is retrieved from [BOAVIZTA reference data API](https://github.com/Boavizta/boaviztapi/). - -This is similar to what you can get from [Datavizta](http://datavizta.boavizta.org/cloudimpact), but with automated inventory. - -- Current version of cloud-scanner uses API v0.2.x diff --git a/docs/src/reference/limits.md b/docs/src/reference/limits.md index f6352fb5..2a92a4f9 100644 --- a/docs/src/reference/limits.md +++ b/docs/src/reference/limits.md @@ -47,7 +47,7 @@ Carbon intensity of electricity is not (yet) real time. It uses and yearly extra ### Allocation of manufacture impacts -Today, cloud scanner returns the manufacture impacts of a resource corresponding to _the entire lifecycle_ of the ressource. The manufacture impacts returned for a VM are the same if you use it one hours or several year. Said differently we do _not_ amortize the manufacturing impacts over the duration of use. +Today, cloud scanner returns the manufacture impacts of a resource corresponding to _the entire lifecycle_ of the ressource. The manufacture impacts returned for a VM are the same if you use it one hours or several year. To say it differently, we do _not_ amortize the manufacturing impacts over the duration of use. ### We do not provide margins of error diff --git a/docs/src/reference/source-of-data.md b/docs/src/reference/source-of-data.md deleted file mode 100644 index 73714d00..00000000 --- a/docs/src/reference/source-of-data.md +++ /dev/null @@ -1,5 +0,0 @@ -# Source of data - -- https://boavizta.github.io/cloud-scanner/ -- https://www.boavizta.org/en -- https://boavizta.org/en/blog/empreinte-de-la-fabrication-d-un-serveur diff --git a/docs/src/reference/testing.md b/docs/src/reference/testing.md index 543aa29f..683069f8 100644 --- a/docs/src/reference/testing.md +++ b/docs/src/reference/testing.md @@ -1,8 +1,8 @@ # Testing -Whne launched with `cargo test -- --include-ignored` some the unit tests require a specific instance to run (when launched ). +When launched with `cargo test -- --include-ignored` some the unit tests require a specific instance to run (when launched ). -> These integration tests requiere specific instance to be up and running to pass. This means they are tied to a specific cloud account. +> These integration tests require specific instances to be up and running to pass. This means they are tied to a specific cloud account. Commands to start or stop instances: diff --git a/docs/src/tutorials/quickstart-dashboard-docker.md b/docs/src/tutorials/quickstart-dashboard-docker.md index 03ac294b..132fa0bf 100644 --- a/docs/src/tutorials/quickstart-dashboard-docker.md +++ b/docs/src/tutorials/quickstart-dashboard-docker.md @@ -1,8 +1,10 @@ # Quick start : display dashboard using docker-compose 🐳 -No installation needed, you will run a public docker image of cloud-scanner CLI and Boavizta API. +Visualize the live impacts of you account in a dashboard. -All data remain local (this docker-compose stack uses a _private instance_ of Boavizta API). +No installation needed, you will run a public docker image of cloud-scanner CLI, Boavizta API, Prometheus and Grafana to get access to a demo dashboard.. + +All data remain will local to your environment (this docker-compose stack uses a _private instance_ of Boavizta API). ## Pre-requisites @@ -31,6 +33,6 @@ docker-compose up - ⚠ This docker-compose example is **not** intended for production deployment, but rather for quick testing. - ports of all services are exposed. - Grafana is served on http with default login. -- You may have to update the line mapping your AWS profile (Replace `AWS_PROFILE=${AWS_PROFILE}` by `AWS_PROFILE=the-real-name-of-your-profile`). +- You may have to update the line mapping your AWS profile (Replace `AWS_PROFILE=${AWS_PROFILE}` by `AWS_PROFILE=the-real-name-of-your-profile`) when using Podman. It seems that Podman compose does not map the variables of the environment to the containers. - In corporate environments, you may need to provide your certificates authorities certificates (`ca-certificates`) to the cloud-scanner container (uncomment the mapping line in the docker-compose file). -- For the demo, we deliberately set a short metrics scrapping interval (30 seconds in this demo). In production deloymnent, you may want to increase this metric scraping interval in the prometheus configuration file. +- For the demo, we deliberately set a short metrics scrapping interval (30 seconds). In a production environment, you may want to increase this metric scraping interval to reduce the API calls and volume of data. This scrapping period is set in the Prometheus configuration file.