[RELENG-7422] 📝 Add documentation

docs/getting-started/local-setup.md

@@ -0,0 +1,18 @@
+# Local environment
+
+Setting up your local environment
+
+## Install Poetry
+
+The Runner manager uses [Poetry](https://python-poetry.org/), a Python packaging
+and dependency management.
+
+To install and use this project, please make sure you have poetry
+installed. Follow [poetry](https://python-poetry.org/docs/#installation)
+documentation for proper installation instruction.
+
+## Install dependencies
+
+```shell
+$ poetry install
+```

docs/getting-started/run-it-locally.md

@@ -0,0 +1,84 @@
+# Run it locally
+
+Before starting this guide:
+
+* Follow the [local setup](./local-setup.md) documentation.
+
+## Run
+
+Once everything is properly set up, you can launch the project
+with the following command at root level:
+
+```bash
+poetry run start
+```
+
+The application is now launched and running on port 8000 of the machine.
+
+## Webhook setup
+
+### Ngrok setup
+
+As GitHub Actions Exporter depends on webhook coming from github to work properly.
+
+Ngrok can help you setup a public URL to be used with GitHub webhooks.
+
+You can install Ngrok on your Linux machine using the following command:
+```bash
+curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list && sudo apt update && sudo apt install ngrok
+```
+For more information, you can visit the Ngrok [website](https://ngrok.com/download).
+
+Once installed, you can run the following command to listen on port 8000
+of the machine and assign a public URL to it.
+
+```
+ngrok http 8000
+```
+
+### Setting up the webhook
+
+Setup a webhook at the organization level, should be on a link like the following:
+`https://github.com/organizations/<your org>/settings/hooks`
+
+* Click on Add Webhook
+* In payload url, enter your ngrok url, like the following:
+`https://xxxxx.ngrok.io/webhook`
+* Content type: application/json
+* Click on `Let me select individual events.`
+* Select: `Workflow jobs` and `Workflow runs`
+* Save
+
+## Setting up your testing repo
+
+Create a new repository in the organization you have configured the runner manager.
+
+And push a workflow in the repository, here is an example:
+
+```yaml
+# .github/workflows/test-gh-actions-exporter.yaml
+---
+name: test-gh-actions-exporter
+on:
+  push:
+  workflow_dispatch:
+jobs:
+  greet:
+    strategy:
+      matrix:
+        person:
+        - foo
+        - bar
+    runs-on:
+    - ubuntu
+    - focal
+    - large
+    - gcloud
+    steps:
+    - name: sleep
+      run: sleep 120
+    - name: Send greeting
+      run: echo "Hello ${{ matrix.person }}!"
+```
+
+Trigger builds and enjoy :beers:

docs/index.md

@@ -1,22 +1,9 @@
-# GitHub WebHook Exporter
+# GitHub Actions Exporter
 
-The idea of this exporter is to be able to expose this service to listen
-from WebHooks coming from GitHub.
-Then expose those metrics in OpenMetrics format for later usage.
+The GitHub Actions Exporter is a project used to retrieve information
+provided by GitHub, notably through Webhooks, process it, and store it
+via Prometheus. Later on, Grafana is employed to display and visualize
+the data in graphs.
 
-## Install
-
-To install and use this project, please make sure you have [poetry](https://python-poetry.org/) installed.
-
-Then run:
-```shell
-poetry install
-```
-
-## Start
-
-To start the API locally you can use the following command:
-
-```shell
-poetry run start
-```
+The main idea of this exporter is to be able to expose this service to
+listen from WebHooks coming from GitHub.

docs/setup/collected-reported-metrics.md

@@ -0,0 +1,117 @@
+# Collected and reported metrics
+
+The idea behind this repository is to gather as much information as
+possible from the requests sent by GitHub via the Webhook.
+
+In first place, it is important to differentiate the `workflow_run`
+and the `workflow_job` API requests.
+
+The `workflow_run` request is triggered when a workflow run is `requested`,
+`in_progress`, or `completed`.
+
+On the other hand, the `workflow_job` request is triggered when a
+workflow job is `queued`, `in_progress`, or `completed`.
+
+## Workflow run
+
+Here are the different metrics collected by the GitHub Actions Exporter
+project for workflow runs:
+
+The number of workflow rebuilds: `github_actions_workflow_rebuild_count`.
+
+The duration of a workflow in seconds: `github_actions_workflow_duration_seconds`.
+
+Count the number of workflows for each state:
+
+- `github_actions_workflow_failure_count`
+- `github_actions_workflow_success_count`
+- `github_actions_workflow_cancelled_count`
+- `github_actions_workflow_inprogress_count`
+- `github_actions_workflow_total_count`
+
+## Workflow job
+
+Voici les différentes metrics recupérées par le projet GitHub Actions Exporter
+pour les workflows job.
+
+The duration of a job in seconds: `github_actions_job_duration_seconds`.
+
+Time between when a job is requested and started: `github_actions_job_start_duration_seconds`.
+
+Count the number of jobs for each states:
+
+- `github_actions_job_failure_count`
+- `github_actions_job_success_count`
+- `github_actions_job_cancelled_count`
+- `github_actions_job_inprogress_count`
+- `github_actions_job_queued_count`
+- `github_actions_job_total_count`
+
+## Cost metric
+
+This is the last metric we collect, and it is one of the most important
+ones. It allows us to determine the cost of our CI runs.
+
+### The formula to calculate the cost over a period of time
+
+To calculate this metric, we use the following formula:
+
+```
+cost = duration (per second) / 60 * cost (per minute)
+```
+
+### How do we find the cost per minute?
+
+#### GitHub
+
+As for GitHub, it is quite simple. They provide us with a fixed value, and
+the price never varies. To give an example, for `ubuntu-latest`, we have a cost
+of 0.008$/min, that's it. Easy!
+
+#### Self-Hosted
+
+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.
+
+The cost can be found based on the machine type in the Management Console
+for AWS (when creating an EC2 instance) and on the
+[Google Cloud website](https://cloud.google.com/compute/vm-instance-pricing)
+for GCP.
+
+Unfortunately, these values are not accurate as they lack several elements
+such as bandwidth or storage. As for storage costs, they can be found in
+the same places where the machine type cost is available. However, it is
+not possible to determine the bandwidth cost directly.
+
+To overcome this, we had to devise a workaround. We didn't necessarily
+need an exact cost for CI but rather a value close to reality (+/- 5%)
+for data visualization purposes.
+
+We analyzed previous invoices and calculated the additional cost generated
+by bandwidth, which amounted to approximately 30% for each month.
+Consequently, we were able to approximate the cost using the following formula:
+
+```
+cost = (cost_per_flavor + cost_per_storage) * 130 / 100
+```
+
+_Good news, GCP and AWS costs are quite the same for the same flavors._
+
+### The different tags and their associated cost
+
+| Provider                           | Runner                      | Cost ($ per min)   |
+| ---------------------------------- | --------------------------- | ------------------ |
+| GitHub                             | `ubuntu-latest`             | 0.008              |
+| GitHub                             | `ubuntu-18.04`              | 0.008              |
+| GitHub                             | `ubuntu-20.04`              | 0.008              |
+| GitHub                             | `ubuntu-22.04`              | 0.008              |
+| GitHub                             | `ubuntu-20.04-4core`        | 0.016              |
+| GitHub                             | `ubuntu-22.04-4core`        | 0.016              |
+| GitHub                             | `ubuntu-22.04-8core`        | 0.032              |
+| AWS & GCP                          | `small`                     | 0.000625           |
+| AWS & GCP                          | `medium`                    | 0.00125            |
+| AWS & GCP                          | `large`                     | 0.0025             |
+| AWS & GCP                          | `xlarge`                    | 0.005              |
+| AWS & GCP                          | `3xlarge`                   | 0.01               |
+| GCP                                | `large-nested`              | 0.0025             |

docs/setup/utilizing-grafana.md

@@ -0,0 +1,2 @@
+# Utilizing Grafana
+

docs/tags/aws.md

@@ -0,0 +1,2 @@
+# AWS
+

docs/tags/google-cloud.md

@@ -0,0 +1,2 @@
+# Google Cloud
+

mkdocs.yml

@@ -40,6 +40,18 @@ theme:
 nav:
 - Home: index.md
 
+- Getting Started:
+  - Local Setup: getting-started/local-setup.md
+  - Run it Locally: getting-started/run-it-locally.md
+
+- Setting up graphs:
+  - 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
+
 markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true