Prometheus metrics

Prometheus scraping

This is the scrape endpoint for Prometheus-compatible monitoring systems. It returns the Prometheus text exposition format instead of JSON and intentionally lives at /metrics, outside the versioned /api/v1 routes.

curl --silent http://localhost:9875/metrics

Each scrape contains metric declarations (# HELP and # TYPE) followed by the current samples and their labels. The response uses text exposition version 0.0.4.

Prometheus configuration

When Prometheus runs on the same machine as the game, add this scrape job to prometheus.yml:

scrape_configs:
    - job_name: uptime
      scrape_interval: 15s
      static_configs:
          - targets:
                - 127.0.0.1:9875

The API only listens locally. If Prometheus runs in Docker, 127.0.0.1 points to the container—not the host. With Docker Desktop, use host.docker.internal:9875 and make sure the container is allowed to reach the host service.

First PromQL queries

Use these queries to confirm the scrape and discover the emitted series:

up{job="uptime"}

{job="uptime"}

The first query is 1 when Prometheus can scrape the game and 0 when the scrape fails. The second returns every series collected by the uptime job so you can inspect the current metric names and labels before building dashboards or alerts.

Metric discovery through JSON

The versioned API also exposes machine-readable discovery endpoints:

• Metric catalog — names, types, units, and help text for every declared Prometheus metric.
• Metric paths — all metric paths present in the current registry capture.
• Metric series — decoded samples for one registry path.

Use /metrics for Prometheus scraping. Use the JSON endpoints when building custom tools that need to browse declarations or inspect a decoded series without parsing the exposition format.

curl -X GET "https://example.com/metrics"