GioJSdocs
ReleasesGitHub ↗
On this page

[metrics]

The Prometheus endpoint /_gio/metrics: off until the section exists, then answering this machine only unless a token or an IP allowlist says who else may scrape it.

gio.toml
[metrics]
token = "a-long-random-secret"         # Authorization: Bearer <token>
ip_allowlist = ["10.0.0.5", "10.1.0.0/16"]

Observability lists the series it exposes. The endpoint is served by Rust and never waits for the Node worker.

Reference

KeyDefaultDescription
enabledbooleantrueServe the endpoint. The default applies once a [metrics] section exists: with no section at all, metrics are off.0 / false / empty: /_gio/metrics answers 404
tokenstring""Require Authorization: Bearer <token>, compared in constant time. A missing or wrong token gets 401.
ip_allowliststring[][]Client IPs or CIDR blocks allowed to scrape; anyone else gets 403. The client is the one [server] trusted_proxies resolves, never the proxy. A malformed entry stops startup.0 / false / empty: Empty with no token: loopback clients only. A /0 entry with no token warns.

Behavior

ConfigurationWho may scrape
No [metrics] section, or enabled = falseNobody: 404
Neither token nor ip_allowlistLoopback clients only; others get 403
token onlyAny client with the token; without it 401
ip_allowlist onlyListed clients; others 403
BothListed clients that also send the token
  • The answer is text/plain; version=0.0.4, the Prometheus text format.
  • In loopback-only mode, a request that carries X-Forwarded-For, Forwarded or X-Real-IP from a peer outside trusted_proxies is refused: a reverse proxy on the same machine would otherwise make every client look local. A proxy that sends none of those headers still does, so list a local proxy in trusted_proxies. Startup says so whenever metrics are loopback-only and trusted_proxies is empty.
  • A trusted proxy whose forwarding header does not name a client (unknown) gets 403 from the allowlist: an unknown client is never admitted.

Startup warnings

WhenStartup warning
ip_allowlist has a /0 and no token is set[metrics] ip_allowlist includes 0.0.0.0/0 and no token is set: /_gio/metrics is open to every client of that family - set [metrics] token, or list only your scrapers' addresses

Examples

Scrape from the same machine

gio.toml
[metrics]
bash
curl http://127.0.0.1:3000/_gio/metrics

Scrape with a token

gio.toml
[metrics]
token = "a-long-random-secret"
prometheus.yml
scrape_configs:
  - job_name: giojs
    metrics_path: /_gio/metrics
    authorization:
      credentials: a-long-random-secret
    static_configs:
      - targets: ["app.internal:3000"]

Open to everyone

Say so explicitly - startup then warns:

gio.toml
[metrics]
ip_allowlist = ["0.0.0.0/0", "::/0"]

Good to know

  • gio.toml holds the token in plain text; error messages and --check-config never print it.
  • Metrics are per server instance; scrape every instance.
  • A malformed entry ("10.0.0.0/33") is a startup error: invalid ip_allowlist entry "10.0.0.0/33": expected an IP address or CIDR block such as "10.0.0.1", "10.0.0.0/8" or "fd00::/8".

Version history

VersionChanges
v0.1.0-beta.8Without a token or ip_allowlist the endpoint answers loopback clients only (it used to answer everyone, with a warning). ip_allowlist accepts CIDR blocks, checks the client behind trusted proxies, and a malformed entry stops startup. An allowlist open to everyone with no token logs a warning.
v0.1.0-beta.1Introduced with enabled, token and ip_allowlist.