Cockpit API
Scaleway's Cockpit allows you to monitor your applications and their infrastructure by giving you insights and context into their behavior. Cockpit also enables you to visualize your metrics and logs through a Grafana dashboard. With Cockpit, you can also push your own data as Scaleway products' data is included by default.
The Observability Cockpit provides you with two Prometheus Remote Write endpoints for pushing metrics and logs. You can push metrics with any Prometheus Remote Write
compatible agent such as Prometheus, Grafana or OpenTelemetry Collector.
You can push logs with any Loki compatible agent such as Promtail, Fluentd, Fluent Bit or Logstash.
This API concerns the Cockpit service which is currently in Public Beta.
Concepts
Refer to our dedicated concepts page to find definitions of the different terms referring to the Observability Cockpit.
Quickstart
-
Configure your environment variables.
Note:This is an optional step that seeks to simplify your usage of the API.
export SCW_SECRET_KEY="<API secret key>"export SCW_PROJECT_ID="<Scaleway Project ID> -
Activate your Cockpit.
Run the following command to activate your Cockpit:
curl -X POST \-H "X-Auth-Token: $SCW_SECRET_KEY" \https://api.scaleway.com/cockpit/v1beta1/activate \-H "Content-Type: application/json" \-d '{"project_id": "'"$SCW_PROJECT_ID"'"}' -
Build push URLs.
A Cockpit has 4 endpoints which are given when creating or getting a Cockpit. The endpoints look like the following:
{[...],"endpoints": {"metrics_url": "https://metrics.cockpit.fr-par.scw.cloud","logs_url": "https://logs.cockpit.fr-par.scw.cloud","alertmanager_url": "https://alertmanager.cockpit.fr-par.scw.cloud""grafana_url": "<project_id>.dashboard.obs.fr-par.scw.cloud"},[...]}The
metrics_url
is a domain that exposes a Prometheus-like API to manage metrics, and thelogs_url
exposes a Loki API to manage logs.Important:To be able to send metrics and logs, you need the exact URL to use with your pushers.
- The Prometheus Remote Write endpoint to push your metrics is the following:
https://metrics.cockpit.fr-par.scw.cloud/api/v1/push
- The Remote Write endpoint to push your logs is the following:
https://logs.cockpit.fr-par.scw.cloud/loki/api/v1/push
- The Prometheus Alertmanager endpoint is the following:
https://alertmanager.cockpit.fr-par.scw.cloud/alertmanager
- The Prometheus Remote Write endpoint to push your metrics is the following:
-
Create your token to push metrics and logs.
Find out how to create your token via the console or run the following command to create your token via API.
curl -X POST \"https://api.scaleway.com/cockpit/v1beta1/tokens" \-H "Content-Type: application/json" \-H "X-Auth-Token: $SCW_SECRET_KEY" \-d '{"project_id": "00000000-0000-0000-0000-000000000000","name": "token-name","scopes": {"query_metrics": false,"write_metrics": true,"setup_metrics_rules": false,"query_logs": false,"write_logs": true,"setup_logs_rules": false,"setup_alerts": false}}'Important:Your token's
secret_key
only displays once. Make sure you save it. We strongly recommend that you only give the minimal amount of permissions to your token. Metric pushers should only have thewrite_metrics
scope, and log pushers thewrite_logs
one. -
Configure the Grafana agent.
Find out how to configure, start the Grafana agent and see your metrics and logs in our documentation.
Note:The promtail configuration for the logs does not support custom headers. The
tenant_id
field corresponds to the headerX-Scope-OrgID
which is one of the supported headers. For more details on the different supported headers, see our troubleshooting documentation for when your pusher does not support custom HTTP headers. -
Configure rules and alerts.
Upon its creation, a Grafana instance is already configured by default with logs and metrics data sources. The alert manager data source is also configured. This means that you will be able to configure your alerting rules, for metrics and logs, configure your contact points and notification policies and manage your alert silences from Grafana.
To do so, on your Grafana instance, click the Bell icon on the left of your screen. The
Alerting
page displays with tabs. Refer to the External links section of this page if you are not familiar with the alert manager or alert rules.Important:For the alerts and rules to be created in your Cockpit, you must use the data sources provided by Scaleway.
In the
Alert rules
tab, you must selectMimir or Loki alert
when creating your alert rules in theRule type
field. Then, on theSelect data source
field that appears on the right, select the data source you wish to create the rule on.For all the other tabs, from
Contact points
toAlert groups
, you will be configuring the alert manager. TheChoose Alertmananger
field displays at the top of the screen.Important:Make sure that you select
Scaleway Alerting
as your alert manager as the alerts are managed by the platform. If you useGrafana
you will work with the local alert manager which is deactivated.
- You have a Scaleway account
- You have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page
- You have activated your Cockpit via the console or API
- You have installed
curl
- You have installed docker
- You have installed docker compose
- You have a Linux machine to run the container on. You can still run the container on macOS or Windows, but your logs will not be available in your Cockpit.
Technical information
Regional availability
Scaleway's Cockpit is available globally. Find out about our product availability in our dedicated documentation.
Current supported endpoints
- The current supported endpoints for metrics are the following. For more information about the endpoints, refer to the Mimir documentation
# Remote write endpointspath /api/v1/push# Query endpointspath /prometheus/api/v1/querypath /prometheus/api/v1/query_rangepath /prometheus/api/v1/query_exemplarspath /prometheus/api/v1/seriespath /prometheus/api/v1/labelspath /prometheus/api/v1/label/*path /prometheus/api/v1/metadatapath /prometheus/api/v1/readpath /prometheus/api/v1/status/buildinfo# Ruler endpointspath /prometheus/api/v1/rulespath /prometheus/api/v1/alertspath /prometheus/config/v1/rulespath /prometheus/config/v1/rules/*
- The current supported endpoints for logs are the following. For more information about the endpoints, refer to the Loki documentation
# Remote write endpointspath /loki/api/v1/push# Query endpointspath /loki/api/v1/querypath /loki/api/v1/query_rangepath /loki/api/v1/labelspath /loki/api/v1/labelpath /loki/api/v1/label/*path /loki/api/v1/tailpath /loki/api/v1/series# Ruler endpointspath /loki/api/v1/rulespath /loki/api/v1/rules/*path /api/prom/rulespath /api/prom/rules/*path /prometheus/api/v1/rulespath /prometheus/api/v1/alerts
- The current supported endpoints for the alert manager are the following. For more information on the endpoints, refer to the Prometheus documentation
# Prometheus alertmanagerpath /alertmanager/*# Alertmanager configuration (see Mimir doc)path /api/v1/alerts
Troubleshooting
Refer to our troubleshooting documentation if your pusher does not support HTTP headers or if you want to reset your Grafana password.
Technical limitations
- Metrics and logs data is retained 31 days. After this period, data older than 31 days is deleted.
- The number of active metrics time series is limited to 250,000 per Cockpit by default.
- The number of active log streams is limited to 5000 per Cockpit.
- It is not yet possible to downsample metrics.
Going further
For more information about Cockpit, you can check out the following pages:
- Cockpit Documentation
- Scaleway Slack Community join the #observability-beta and the #observability channels
- Contact our support team
External links
If you are interested in learning more, you can check out the following pages:
- Introduction to Prometheus. This page gives a general introduction to what Prometheus is.
- Introduction to Promtail. Promtail is an agent that collects and forwards logs to a Grafana Loki instance.
- Introduction to Grafana Agent. Grafana Agent is an agent that embeds multiple other agents like Prometheus or Promtail.
- Pushing logs using Fluentbit. Fluentbit is another commonly used agent that collects and forwards logs.
- Pushing metrics using Prometheus's agent mode. Prometheus can be used in an "agent-mode" that can scrape local targets and forward them using remote-write. This is useful for scenarios where targets are exposed in a private network (like a VPN or a single host) but need to be forwarded outside of it.
- Prometheus remote write configuration. This page gives the exact configuration parameters that can be used to configure Prometheus's remote-write.
- Prometheus data model. This page explains the Prometheus data model to help understand the concepts of metrics, time series, labels and samples, and how they work together.
- Article on Prometheus label cardinality and performance. When working with metrics, the cardinality, which is the number time series for a given metric, is extremely important. This article explains why.
- Integrations supported by Grafana Agent. Grafana Agent has many other embedded agents that can be used to monitor various software, like PostgreSQL or MongoDB. All of them can be found on the left menu of this page.
- Introduction to alerting using Prometheus
- How to create a Mimir or Loki managed alerting rule using Grafana
- How to manage alerting rules using Grafana
- How to manage contact points using Grafana
- How to manage notification policies using Grafana
- How to manage silences using Grafana.
A Cockpit is an instance that stores logs and metrics and provides a dedicated dashboarding system on Grafana to visualize them. Each Scaleway Project can have only one Cockpit.
POST/cockpit/v1beta1/activate
GET/cockpit/v1beta1/cockpit
GET/cockpit/v1beta1/cockpit/metrics
POST/cockpit/v1beta1/deactivate
POST/cockpit/v1beta1/reset-grafana
Tokens are secret keys that allow you to authenticate against your Cockpit’s endpoints (metrics, logs, alerts).
GET/cockpit/v1beta1/tokens
POST/cockpit/v1beta1/tokens
GET/cockpit/v1beta1/tokens/{token_id}
DELETE/cockpit/v1beta1/tokens/{token_id}
Contact points define individuals or channels to be notified when an alert is triggered. Contact points include emails. You can configure other contact point types such as on-call systems, Slack and texts in your Grafana. Whenever an alert is triggered, all contact points receive a notification.
GET/cockpit/v1beta1/contact-points
POST/cockpit/v1beta1/contact-points
POST/cockpit/v1beta1/delete-contact-point
Managed alerts are predefined monitoring rules configured by Scaleway. They send notifications when abnormal behaviors are detected on your products. These alerts are limited to metrics and logs related to Scaleway products only.
POST/cockpit/v1beta1/disable-managed-alerts
POST/cockpit/v1beta1/enable-managed-alerts
POST/cockpit/v1beta1/trigger-test-alert
Grafana users are individuals who can log in to Grafana. Each user is associated with a role. Users can have two roles: viewer and editor. A viewer can only view dahsboards. An editor can build and view dashboards.
GET/cockpit/v1beta1/grafana-users
POST/cockpit/v1beta1/grafana-users
POST/cockpit/v1beta1/grafana-users/{grafana_user_id}/delete
POST/cockpit/v1beta1/grafana-users/{grafana_user_id}/reset-password
A pricing plan is associated with each Cockpit. Pricing plans give you information on how you are billed for the Cockpit product.
GET/cockpit/v1beta1/plans
POST/cockpit/v1beta1/select-plan