Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: state how long metrics statistics trail and what a give-up costs

Yudhi Armyndharis13c8599724df
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 26868118b..72ba44f30 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5314,7 +5314,7 @@ openwa_messages_total{direction="incoming"} 940
openwa_messages_failed_total 4
```
-Values come from `StatsService.getOverview()` plus `process.memoryUsage()`/`process.uptime()`. The render is memoized for 5000 ms to avoid re-running the overview query on every scrape, and `getOverview()` is itself memoized for `STATS_CACHE_TTL_MS` (default 30 s), so the database-derived series and `openwa_stats_available` can trail the data database by up to `STATS_CACHE_TTL_MS` + 5 s plus the time the overview query takes (the memo TTL counts from when the query completes), or by up to 5 minutes when the database stops answering and the last kept result stands in for the late read.
+Values come from `StatsService.getOverview()` plus `process.memoryUsage()`/`process.uptime()`. The render is memoized for 5000 ms to avoid re-running the overview query on every scrape, and `getOverview()` is itself memoized for `STATS_CACHE_TTL_MS` (default 30 s), so the database-derived series and `openwa_stats_available` can trail the data database by up to `STATS_CACHE_TTL_MS` + 5 s plus the time the overview query takes (the memo TTL counts from when the query completes), or by up to 5 minutes plus `STATS_CACHE_TTL_MS` when the database stops answering and the last kept result stands in for the late read.
**Errors:** `401` — `METRICS_TOKEN` is configured but the bearer is missing or does not match (`{ "statusCode": 401, "message": "Invalid metrics token", "error": "Unauthorized" }`) · `404` — `METRICS_TOKEN` is unset/blank, so the endpoint is disabled (`{ "statusCode": 404, "message": "Metrics endpoint is disabled (set METRICS_TOKEN to enable)", "error": "Not Found" }`) · `429`: 10 failed token attempts from one client within a minute; only failures count, and the block lifts as the window slides (`{ "statusCode": 429, "message": "Too many failed metrics token attempts" }`).
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.md
index 466f47867..a1dcea093 100644
--- a/docs/10-devops-infrastructure.md
+++ b/docs/10-devops-infrastructure.md
@@ -936,9 +936,11 @@ still pending after that, the scrape serves the last result it kept, up to 5 min
`openwa_stats_available` stays 1; the late result fills the memo and is kept for the next scrape. With no result
that recent, such as the first scrape after start, or a read that has hung for more than 5 minutes after the last
good one, the series are left out and the gauge reads 0. A read still pending after 5 minutes is given up on and the
-next scrape starts a new one. The process, HTTP, webhook and queue series are served as usual. A read still pending is shared by the scrapes that arrive
-meanwhile, so they answer without waiting again and add no query of their own, whatever
-`STATS_CACHE_TTL_MS` is. The 2 seconds bound the wait, not the query: nothing cancels it in the database.
+next scrape starts a new one. The process, HTTP, webhook and queue series are served as usual. While a read is
+still within its 5 minutes it is shared by the scrapes that arrive meanwhile, so they answer without waiting again
+and add no query of their own. With `STATS_CACHE_TTL_MS=0` each give-up starts a new overview query while the
+abandoned one stays pending in the database; at the default the replacement joins the overview flight already
+running. The 2 seconds bound the wait, not the query: nothing cancels it in the database.
Access is **disabled by default**: the endpoint returns **404** unless `METRICS_TOKEN` is set. When
set, scrapers must send `Authorization: Bearer <token>` (compared with `timingSafeEqual`); a missing or