NavigationContentFooter

Cockpit API

Introduction

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, logs, and traces through a Grafana dashboard. With Cockpit, you can also push data from your Scaleway resources, if they are integrated with Cockpit.

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.

Note

This API concerns the Cockpit service.

Concepts

Refer to our dedicated concepts page to find definitions of the different terms referring to the Observability Cockpit.

Quickstart

  1. 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>
  2. Build push URLs.

    Your Cockpit has 5 endpoints which 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",
    "traces_url": "https://traces.cockpit.fr-par.scw.cloud"
    },
    [...]
    }

    The metrics_url is a domain that exposes a Prometheus-like API to manage metrics, and the logs_url exposes a Loki API to manage logs.

    Important

    To be able to send metrics, logs, and traces, 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
    • Traces have different endpoints depending on the push path you use. The traces endpoint for the OpenTelemetry agent is: https://traces.cockpit.fr-par.scw.cloud/otlp.
  3. Create your token to push metrics, logs, and traces.

    Find out how to create your token via the console or run the following command to create your token via the 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,
    "query_traces": false,
    "write_traces": true
    }
    }'
    Important

    Your token's secret_key only displays once. Make sure that you save it. We strongly recommend that you only give the minimal amount of permissions to your token.

  4. Configure the Grafana agent.

    Find out how to configure, start the Grafana agent and see your metrics, logs, and traces in our documentation.

    Note

    The promtail configuration for the logs does not support custom headers. The tenant_id field corresponds to the header X-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.

  5. Configure rules and alerts.

    Upon creation, your Grafana instance is already configured by default with your data sources and the alert manager data source. This means that you will be able to configure and manage advanced alerting rules, for metrics, logs, and traces, configure contact points and notification policies, from Grafana.

    To do so, access your Grafana dashboard and read our dedicated documentation to find out how to configure alert rules for Scaleway resources. 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.

    Important

    Make sure that you select Scaleway Alerting as your alert manager, as the alerts are managed by the platform. If you use Grafana you will work with the local alert manager which is deactivated.

Requirements
  • 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 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 infrastructure is spread across different regions and Availability Zones. Your Cockpit resources are available in the Paris, Amsterdam and Warsaw regions.

Current supported endpoints

  • The current supported endpoints for metrics are the following. For more information about metrics endpoints, refer to the Mimir documentation

    # Remote write endpoints
    path /api/v1/push
    # Query endpoints
    path /prometheus/api/v1/query
    path /prometheus/api/v1/query_range
    path /prometheus/api/v1/query_exemplars
    path /prometheus/api/v1/series
    path /prometheus/api/v1/labels
    path /prometheus/api/v1/label/*
    path /prometheus/api/v1/metadata
    path /prometheus/api/v1/read
    path /prometheus/api/v1/status/buildinfo
    # Ruler endpoints
    path /prometheus/api/v1/rules
    path /prometheus/api/v1/alerts
    path /prometheus/config/v1/rules
    path /prometheus/config/v1/rules/*
  • The current supported endpoints for logs are the following. For more information about logs endpoints, refer to the Loki documentation

    # Remote write endpoints
    path /loki/api/v1/push
    # Query endpoints
    path /loki/api/v1/query
    path /loki/api/v1/query_range
    path /loki/api/v1/labels
    path /loki/api/v1/label
    path /loki/api/v1/label/*
    path /loki/api/v1/tail
    path /loki/api/v1/series
    # Ruler endpoints
    path /loki/api/v1/rules
    path /loki/api/v1/rules/*
    path /api/prom/rules
    path /api/prom/rules/*
    path /prometheus/api/v1/rules
    path /prometheus/api/v1/alerts
  • The current supported endpoints for the alert manager are the following. For more information about the alert manager endpoints, refer to the Prometheus documentation

    # Prometheus alertmanager
    path /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

  • With the free pricing plan, metrics, traces 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

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.

Cockpits

A Cockpit is an instance that stores metrics, logs, and traces, 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

Data sources

Data sources are endpoints that allow you to fetch metrics, logs and traces from your Cockpit. You can configure multiple datasources for each type

GET
/cockpit/v1beta1/datasources
POST
/cockpit/v1beta1/datasources
DELETE
/cockpit/v1beta1/datasources/{datasource_id}

Tokens

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}

Alert Contact Points

Contact points define individuals or channels to notify when an alert is triggered. Contact points include email addresses. 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

Managed alerts are predefined monitoring rules configured by Scaleway. They send notifications when abnormal behaviors are detected on your resources. These alerts are limited to metrics and logs related to the Scaleway resources integrated with Cockpit

POST
/cockpit/v1beta1/disable-managed-alerts
POST
/cockpit/v1beta1/enable-managed-alerts
POST
/cockpit/v1beta1/trigger-test-alert

Grafana Users

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 dashboards, whereas an editor can create and edit dashboards. Note that the admin username is not available for creation

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

Pricing Plans

Pricing plans give you information on how you are billed for your usage of the Cockpit product.

GET
/cockpit/v1beta1/plans
POST
/cockpit/v1beta1/select-plan

Product Dashboards

Product dashboards are Grafana dashboards that are configured by Scaleway. They are available in your Grafana instance and are associated with your Cockpit. They are designed to help you monitor your Scaleway resources.

GET
/cockpit/v1beta1/grafana-product-dashboards
GET
/cockpit/v1beta1/grafana-product-dashboards/{dashboard_name}
Docs APIScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCarreer
© 2023-2024 – Scaleway