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's withMonitor / @monitor). The first one creates the monitor; later ones update it, so the config in code is the source of truth.
SettingIn monitor_configDefaultMeaning
Slugmonitor_slugfrom the nameWhat jobs check in with. Lowercase letters, digits, -, _; 50 characters. Unique per project.
Scheduleschedule0 * * * *A 5-field crontab (or @hourly, @daily, @weekly, @monthly, @yearly), or every N minutes / hours / days / weeks / months / years.
TimezonetimezoneUTCIANA name. Crontabs run in it, DST included.
Check-in margincheckin_margin1 minHow late a check-in may be before it counts as missed.
Max runtimemax_runtime30 minA run still in progress after this is marked timed out.
Failure tolerancefailure_issue_threshold1Failed, missed or timed-out check-ins in a row that open an incident.
Recoveryrecovery_threshold1OK check-ins in a row that resolve it.
Owner, notifications, mute——Dashboard only.

How check-ins are judged

  • Each new check-in (in_progress, ok or error) 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_progress followed by ok / error with the same check_in_id is one run; its duration is the SDK's duration, 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 (fingerprint cron:<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:

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

SettingDefaultMeaning
Method, headers, bodyGETAny method; up to 30 headers; a body for POST/PUT/PATCH/DELETE/OPTIONS.
Timeout10 s1–30 s, for the whole exchange (DNS, connect, TLS, headers and body).
Expected status2xxCodes (200), classes (2xx) or ranges (200-299).
Keyword—Must (or must not) appear in the first 1 MB of the body.
Follow redirectsonUp to 5 hops; with it off, a 3xx is the answer (add 3xx to the expected codes).
Downtime after3Failed checks in a row; the last one is confirmed by an immediate re-check.
Recovered after1Passing checks in a row.
TLS warning14 daysWarn once per certificate this long before it expires.
EnvironmentproductionWhich 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 most UPTIME_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, keyword or redirect.
  • Downtime opens an incident, an issue in Errors (Downtime detected for <url>: <reason>, category uptime, fingerprint uptime:<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

DataKept
Cron check-insCRON_CHECKIN_RETENTION_DAYS (90 days)
Uptime checksUPTIME_CHECK_RETENTION_DAYS (30 days)
Hourly uptime rollups, resolved incidents400 days
Monitor notifications90 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.ts and uptime.ts (dashboard API), uptime-runner.ts and uptime-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 (envelope check_in items) and apps/web/src/server/sentry/monitors-api.ts (the URL check-in and the /api/0 check-in API).
  • Worker jobs monitors.crons and monitors.uptime (every minute) in src/server/jobs/worker.ts.