docs(Cockpit): add new federation documentation for Cockpit - int-add-observability-federate-doc

pages/cockpit/how-to/federate-scaleway-metrics.mdx

@@ -0,0 +1,101 @@
+---
+meta:
+  title: How to federate Scaleway metrics with your own Prometheus
+  description: Learn how to retrieve your Scaleway metrics with federation and reuse them within your own Prometheus with this step-by-step guide.
+content:
+  h1: How to federate Scaleway metrics with your own Prometheus
+  paragraph: Learn how to retrieve your Scaleway metrics with federation and reuse them within your own Prometheus with this step-by-step guide.
+tags: federation cockpit metrics observability monitoring prometheus
+categories:
+  - observability
+dates:
+  validation: TBD
+  posted: TBD
+---
+
+In this page, we will show you how to federate your Scaleway metrics using the `/federate` endpoint of your Scaleway datasources with a [Prometheus](https://prometheus.io) configuration.
+
+<Macro id="requirements" />
+
+ - A Scaleway account logged into the [console](https://console.scaleway.com)
+ - [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+ - [Created](/cockpit/how-to/create-token/) a Cockpit token with read access in the same region as the metrics data source
+ - A running [Prometheus](https://prometheus.io) instance
+
+<Message type="info">
+  The `/federate` endpoint will not be billed during the beta phase. After the beta, the endpoint will incur additional costs.
+</Message>
+
+Prometheus federation can be used to gather all your metrics in a unique Prometheus instance, or to downsample different metrics to reduce storage costs in the long run.
+Since you have full control over your Prometheus instance, you can also use federation to increase metrics retention.
+
+## Configure your Prometheus
+
+Create a `prometheus.yml` file to configure your Prometheus instance, using the example below.
+Make sure you replace `$SCW_DATASOURCE_URL` with the URL of your data source. The URL can be found under the "API URL" section in the [Data sources tab](https://console.scaleway.com/cockpit/dataSource) of the Scaleway console. Replace `$SCW_READ_TOKEN` with your Cockpit token with read permissions.
+
+```yaml
+global:
+  scrape_interval: 3m
+
+scrape_configs:
+  - job_name: 'federate-scaleway-metrics'
+    honor_labels: true
+    metrics_path: '/federate'
+    http_headers:
+      X-Token:
+        values:
+          - '$SCW_READ_TOKEN'
+    params:
+      'match[]':
+        - '{__name__="instance_.*"}'
+        - '{region="fr-par"}'
+    static_configs:
+      - targets:
+        - '$SCW_DATASOURCE_URL'
+```
+
+<Message type="important">
+  Do not include `https://` in the `SCW_DATASOURCE_URL`.
+</Message>
+
+Modify the different `match[]` parameters according to the metrics you want to retrieve. In this example, you will federate:
+  - All metrics with a name that starts with `instance_`
+  - All metrics with the label `region` with the value `fr-par`
+
+You can also set `honor_labels` to `false` if you prefer to not override the different labels that your Prometheus could set that conflict with Scaleway metrics label.
+For example, with `honor_labels` set to `false` the Scaleway label `job` will be relabelled as `exported_job` to avoid collision.
+
+## Run your Prometheus instance
+
+Once you have configured your `prometheus.yml` file, you can use docker-compose to run your Prometheus instance with the configuration and start federating Scaleway metrics.
+
+1. Create a `docker-compose.yml` file with:
+    ```yaml
+    services:
+    prometheus:
+    image: prom/prometheus:latest
+    container_name: prometheus
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+    ports:
+      - 9090:9090
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+    ```
+
+2. Go to `http://localhost:9090/targets` and you should see your newly created target, federating your Scaleway metrics.
+
+## Monitor your federation volumes
+
+You can monitor the amount of samples federated with the `/federate` endpoint by looking at the `observability_cockpit_federate_exported_sample_total:increase5m` in your Cockpit.
+This metric indicates the total volume of exported samples through the federation endpoint over a 5 minutes interval.
+
+1. Go to the Cockpit page on the Scaleway console
+2. Click on `Open dashboards` to open your Grafana
+3. Go to the Explore tab on the left panel
+4. Search for the `observability_cockpit_federate_exported_sample_total:increase5m` metrics
+
+<Message type="info">
+  You can also federate this metrics to monitor your volume of federated metrics directly in your Prometheus instance.
+</Message>

pages/cockpit/reference-content/cockpit-supported-endpoints.mdx

@@ -64,6 +64,23 @@ Refer to the [official Mimir documentation](https://grafana.com/docs/mimir/lates
     - Path: `/prometheus/api/v1/status/buildinfo`
 </Concept>
 
+<Concept>
+  ## Additional endpoints
+
+  Methods: `GET`
+
+  - Path: `/federate`
+</Concept>
+
+<Message type="info">
+  The `/federate` endpoint aims to replicate the behavior of the classic Prometheus `/federate` endpoint, but it is not an official Mimir endpoint.
+</Message>
+
+<Message type="important">
+  The `/federate` endpoint will not be billed during the beta phase. After the beta, the endpoint may incur additional costs.
+    Refer to the [How to federate metrics](/cockpit/how-to/federate-scaleway-metrics) documentation page for more information.
+</Message>
+
 <Concept>
   ## Mimir rules endpoints