Skip to content

docs(monitoring): Sentry DSN separation and compact health reference #1244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gildesmarais merged 2 commits into from
Aug 22, 2026
Merged

docs(monitoring): Sentry DSN separation and compact health reference #1244

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f3ec20
docs(obs): document Sentry DSN separation and explicit log intake
gildesmarais Aug 22, 2026
a137585
docs(monitoring): compact health and Sentry reference
gildesmarais Aug 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 17 additions & 18 deletions src/content/docs/web-application/reference/monitoring.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,13 @@ import { Code } from "@astrojs/starlight/components";

## Health Endpoints

`html2rss-web` exposes these health endpoints:
| 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 |

- `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.

Set the environment variable `HEALTH_CHECK_TOKEN`, then send it as a bearer token:
Set `HEALTH_CHECK_TOKEN`, then call the authenticated endpoint:

<Code
code={`
Expand All @@ -27,16 +23,19 @@ Set the environment variable `HEALTH_CHECK_TOKEN`, then send it as a bearer toke
lang="bash"
/>

The response is JSON and reports the current status, timestamp, environment, uptime, and reserved checks payload.
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.

## Sentry

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.
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.

## Probe Selection
Use separate Sentry projects for html2rss-web and botasaurus-scrape-api. Never share a DSN.

- 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.
| Env var | Service |
| --- | --- |
| `SENTRY_DSN` | html2rss-web |
| `BOTASAURUS_SENTRY_DSN` | botasaurus-scrape-api |

## Application Performance Monitoring using Sentry
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.

When you specify `SENTRY_DSN` in your environment variables, the application will be setup to use Sentry.
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).
Loading