From c47e5a5f123cf0ed50ce9f87358df9c4704fd3dc Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sun, 22 Nov 2026 02:18:34 +0000 Subject: [PATCH] docs(observability): document the health check and the metrics endpoint The page explains GET /api/health (public, rate limited, 503 when a critical check fails), GET /api/metrics (administrators, Prometheus text 0.0.4 with stackiq_info, stackiq_up and stackiq_gebruik_total), the manifest's observability block as their source, and that /api/settings/status is a settings endpoint, not a health check. Ticks adopt-apphost task 4.1. Assisted-by: ClaudeCode:claude-opus-5-5 --- CHANGELOG.md | 4 + docs/features/README.md | 1 + docs/features/observability.md | 110 ++++++++++++++++++++++++ openspec/changes/adopt-apphost/tasks.md | 3 +- 4 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 docs/features/observability.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0662354ce..274ac0fb4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] ### Added +- Health and metrics documentation (adopt-apphost): `docs/features/observability.md` + describes the public `/api/health` check, the administrator-only Prometheus + `/api/metrics`, the manifest's `observability` block that drives both, and + why `/api/settings/status` is not a health check. - MCP action surface (mcp-full-action-surface), for hermiq agents: 28 derived read tools (search and get on 14 catalogue schemas), create and update on `vulnerability`, and 27 curated tools in the `stackiq` provider. The curated diff --git a/docs/features/README.md b/docs/features/README.md index 16b1b0223..30f3af676 100644 --- a/docs/features/README.md +++ b/docs/features/README.md @@ -35,6 +35,7 @@ All data is stored as OpenRegister objects (no own database tables). OpenRegiste | [CMDB Import](#cmdb-import) | Import a municipality's TOPdesk CMDB export (xlsx) as applications, suppliers, usages and owners | | [Data quality](./data-quality.md) | A data quality score on every application and usage, a confirm-current action and a Data quality page per organisation | | [API documentation](api-documentation.md) | Read OpenRegister's document of the catalogue objects and stackiq's own endpoints in the app, and download either as JSON | +| [Health and metrics](observability.md) | A public health check for uptime probes and Prometheus metrics for administrators, configured in the manifest | | [Open Data Publishing](#open-data-publishing) | Expose the catalogue as a public open-data API | | [GEMMA Compliance](#gemma-compliance) | Built around VNG GEMMA Softwarecatalogus reference | | [Reference Component Coverage](reference-component-coverage.md) | Which GEMMA reference components an organisation covers, where it has gaps and where applications overlap | diff --git a/docs/features/observability.md b/docs/features/observability.md new file mode 100644 index 000000000..23c0071da --- /dev/null +++ b/docs/features/observability.md @@ -0,0 +1,110 @@ +# Health and metrics + +Stackiq has two endpoints for monitoring: a health check that an uptime probe can call without logging in, and Prometheus metrics for administrators. Both come from OpenRegister's AppHost and answer from the `observability` block in `src/manifest.json`, so a new check or metric is configuration, not code. + +## Health: `GET /api/health` + +``` +GET https:///index.php/apps/stackiq/api/health +``` + +- Public: no session or app password is needed, so a load balancer or uptime monitor can call it. +- Rate limited to 240 anonymous calls a minute, which is enough for a probe every few seconds. +- The body names the overall status, the app, the installed version and the result of each check: + +```json +{ + "status": "ok", + "app": "stackiq", + "version": "0.2.13", + "checks": { + "database": "ok", + "openregister": "ok" + } +} +``` + +| Check | What it checks | +|-------|----------------| +| `database` | Nextcloud's database answers a query (`SELECT 1`) | +| `openregister` | OpenRegister's object service can be reached; stackiq keeps all its data there | + +A failed check reads `failed` or `failed: ` instead of `ok`, for example `failed: openregister unavailable`. The reason never carries internal error text; that goes to the Nextcloud log. + +### Status codes + +The manifest sets `statusCodePolicy` to `adr006`: + +| Overall status | When | HTTP code | +|----------------|------|-----------| +| `ok` | Every check passed | 200 | +| `degraded` | Only a check marked `degraded` failed | 200 | +| `error` | A critical check failed (both checks are critical) | 503 | + +A probe only has to look at the HTTP code: 503 means stackiq cannot serve its users. + +Example probe: + +```bash +curl -fsS https:///index.php/apps/stackiq/api/health || echo "stackiq is down" +``` + +## Metrics: `GET /api/metrics` + +``` +GET https:///index.php/apps/stackiq/api/metrics +``` + +- Administrators only. Anyone else gets the Nextcloud login redirect or a 401, never metric data. +- The response is Prometheus text exposition format 0.0.4 (`Content-Type: text/plain; version=0.0.4; charset=utf-8`). +- Every metric name starts with `stackiq_`. + +| Metric | Type | Meaning | +|--------|------|---------| +| `stackiq_info` | gauge | Always 1; its labels carry the app version, the PHP version and the Nextcloud version | +| `stackiq_up` | gauge | 1 while the app answers | +| `stackiq_gebruik_total` | gauge | The number of usage records in the `stackiq` register (schema `usage`) | + +Example scrape configuration, with an app password of an administrator account: + +```yaml +scrape_configs: + - job_name: stackiq + scheme: https + metrics_path: /index.php/apps/stackiq/api/metrics + basic_auth: + username: monitoring-admin + password: + static_configs: + - targets: [''] +``` + +## The manifest is the source of truth + +The checks and metrics are listed in the `observability` block of `src/manifest.json`: + +```json +"observability": { + "health": { + "statusCodePolicy": "adr006", + "checks": [ + { "id": "database", "type": "database" }, + { "id": "openregister", "type": "orAvailable" } + ] + }, + "metrics": [ + { + "name": "gebruik_total", + "type": "gauge", + "help": "Gebruik (usage) records", + "source": { "kind": "objectCount", "register": "stackiq", "schema": "usage" } + } + ] +} +``` + +To add a check or a metric, add an entry here. `stackiq_info` and `stackiq_up` are always there and are not listed. + +## `/api/settings/status` is not a health check + +`GET /api/settings/status` says whether stackiq's settings are configured (`fullyConfigured`, `autoConfigCompleted`, the version information). It needs a login and answers 200 even when OpenRegister is down, so a monitor must not use it as a health check. Use `/api/health` instead. diff --git a/openspec/changes/adopt-apphost/tasks.md b/openspec/changes/adopt-apphost/tasks.md index ad7b3afb6..4a463d059 100644 --- a/openspec/changes/adopt-apphost/tasks.md +++ b/openspec/changes/adopt-apphost/tasks.md @@ -29,7 +29,8 @@ ## 4. Docs -- [ ] 4.1 Update app docs: observability page documenting the real `/api/health` + `/api/metrics` endpoints (probe/scrape examples), the manifest `observability` block as the source of truth, and an explicit note that `/api/settings/status` is a settings endpoint, not health +- [x] 4.1 Update app docs: observability page documenting the real `/api/health` + `/api/metrics` endpoints (probe/scrape examples), the manifest `observability` block as the source of truth, and an explicit note that `/api/settings/status` is a settings endpoint, not health + > `docs/features/observability.md`, linked from `docs/features/README.md`. ## 5. Quality gates + delivery