updown.io Exporter

A Prometheus exporter for updown.io. It polls the updown.io API for every check attached to one or more API keys and serves apdex, response-time distribution, request counts, timings and SSL expiry on :9100/metrics.

Configuration

Configuration is read from, in order of precedence:

1. environment variables,
2. /etc/updownio-exporter/updownio-exporter.json,
3. ~/.config/updownio-exporter.json.

{
    "apikeys": ["ro-xxxxxxxxxxxxxxxxxxxx"],
    "loop": {"interval": 240, "reset": 168, "lookback": 24},
    "prometheus": {"port": 9100, "namespace": "updownio"},
    "logging": {"level": "WARNING"}
}

lookback has to be long enough for updown.io to have statistics to serve: a check running every 30 minutes needs about 24 hours.

Running it

... with python:

pip install updownio-exporter
python -m updownio_exporter

... with docker:

docker run -e APIKEYS_0=ro-xxxxxxxxxxxxxxxxxxxx -p 9100:9100 jaesivsm/updownio-exporter

or with a configuration file:

docker run -v ~/.config/updownio-exporter.json:/etc/updownio-exporter/updownio-exporter.json:ro \
    -p 9100:9100 jaesivsm/updownio-exporter

Metrics served

Every check is labelled by its alias, lowercased and with spaces replaced by dashes (My Blog becomes my-blog), or by its token when it has no alias. Disabled checks are skipped: updown.io serves no statistics for them. Enabled checks show up once updown.io has at least an hour of samples for them.

The daemon* metrics come from daemon-metrics and are shared with the other exporters built on it.

How counters are built

updown.io does not expose counters. It returns totals over a time window starting at a given date. The exporter keeps that start date fixed, and on each poll adds the difference with the previous totals to the Prometheus counters.

The histogram is rebuilt the same way from updown.io's under<N> buckets. updown.io only gives counts per bucket, so each new sample is recorded at the midpoint of its bucket. Samples slower than 32 s are recorded at 64 s.

Two things reset this state:

• Every loop.reset hours, the window restarts at now - loop.lookback. The cache and every updownio_* series are cleared, so checks deleted or disabled since then disappear, and daemon{status="loop-reset"} is incremented.
• When a total decreases between two polls, that check's affected series is dropped and starts over on the next poll.

Both show up to Prometheus as ordinary counter resets, so rate() and increase() handle them.

Development

poetry install
make help    # list the targets
make lint    # pycodestyle, mypy, pylint, black --check, poetry check
make build   # wheel + local docker image tagged with the current branch

Releasing

Releases are built and published from the local machine; there is no CI.

make release   # bump the version, commit "release X.Y.Z", tag X.Y.Z, push
make deploy    # PyPI, then Docker Hub as vX, vX.Y, vX.Y.Z and latest

Images are pushed to $(REGISTRY), jaesivsm (Docker Hub) by default, for linux/amd64 and linux/arm64 (PLATFORMS). make push-tag TAG=<tag> pushes a one-off tag. Releases up to 0.0.12 were tagged 0.0.N without the v.