Cron and uptime monitors
Monitor → Crons tells you when a scheduled job misses a run, fails or runs too long. Monitor → Uptime checks your URLs on a schedule and tells you when they go down or their TLS certificates are about to expire. A job checks in with one HTTP call when it starts and when it ends; jobs that already report to Sentry Crons keep working once their DSN points at Guidely.
Incidents show up in Monitor → Errors as issues (category cron or uptime), so your error alert rules fire on them too, and each monitor can also notify its own email recipients, Slack channel and issue tracker.
Cron monitors
Create a monitor
Either:
- In the dashboard: Crons → New monitor. Pick a crontab (with timezone) or an interval, see the schedule in words and its next five runs, then add the check-in to your job. The monitor page shows its check-in URL, a curl example and the HTTP API (and snippets for Sentry SDKs).
- From code: send a check-in with a
monitor_config(a POST to the check-in URL or the API with it in the JSON body, or a Sentry SDK'swithMonitor/@monitor). The first one creates the monitor; later ones update it, so the config in code is the source of truth.
| Setting | In monitor_config | Default | Meaning |
|---|---|---|---|
| Slug | monitor_slug | from the name | What jobs check in with. Lowercase letters, digits, -, _; 50 characters. Unique per project. |
| Schedule | schedule | 0 * * * * | A 5-field crontab (or @hourly, @daily, @weekly, @monthly, @yearly), or every N minutes / hours / days / weeks / months / years. |
| Timezone | timezone | UTC | IANA name. Crontabs run in it, DST included. |
| Check-in margin | checkin_margin | 1 min | How late a check-in may be before it counts as missed. |
| Max runtime | max_runtime | 30 min | A run still in progress after this is marked timed out. |
| Failure tolerance | failure_issue_threshold | 1 | Failed, missed or timed-out check-ins in a row that open an incident. |
| Recovery | recovery_threshold | 1 | OK check-ins in a row that resolve it. |
| Owner, notifications, mute | — | — | Dashboard only. |
How check-ins are judged
- Each new check-in (
in_progress,okorerror) answers the expected run and sets the next one: the next crontab tick after the check-in's minute (in the monitor's timezone), or the check-in plus the interval. A job that checks in a few seconds after 10:00 expects 11:00 next, not 10:00 again. in_progressfollowed byok/errorwith the samecheck_in_idis one run; its duration is the SDK'sduration, or the time between the two. URL and API check-ins without an id close the environment's latest run still in progress.- Every minute the worker (
monitors.crons) marks a missed check-in for each expected run with no check-in by expected time + margin, and times out runs in progress past max runtime. A run that finishes after it timed out keeps the timeout and records its real duration. - DST: a run inside a skipped hour (02:30 on the spring-forward night) runs at the first minute after the gap; a run in a repeated hour (01:30 on the fall-back night) runs once.
- Every environment is tracked separately (production, staging…: the SDK's
environment, mapped onto the project's environments like errors are). An environment starts with its first check-in, so a monitor created in the dashboard waits for one before it can miss anything. - Disabled monitors drop check-ins and are never marked missed. Muted monitors (or muted environments) still track incidents but open no issues and notify nobody.
Incidents
failure_issue_threshold failures in a row open an incident:
- An issue in Errors (
Cron failure: <monitor>: Missed check-in), one per monitor and environment (fingerprintcron:<monitorId>), with an occurrence for each failure. New-issue and regression error alerts fire on it. - A notification to the monitor's email recipients and Slack channel, and a ticket in its issue tracker.
recovery_threshold OK check-ins in a row resolve the incident and its issue and send a recovery notification. The next incident reopens the same issue (a regression).
Sending check-ins
The check-in URL (on the monitor page; any HTTP client works):
curl "https://<api host>/api/<ingestId>/cron/<monitor_slug>/<public key>/?status=in_progress"
curl "https://<api host>/api/<ingestId>/cron/<monitor_slug>/<public key>/?status=ok" # or error
GET or POST. Query parameters: status (required: in_progress, ok, error), environment, check_in_id, duration (seconds), release. A POST may send the same fields as JSON, plus monitor_config. Answers 202 {"id": "<check-in id>"}; 404 for an unknown monitor without a config, 400 for a bad status or a disabled monitor, 401 for an unknown key, 429 when the monitor allowance is used up. The URL carries the project's client key (Settings → Sentry SDKs (DSN)); a project gets its Default key the first time a monitor page or that settings page opens.
In a crontab:
0 3 * * * curl -s "$URL?status=in_progress" && ./export.sh && curl -s "$URL?status=ok" || curl -s "$URL?status=error"
The check-in API, with a project API key:
| Method | Path | Body |
|---|---|---|
POST | /api/0/organizations/<org>/monitors/<slug>/checkins/ | { "status", "environment"?, "duration"? (ms), "release"?, "monitor_config"? } → 201 check-in |
PUT | …/checkins/<check_in_id>/ or …/checkins/latest/ | { "status", "duration"? (ms) } |
GET | …/checkins/?environment=&per_page= | Newest first |
Authenticate with Authorization: Bearer gly_sk_… (a project API key with the monitors:write scope, Settings → Source maps → API keys; store it as GUIDELY_KEY) or Authorization: DSN <dsn>. <org> is the workspace slug. A key limited to some environments (Only some when you create it, or the pencil next to it) gets 403 for check-ins in any other environment, and its lists only show check-ins from its environments.
Sentry SDKs
Jobs that already use a Sentry SDK's cron support check in as they are once the SDK's DSN is this project's (Settings → Sentry SDKs (DSN)):
import * as Sentry from "@sentry/node";
Sentry.init({ dsn: "https://<key>@<your Guidely API host>/<ingestId>" });
await Sentry.withMonitor("nightly-export", () => runExport(), {
schedule: { type: "crontab", value: "0 3 * * *" },
timezone: "America/New_York",
checkinMargin: 5,
maxRuntime: 60,
});
from sentry_sdk.crons import monitor
@monitor(monitor_slug="nightly-export", monitor_config={"schedule": {"type": "crontab", "value": "0 3 * * *"}})
def run_export(): ...
Go, Ruby, PHP, Java and the other Sentry SDKs work the same way (snippets on the monitor page, under Sentry SDKs). The check-in API above is Sentry's, so sentry-cli monitors run works too.
Uptime monitors
Uptime → New monitor: a URL, how often to check it (1, 5, 10, 20, 30 or 60 minutes) and what counts as up. Test now runs one check of the configuration as typed.
| Setting | Default | Meaning |
|---|---|---|
| Method, headers, body | GET | Any method; up to 30 headers; a body for POST/PUT/PATCH/DELETE/OPTIONS. |
| Timeout | 10 s | 1–30 s, for the whole exchange (DNS, connect, TLS, headers and body). |
| Expected status | 2xx | Codes (200), classes (2xx) or ranges (200-299). |
| Keyword | — | Must (or must not) appear in the first 1 MB of the body. |
| Follow redirects | on | Up to 5 hops; with it off, a 3xx is the answer (add 3xx to the expected codes). |
| Downtime after | 3 | Failed checks in a row; the last one is confirmed by an immediate re-check. |
| Recovered after | 1 | Passing checks in a row. |
| TLS warning | 14 days | Warn once per certificate this long before it expires. |
| Environment | production | Which environment the incidents are filed under. |
- Checks run from this deployment (one region). The worker (
monitors.uptime, every minute) runs each monitor due in the next minute at its own moment: a new monitor gets a random offset in its first 30 seconds and keeps that phase, so checks spread out instead of all firing on the minute. At mostUPTIME_CONCURRENCY(20) run at once. - Requests go through Guidely's SSRF guard: only http(s) on ports 80/443, no credentials in the URL, and every hostname (including each redirect hop) must resolve to public addresses only. Private, loopback and link-local targets are refused when saving and again at check time.
- A failure records why:
timeout,dns,connect,tls(invalid, expired or untrusted certificate),blocked,status,keywordorredirect. - Downtime opens an incident, an issue in Errors (
Downtime detected for <url>: <reason>, category uptime, fingerprintuptime:<monitorId>) and notifications; each further failed check adds an occurrence. Recovery resolves both and notifies. - TLS expiry: a warning issue (level warning, fingerprint
uptime-ssl:<monitorId>) and a notification once per certificate; a renewed certificate resolves the warning. An expired certificate fails the check. - Uptime % is the share of passing checks (24 h, 7 days, 30 days), from hourly rollups kept current as checks land.
- All projects (under Overview) has an Uptime card with every monitor in the workspace's projects in one list, whatever environment it files under: live status (down and failing first, paused last), one bar per day for the last 30 days, and uptime for 24 h, 7 days and 30 days.
Notifications
Each monitor has its own channels, on top of the error alert rules that fire on its incident issues: email recipients, a Slack channel from the project's Slack integrations, and an issue tracker (one ticket per incident's issue). Send test notification in the edit dialog checks them. Incidents posted to a channel of the Guidely Slack app get a Mute monitor button (not in workspaces that require two-step verification or enforce single sign-on, where Slack actions are off). Emails go through the outbound email queue and Slack posts through the alert outbox (retried up to 5 times), like error alerts.
Billing
Monitors are billed per active monitor per month (Sentry's monitor seats), cron and uptime alike. A monitor counts once per calendar month (UTC) in which it is active at any point: when it is created or re-enabled, or, for monitors that stay active, on the worker's first pass of the month. Pausing and re-enabling within a month doesn't count it twice; deleting it doesn't refund the month.
When the monthly allowance is used up, creating or enabling a monitor is refused ("Your plan's monitor allowance for this month is used up…"), a check-in whose monitor_config would create a monitor is dropped as rate limited (X-Sentry-Rate-Limits: …:monitor:…:usage_exceeded), and at the start of a month the newest monitors beyond the allowance are disabled (marked monitor allowance used up). Check-ins themselves are not metered.
Retention
| Data | Kept |
|---|---|
| Cron check-ins | CRON_CHECKIN_RETENTION_DAYS (90 days) |
| Uptime checks | UPTIME_CHECK_RETENTION_DAYS (30 days) |
| Hourly uptime rollups, resolved incidents | 400 days |
| Monitor notifications | 90 days |
Code map
apps/web/src/server/services/monitors/:check-ins.ts(ingest, missed / timeout detection, incident counters),schedule.ts(crontab and interval math),cron.tsanduptime.ts(dashboard API),uptime-runner.tsanduptime-probe.ts(the worker and one check),incidents.ts(error issues),notify.ts(email, Slack, tickets),usage.ts(monitor seats),retention.ts.apps/web/src/server/safe-fetch.ts:safeProbe, the SSRF-guarded request behind uptime checks.apps/web/src/server/sentry/handlers/check-in.ts(envelopecheck_initems) andapps/web/src/server/sentry/monitors-api.ts(the URL check-in and the/api/0check-in API).- Worker jobs
monitors.cronsandmonitors.uptime(every minute) insrc/server/jobs/worker.ts.