[RELENG-7422] 📝 Add documentation

docs/setup/collected-reported-metrics.md

@@ -31,8 +31,8 @@ Count the number of workflows for each state:
 
 ## Workflow job
 
-Voici les différentes metrics recupérées par le projet GitHub Actions Exporter
-pour les workflows job.
+Here are the different metrics collected by the GitHub Actions
+Exporter project for workflows and jobs.
 
 The duration of a job in seconds: `github_actions_job_duration_seconds`.
 
@@ -72,7 +72,7 @@ of 0.008$/min, that's it. Easy!
 
 When it comes to the cost of self-hosted runners, it's a bit more complicated.
 
-Scality's self-hosted runners include Google Cloud Provider (GCP) and AWS.
+Self-hosted runners include Google Cloud Provider (GCP) and AWS.
 
 The cost can be found based on the machine type in the Management Console
 for AWS (when creating an EC2 instance) and on the

docs/setup/utilizing-grafana.md

@@ -1,2 +1,90 @@
 # Utilizing Grafana
 
+Grafana is a powerful open-source platform that allows users to visualize
+and monitor various metrics and data sources. In this guide, we will
+explore how to effectively use Grafana to monitor and analyze GitHub Actions.
+
+Grafana can be accessed through
+[the following URL](https://mon.scality.net/grafana/d/WidbLgPnk/).
+Once logged in, you will find two distinct boards: "GitHub Actions Costs"
+and "GitHub Actions Monitoring." These boards provide valuable insights
+into cost monitoring and general information about GitHub Actions.
+
+## As a user
+
+When accessing the Grafana URL, users can easily sort and filter the displayed
+data using variables located at the top of the page. This functionality
+allows more precise and targeted information based on specific criteria.
+
+Available Sorting Options:
+
+- `repository`: GitHub repository
+- `workflow_name`: Name of the workflow
+- `repository_visibility`: Public or private
+- `job_name`: Name of the job
+- `runner_type`: GitHub or self-hosted
+- `cloud`: GCloud / AWS or GitHub
+
+Note that additional variables may be added in the future to enhance the
+monitoring capabilities further.
+
+It is possible to test and display specific information easily by
+accessing the ["Explore" tab](https://mon.scality.net/grafana/explore)
+in Grafana. You will need to enter a query there, as explained in
+the "As a developer" section below.
+
+## As a developper
+
+Grafana provides a flexible platform for customization and extensibility.
+Developpers can create their own dashboards, incorporating specific metrics and
+visualizations tailored to their unique requirements.
+
+I will not provide a comprehensive guide on Grafana; instead, I will
+focus on key points to help you get started. I encourage you to refer
+to [Grafana's documentation](https://grafana.com/docs/grafana/latest/dashboards/)
+for more detailed information.
+
+There are various types of graphs available in Grafana, including line charts,
+bar charts, pie charts, and more. I encourage you to explore and experiment
+with different graph types by referring to the documentation, exploring
+existing graphs, or simply trying them out yourself.
+
+### Query
+
+First of all, to create a graph, start by clicking on the "Add panel" button
+at the top of the page. Another option is to duplicate another graph if
+you want to make a similar one.
+
+Let's begin by examining an example query:
+
+```
+topk(5, sum(increase(github_actions_job_cost_count_total{repository=~"$repository", runner_type=~"$runner_type", repository_visibility=~"$repository_visibility", cloud=~"$cloud"}[$__range])) by (repository) > 0)
+```
+
+This query retrieves data related to GitHub Actions job costs and
+provides the top 5 repositories with the highest cumulative cost
+within a specified time range.
+
+1. The query starts with the topk(5, ...) function, which returns the
+top 5 values based on a specified metric or condition.
+2. The sum(increase(...)) part of the query calculates the cumulative
+sum of the specified metric. In our example, it calculates the
+cumulative sum of the github_actions_job_cost_count_total metric,
+representing the total job cost count.
+3. Within the curly braces {}, we apply filters to narrow down the
+data based on specific criteria. The `$variable` refers to the filter
+variables that you can specify at the top of the page.
+4. The `[$__range]` part specifies the time range for the query.
+It uses the `$__range` variable, which represents the selected time
+range in Grafana.
+5. The `by (repository)` clause groups the data by the repository field.
+This enables the query to calculate the cost sum for each repository individually.
+6. The expression `> 0` filters the query results to only include
+repositories with a value greater than zero.
+
+It's also possible to combine different queries in Grafana allowing you
+to make other graphs. For example, one query dividing by another.
+
+Lastly, it is also important to understand `__interval`. `__interval`
+represents the time interval between data points, whereas `__range`
+represents the selected time range for the query.

docs/tags.md

@@ -0,0 +1,30 @@
+# Tags
+
+In addition to Grafana, we also have tags that are set on AWS and GCP to
+visualize data. These tags allow us to navigate their respective consoles
+and filter data using specific tags, providing more accurate figures
+compared to Grafana, which has an approximate margin of error of +/- 5%.
+
+## AWS
+
+For AWS, we have the following tags (specified in the configuration file
+found in the `devinfra` repository):
+
+- Name of the runner
+- `lifecycle_autostop`: `no`
+- `lifecycle_autostart`: `no`
+- `map-migrated`: `mig42992`
+- `owner`: `ci`
+- `tool`: `runner-manager`
+
+## GCloud
+
+For GCP, we have the following tags (retrieve dynamic tags using the
+`gh_actions_exporter` repository via webhooks):
+
+- machine_type
+- image
+- status
+- repository
+- workflow
+- job

mkdocs.yml

@@ -48,9 +48,7 @@ nav:
   - Collected and reported metrics: setup/collected-reported-metrics.md
   - Utilizing Grafana: setup/utilizing-grafana.md
 
-- Tags on runners' VMs:
-  - Google Cloud: tags/google-cloud.md
-  - AWS: tags/aws.md
+- Tags on runners' VMs: tags.md
 
 markdown_extensions:
   - pymdownx.highlight: