Monitoring the server from outside
How to point an uptime monitor at the server, how to keep the monitoring from raising the running cost, and how to tell the maintenance mode (Maintenance) from an outage. The probe paths are in the health check section of the running guide.
Third-party facts below carry the date they were confirmed and their source. Services change their plans and screens; check the linked page before relying on a limit.
Which URL to monitor
Section titled “Which URL to monitor”| Path | For | Touches the DB | In the maintenance mode |
|---|---|---|---|
GET /api/v1/instance/health |
Uptime monitors, status pages, the web client | At most once per 60 s per process | 503 with Retry-After and {"status":"maintenance"} |
GET /healthz, GET /health/live |
The platform’s liveness probe | Never | 200 {"status":"maintenance"} |
GET /readyz, GET /health/ready |
The load balancer’s or Kubernetes’ readiness probe | On every request (concurrent requests share one check) | 200 {"status":"maintenance"} |
Point the external monitor at /api/v1/instance/health, not at /readyz (/health/ready): it queries the database on every request,
so a monitor with a short interval keeps a scale-to-zero database awake. The probes are for your platform.
The monitoring section of mycroblog-gcp checks /health/live on Google Cloud, and that of mycroblog-aws checks /readyz, each from the platform’s own monitor at a long interval: its uptime_period is what that costs, since each check wakes an instance.
Where the server’s own metrics, traces, and error reports go is the observability section of the same modules, which monitoring reads. By default it sends each to the platform: on Google Cloud the metrics to Cloud Monitoring, the request traces to Cloud Trace, and the error reports to Error Reporting, all three from what Cloud Run sends them, with their APIs enabled; on AWS the metrics to CloudWatch in Embedded Metric Format, the error reports to CloudWatch Logs, and the traces to X-Ray, through a collector that runs beside the server in every task (traces on AWS ECS). monitoring needs the metrics there: it refuses observability.metrics = "settings", which leaves metrics_exporter to the settings input.
Responses of /api/v1/instance/health (no authentication, Cache-Control: no-store):
| State | HTTP | Body |
|---|---|---|
| Healthy | 200 |
{"status":"ok","checked_at":"<RFC 3339>"} |
| Unavailable (the database is unreachable or the schema is not applied) | 503 |
{"status":"unavailable","checked_at":"<RFC 3339>"} |
| Maintenance mode | 503 with Retry-After |
{"status":"maintenance"} |
/healthz and /readyz answer 200 with {"status":"ok"} when healthy, and /readyz answers 503 with a problem document when the database is not ready. /health/live and /health/ready are the same checks under other names.
On Cloud Run, call the paths that do not end in z. Cloud Run reserves some paths that end in z and answers them with its own 404 before a request reaches the container: /healthz is one, and nothing promises that /readyz keeps answering. From outside a Cloud Run deployment (an uptime monitor, curl), use /health/live, /health/ready, or /api/v1/instance/health. The probes of the container itself are not affected.
The body never carries a reason, host name, or version. The cause is in the server log.
checked_at is the time of the check the answer is based on. The server runs the database check at most once a minute per process and reuses the result,
so a monitor that polls more often than every 60 s sees the same checked_at and gains nothing. With several processes, each runs its own check.
With origin_secret set, these three paths still answer without the header, so they do not show that the CDN lost it. Monitor a page through the CDN too, such as https://<host>/about, if a monitor is your first sign of trouble.
Keep the monitoring cheap
Section titled “Keep the monitoring cheap”- Scale-to-zero databases. If the monitor’s interval is shorter than the time the database waits before it stops, the database never stops. Neon suspends a compute after 5 minutes without activity; the Free plan cannot turn this off (confirmed 2026-10-25, Neon: Scale to zero). As a rule of thumb, an interval of 5 minutes or more lets an idle database stop between checks, and each check wakes it for the check plus the idle time. A federated server receives deliveries from other servers around the clock, so its database is awake for much of the day anyway; the extra cost is limited to the quiet hours.
- Prefer a cheaper split if idle cost matters most. Monitor
/health/live(it never touches the database) at a short interval, and the database-backed/api/v1/instance/healthat a long one (15 minutes or more)./health/liveanswers200during the maintenance mode too, so match"status":"ok"in the body. - The requests themselves are small. One check every 5 minutes is about 8,640 requests a month, every minute about 43,200. That fits in the free tier of Cloud Run (2 million requests, 180,000 vCPU-seconds, and 360,000 GiB-seconds a month; time rounded up to 100 ms; confirmed 2026-10-23, Cloud Run pricing).
Telling the maintenance mode from an outage
Section titled “Telling the maintenance mode from an outage”During the maintenance mode (maintenance guide) the health endpoint answers 503, which most monitors treat like an outage.
The status code alone cannot tell them apart, so decide on the body:
- Treat
"status":"ok"in the body as healthy, and anything else as down. A keyword or JSON value monitor does this. - To avoid alerts during planned maintenance, set the monitor’s maintenance window if the service has one (see the table below), or pause the monitor by hand before you start.
- UptimeRobot’s Free plan has no maintenance window: pause the monitor or accept the alert.
Setting up the monitors
Section titled “Setting up the monitors”All of these check the same thing: GET https://<your-host>/api/v1/instance/health is healthy when the answer is 200 and the body contains "status":"ok".
| Service | Monitor type | Healthy when | Maintenance window | Confirmed |
|---|---|---|---|---|
| UptimeRobot | Keyword | The body contains "status":"ok" |
Not in Free (Solo and above) | 2026-10-25, pricing |
| Better Stack | HTTP status, or Keyword | 2xx, or the body contains "status":"ok" |
Unverified | 2026-10-25 |
| Gatus | Endpoint conditions | [STATUS] == 200 and [BODY].status == ok |
maintenance in the config |
2026-10-25, README |
| Uptime Kuma | HTTP(s) - Keyword, or JSON Query | The body contains "status":"ok", or status is ok |
Built in | 2026-10-23, README |
| Upptime | sites in .upptimerc.yml |
200 and the body contains "status":"ok" |
None | 2026-10-25, Configuration |
UptimeRobot
Section titled “UptimeRobot”Create a monitor of type Keyword: URL https://<your-host>/api/v1/instance/health, keyword "status":"ok", alert when the keyword does not exist.
The Free plan allows 50 monitors at an interval of 5 minutes, and includes keyword monitors.
“Custom headers & statuses” and maintenance windows start at the Solo plan (paid, 60-second interval)
(confirmed 2026-10-25, pricing). A keyword monitor is enough here, because the check is on the body.
Better Stack
Section titled “Better Stack”Two forms work (confirmed 2026-10-25, Uptime monitor, Keyword monitor):
- An HTTP status monitor: it treats a
2xxanswer as up, so200is up and503(unavailable or maintenance) opens an incident. - A Keyword monitor: “Alert us when” is “URL doesn’t contain keyword”, keyword
"status":"ok". The match is case-insensitive.
The check frequency and the maintenance windows of the Free plan are unverified: the official pages do not state them for the Free plan. The free tier’s counts (10 monitors and heartbeats together, one status page) are from the pricing page, confirmed 2026-10-23.
In config.yaml (default interval 60s; confirmed 2026-10-25, README):
endpoints: - name: my url: "https://<your-host>/api/v1/instance/health" interval: 5m conditions: - "[STATUS] == 200" - "[BODY].status == ok"Gatus has a top-level maintenance section (start as hh:mm, duration, timezone defaulting to UTC, every as a list of weekdays, empty meaning every day)
for planned work. The README only says it is for avoiding alerts during maintenance windows; check the behavior on your version.
Uptime Kuma
Section titled “Uptime Kuma”Add a monitor of type HTTP(s) - Keyword with the keyword "status":"ok", or HTTP(s) - Json Query with the query status and the expected value ok.
The accepted status codes default to 200-299, so the maintenance 503 and the outage 503 are both down. Uptime Kuma has a maintenance feature
for monitor windows (wiki lists it; its details are unverified).
The monitor types were confirmed 2026-10-23 in the source (monitor.js,
EditMonitor.vue).
Upptime
Section titled “Upptime”In .upptimerc.yml (confirmed 2026-10-25, Configuration):
sites: - name: My server url: https://<your-host>/api/v1/instance/health __dangerous__body_down_if_text_missing: '"status":"ok"'By default 20x and 30x count as up; set expectedStatusCodes: [200] to accept only 200. The check runs from GitHub Actions on a schedule set for all sites
(workflowSchedule.uptime, default every 5 minutes, which is also the shortest GitHub Actions allows). The option name says it is not recommended,
but it is the way to test the body.
A status page
Section titled “A status page”Set status_page_url (MY_STATUS_PAGE_URL, an https: URL; see the configuration reference)
to the public page of your monitor. The server shows the link in GET /api/v1/instance, in the sign-in and error pages it renders, in the web client
(also when the server does not answer), and on the maintenance page, so a user who cannot reach the server can find out why.
It is read from the configuration, not from the database, so it works when the database is down. A change takes effect after a restart.
Options for the page itself (this server does not import a status page’s state, so also post announcements as a server-wide notice):
- The hosted status page of the monitoring service you chose (UptimeRobot’s Free plan has one status page without customization; Better Stack’s free tier has one), the pages that Gatus and Uptime Kuma serve themselves, or Upptime’s static site on GitHub Pages.
- Atlassian Statuspage, which is a place to publish and not a monitor. A component has one of five states: Operational, Under maintenance, Degraded performance,
Partial outage, Major outage (API values
operational,under_maintenance,degraded_performance,partial_outage,major_outage; confirmed 2026-10-23, What is a component?, Statuspage API). How to change a component’s state automatically from a monitor’s alert is unverified (it needs a per-service integration set up on an actual account).
For LLMs and coding agents:this page as Markdown, llms.txt,llms-full.txt, llms-small.txt