# Metrics

Prometheus metrics at `GET /metrics` (text format). The endpoint is disabled unless `WHEREBOX_METRICS_TOKEN` is set; scrape it with `Authorization: Bearer <token>`. Route labels are route *patterns* (e.g. `/v1/map.:ext`), so cardinality stays bounded.

| Metric | Type | Labels | Description |
|---|---|---|---|
| <a id="wherebox_build_info"></a>`wherebox_build_info` | gauge | `render_version`, `data_version` | Always 1; labels carry the render and data versions of this process. |
| <a id="wherebox_http_requests_total"></a>`wherebox_http_requests_total` | counter | `route`, `method`, `status` | HTTP requests by route pattern, method and status code. |
| <a id="wherebox_http_request_duration_seconds"></a>`wherebox_http_request_duration_seconds` | histogram | `route` | HTTP request latency by route pattern. Buckets (s): 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10. |
| <a id="wherebox_renders_total"></a>`wherebox_renders_total` | counter | `result` | Map image requests by outcome: `rendered` (new render), `cache_hit` (image cache), `joined` (shared an identical in-flight render). |
| <a id="wherebox_render_stage_seconds"></a>`wherebox_render_stage_seconds` | histogram | `stage` | Time per render stage (resolve, geometry, style, neighbors, raster, encode, total) for new renders. Buckets (s): 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10. |
| <a id="wherebox_render_queue_active"></a>`wherebox_render_queue_active` | gauge | — | Renders running now. |
| <a id="wherebox_render_queue_waiting"></a>`wherebox_render_queue_waiting` | gauge | — | Renders waiting for a slot (beyond `WHEREBOX_RENDER_CONCURRENCY`). |
| <a id="wherebox_problems_total"></a>`wherebox_problems_total` | counter | `code` | Error responses by catalog code (see the errors reference). |
| <a id="wherebox_auth_total"></a>`wherebox_auth_total` | counter | `outcome` | Key-auth outcomes when `WHEREBOX_AUTH=keys`: `ok` (a key or OAuth token), `anonymous` (no key, demo allowance) or an error code. |
| <a id="wherebox_anonymous_renders_total"></a>`wherebox_anonymous_renders_total` | counter | `result` | Map requests on the anonymous demo allowance (no key) by outcome: `rendered` (counted against the allowance) or `cache_hit` (free). Anonymous usage is not stored per account, so this is its only record. |
| <a id="wherebox_map_pool_total"></a>`wherebox_map_pool_total` | counter | `event` | MapLibre map pool events: `created`, `reused`, `discarded`. |
| <a id="wherebox_geometry_cache_total"></a>`wherebox_geometry_cache_total` | counter | `result` | Area/subdivision geometry cache lookups: `hit` or `miss`. |
| <a id="wherebox_geocoder_total"></a>`wherebox_geocoder_total` | counter | `result` | Place-name geocoder fallback lookups: `cache` (answered from the in-process cache), `fetched` (found), `miss` (provider knows no such place), `error`. |
| <a id="wherebox_upstream_total"></a>`wherebox_upstream_total` | counter | `result` | Basemap/tile/terrain fetches through the HTTP cache: `cache` (served from disk), `fetched`, `revalidated`, `error`. |

## Example scrape config

```yaml
scrape_configs:
  - job_name: wherebox
    metrics_path: /metrics
    authorization:
      credentials: <WHEREBOX_METRICS_TOKEN>
    static_configs:
      - targets: ["api:8080"]
```