From 3f3ec207a2d62466dc68a370a1a24494b937c4e4 Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 22 Aug 2026 15:05:14 +0200 Subject: [PATCH 1/2] docs(obs): document Sentry DSN separation and explicit log intake Clarify that web and botasaurus use separate Sentry projects and that SENTRY_ENABLE_LOGS must be set explicitly for structured log forwarding. --- .../docs/web-application/reference/monitoring.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/src/content/docs/web-application/reference/monitoring.mdx b/src/content/docs/web-application/reference/monitoring.mdx index 0bd4d6f2..fc36a815 100644 --- a/src/content/docs/web-application/reference/monitoring.mdx +++ b/src/content/docs/web-application/reference/monitoring.mdx @@ -39,4 +39,17 @@ Do not leave `CHANGE_ME_HEALTH_CHECK_TOKEN` anywhere in production. Once the pro ## Application Performance Monitoring using Sentry -When you specify `SENTRY_DSN` in your environment variables, the application will be setup to use Sentry. +When you specify `SENTRY_DSN` in your environment variables, html2rss-web initializes Sentry for Issue capture (Rack middleware and operational failure emission). Structured log intake requires an explicit `SENTRY_ENABLE_LOGS=true` — a DSN alone does not forward stdout logs. + +### DSN separation (required) + +Use **separate Sentry projects** for html2rss-web and botasaurus-scrape-api. Never share a DSN between them. + +| Env var | Service | Sentry project | +| --- | --- | --- | +| `SENTRY_DSN` | html2rss-web | Project A (web) | +| `BOTASAURUS_SENTRY_DSN` | botasaurus-scrape-api | Project B (scraper) | + +In `docker-compose.yml`, the botasaurus service maps `BOTASAURUS_SENTRY_DSN` into its own `SENTRY_DSN` and does **not** fall back to the web project's DSN. + +For on-call triage, alert rules, and dashboard baselines, see the [Sentry runbook in the web repo](https://github.com/html2rss/html2rss-web/blob/main/docs/README.md#sentry-runbook). From a1375852e5a377c4a340a5f2a24fe6965c32a96c Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 22 Aug 2026 15:14:35 +0200 Subject: [PATCH 2/2] docs(monitoring): compact health and Sentry reference Merge redundant probe sections into one table and tighten Sentry env var guidance without changing the verified compose/runtime contract. --- .../web-application/reference/monitoring.mdx | 44 +++++++------------ 1 file changed, 15 insertions(+), 29 deletions(-) diff --git a/src/content/docs/web-application/reference/monitoring.mdx b/src/content/docs/web-application/reference/monitoring.mdx index fc36a815..ddc31083 100644 --- a/src/content/docs/web-application/reference/monitoring.mdx +++ b/src/content/docs/web-application/reference/monitoring.mdx @@ -7,17 +7,13 @@ import { Code } from "@astrojs/starlight/components"; ## Health Endpoints -`html2rss-web` exposes these health endpoints: - -- `GET /api/v1/health/live`: liveness probe, no auth -- `GET /api/v1/health/ready`: readiness probe, no auth -- `GET /api/v1/health`: authenticated health probe, bearer token required - -## Authenticated Health Checks - -Use `GET /api/v1/health` when you want an authenticated operator-facing probe. +| Endpoint | Auth | Purpose | +| --- | --- | --- | +| `GET /api/v1/health/live` | none | Process liveness | +| `GET /api/v1/health/ready` | none | Config readiness | +| `GET /api/v1/health` | bearer | Operator and uptime checks | -Set the environment variable `HEALTH_CHECK_TOKEN`, then send it as a bearer token: +Set `HEALTH_CHECK_TOKEN`, then call the authenticated endpoint: -The response is JSON and reports the current status, timestamp, environment, uptime, and reserved checks payload. - -Do not leave `CHANGE_ME_HEALTH_CHECK_TOKEN` anywhere in production. Once the production hardening change is released, boot will fail if any account still uses that placeholder token. +The response is JSON with status, timestamp, environment, uptime, and a checks payload. Boot fails in production if `HEALTH_CHECK_TOKEN` is still `CHANGE_ME_HEALTH_CHECK_TOKEN` after the hardening release. -## Probe Selection +## Sentry -- Use `/api/v1/health/live` for a simple process-alive signal. -- Use `/api/v1/health/ready` for the standard config-readiness check without auth. -- Use `/api/v1/health` for authenticated monitoring from your uptime system or operator tooling. +Set `SENTRY_DSN` to enable Issue capture in html2rss-web (Rack middleware and operational failures). Structured log intake is opt-in: set `SENTRY_ENABLE_LOGS=true` explicitly — a DSN alone does not forward stdout logs. -## Application Performance Monitoring using Sentry +Use separate Sentry projects for html2rss-web and botasaurus-scrape-api. Never share a DSN. -When you specify `SENTRY_DSN` in your environment variables, html2rss-web initializes Sentry for Issue capture (Rack middleware and operational failure emission). Structured log intake requires an explicit `SENTRY_ENABLE_LOGS=true` — a DSN alone does not forward stdout logs. - -### DSN separation (required) - -Use **separate Sentry projects** for html2rss-web and botasaurus-scrape-api. Never share a DSN between them. - -| Env var | Service | Sentry project | -| --- | --- | --- | -| `SENTRY_DSN` | html2rss-web | Project A (web) | -| `BOTASAURUS_SENTRY_DSN` | botasaurus-scrape-api | Project B (scraper) | +| Env var | Service | +| --- | --- | +| `SENTRY_DSN` | html2rss-web | +| `BOTASAURUS_SENTRY_DSN` | botasaurus-scrape-api | -In `docker-compose.yml`, the botasaurus service maps `BOTASAURUS_SENTRY_DSN` into its own `SENTRY_DSN` and does **not** fall back to the web project's DSN. +In `docker-compose.yml`, the botasaurus service maps `BOTASAURUS_SENTRY_DSN` into its own `SENTRY_DSN`, requires it at startup, and does not fall back to the web project's DSN. For on-call triage, alert rules, and dashboard baselines, see the [Sentry runbook in the web repo](https://github.com/html2rss/html2rss-web/blob/main/docs/README.md#sentry-runbook).