Skip to main content

Set the metrics token

With the token of its metrics endpoint, peckaboo.com also reads the metrics of your Woodpecker CI server: the queue, the runs and steps of each repository, and the state of the server. The token is a value you choose and set on the server yourself. peckaboo.com is an independent service and not a project of Woodpecker CI.

Set the token on the server

Woodpecker CI 3 opens its metrics endpoint only once WOODPECKER_PROMETHEUS_AUTH_TOKEN is set on the server. Until then it answers /metrics with 404.

  1. Create a long random value, for example with openssl rand -hex 32.
  2. Set it in the environment of the Woodpecker CI server as WOODPECKER_PROMETHEUS_AUTH_TOKEN, or write it into a file whose path WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE names.
  3. Restart the server.

WOODPECKER_STEP_LEVEL_METRICS adds the counters of failed steps and the durations of the steps to the metrics. It is on unless your server sets it to false. Without it, the view of the repositories and steps has no steps.

Check it

curl -H "Authorization: Bearer $TOKEN" https://ci.example.com/metrics

$TOKEN stands for the value you set on the server, and ci.example.com for its address.

Answer What it means
200 and a text that starts with # HELP the endpoint is open and accepts the token
401 and invalid or missing token the request carried no token
403 the token is not the one set on the server
404 no token is set on the server, or a proxy in front of it does not pass /metrics on

A proxy in front of the server has to pass /healthz, /version and /metrics on to it. peckaboo.com reads /metrics at the address of the server, with the token; the separate endpoint without a token that WOODPECKER_METRICS_SERVER_ADDR opens is not used.

Give the token to peckaboo.com

  • For a new instance, enter it as Metrics token under Connect an instance in the instance settings.
  • For an instance that is connected already, enter it under Replace the token.

peckaboo.com asks the metrics endpoint with the token before it saves it, and keeps the token it had when the server refuses the new one. A saved token is stored encrypted and never shown again; the screen only says when it was set.

When the token changes on the server

Once the server holds another token, it refuses the one peckaboo.com has. The dashboard and the instance settings then say why the metrics are not current, and the views of the metrics show what the last poll that read them found. Replace the token, and the next poll reads the metrics again.