ReferenceHealth and Metrics

Health and Metrics

Liveness and readiness for orchestrators, and Prometheus metrics on a separate port. None of them need an API key.

GET/healthzLiveness

GET/readyzReadiness

GET:9090/metricsPrometheus

Liveness

/healthz answers 200 whenever the process serves requests, database or not. Use it to decide when to restart the container.

GET /healthz

HTTP/1.1 200 OK
{"status": "ok"}

Readiness

/readyz answers 200 once a database is loaded and 503 before. Use it to decide when to send traffic. On the first start, the download of the current database takes a few seconds.

HTTP/1.1 200 OK
{"status": "ready"}

HTTP/1.1 503 Service Unavailable
{"status": "not_ready"}

The image has no shell and no curl. Its HEALTHCHECK runs locate-me healthcheck, which probes /readyz on the configured listener.

Metrics

Prometheus text format on metrics.listen (default 0.0.0.0:9090), a listener of its own so it is never published with the API. Set metrics.token_sha256 to require Authorization: Bearer <token>.

curl -H "Authorization: Bearer $METRICS_TOKEN" \
  http://localhost:9090/metrics

Metric	Labels	Description
`locateme_http_requests_total`	`route`, `status`	Requests by route and status.
`locateme_http_request_duration_seconds`	`route`	Latency histogram, 25 µs to 5 s.
`locateme_lookups_total`	`outcome`	Lookups: `found`, `not_found`, `reserved`, `invalid`.
`locateme_auth_failures_total`		Requests with a missing or unknown key.
`locateme_rate_limited_total`	`scope`	Rejections: `api_key`, `client_ip` (failed auth), `playground`.
`locateme_api_key_requests_total`	`key`	Authenticated requests per key. Also `_lookups_total` and `_rate_limited_total`.
`locateme_shed_requests_total`		Requests shed with `503 overloaded`.
`locateme_request_timeouts_total`		Requests that hit the deadline.
`locateme_inflight_requests`		Requests being processed now.
`locateme_open_connections`		Open client connections.
`locateme_db_build_timestamp_seconds`		Build time of the loaded database. Alert when it grows old.
`locateme_db_reloads_total`		Database activations. Also `_update_checks_total` and `locateme_config_reloads_total`.

The route label is one of lookup, bulk, info, healthz, readyz, playground, docs and other. Looked-up addresses never appear in metrics or logs.