Docs

Getting started

Collapse the desktop navigation to show destination icons; hover an icon to see its label, or expand the navigation to restore text.

1. Create an organization. The organization stores monitors, recipients, reliability settings, and team access. Its owner is automatically added as an enabled alert recipient using the account email. Creation opens the resumable First monitor setup guide.
2. Create monitoring coverage. Open Monitors and choose New monitor. Guided website setup creates recommended HTTP, DNS, TLS, and browser coverage from one URL; individual monitor types remain available for targeted configuration.
3. Select recipients. Attach one or more recipients to each monitor so unhealthy transitions reach the right people.
4. Review collected results. Monitor details show recent executions, while Overview and Reliability turn ringstore history into trends, budgets, and operational context.

First monitor setup

After creating an organization, SiteCanary opens First monitor setup. Return from Overview, Monitors, or Settings → First monitor setup at any time. Organization members share the guide and its progress.

1. Add a website. Enter a name and endpoint, preview coverage, and create your monitors. The account owner's enabled recipient is recommended automatically; you can change or clear it. Creation returns to setup. Individual monitor creation remains available.
2. See a real result. The guide follows the oldest enabled HTTP monitor, or an enabled monitor of another type when no HTTP monitor exists. Waiting progress refreshes every five seconds. A recorded healthy or unhealthy result completes this step; unhealthy results link to investigation. If the first result is delayed beyond the configured interval, execution timeout, and a reload allowance after the latest monitor edit, the guide asks your operator to check the monitoring service. It does not infer healthy status from missing results.
3. Choose a recipient. At least one enabled recipient must be attached to the followed monitor. Edit the monitor to change recipients, or create a new destination. An enabled recipient alone does not prove that a monitor will send it alerts.
4. Verify email. With email enabled, send a test to the saved, attached recipient. Pending and retrying deliveries update automatically. If a test stays queued for more than two minutes, the guide asks your operator to check the monitoring service and email delivery. Repeated setup submissions reuse an outstanding test for that address. Provider acceptance enables I received the email; confirm only after checking the inbox or spam folder. Logging or an unknown provider cannot verify email. Email-disabled installations can run monitors, but verification remains incomplete until the operator enables delivery.

Setup completes when an enabled monitor has a recorded result, an enabled attached recipient has a provider-accepted test, and a member confirms receipt at that recipient's current address. Completion hides the Overview setup prompt; Settings and Monitors retain access. A newer test does not erase a prior confirmation for the same address. Changing the address, disabling or detaching the recipient, or disabling the monitor can make setup incomplete again. This verifies one monitor and one destination, not every monitor or inbox in the organization.

Overview dashboard

Graphs group executions by their scheduled time; run details show actual execution times.

Overview compares up to five monitors within a monitor-type tab. Open Choose monitors, search by name or target, select monitors, and choose Compare selected monitors. The initial selection uses the first five enabled monitors ordered by name; disabled monitors remain available for historical analysis. The URL preserves selection and range. Switching monitor type resets selection.

• Uptime and duration summarize recent success rates and average execution time with monitor-level tables and trends. Comparison graphs use a shared resolution across monitors. Uptime and mean latency summaries weight executions equally, even when bucket sample counts differ.
• Health heatmaps distinguish healthy, unhealthy, and empty time buckets. Graph ranges include their start and exclude their end. Empty buckets mean no scheduled result was recorded; they are not treated as failures.
• On monitor detail pages, reliability calendars and tail latency show longer-term daily health and p50/p95/p99 behavior when enough history exists. Daily calendars include today and show at most 90 dates. Window percentiles are calculated from pooled monitoring history rather than averages of chart percentiles.
• Comparison panels use the same selected monitors: average duration, successful-run percentage, the summary table, heatmap, regressions, and HTTP status mix. Status mix pools recorded responses by response count. Similarity results show their cached analysis window separately. Single-monitor fingerprints appear on monitor details.

Monitor management

Open a monitor to explore performance over a selected range. The header separates enabled state from the latest execution result. Performance charts precede reliability percentiles, UTC daily calendar, and performance fingerprint; unsupported or insufficient history is labeled. HTTP latest-request diagnostics stay fixed while paging run history. Open Configuration and management for settings, ringstore debugging, or deletion; Edit remains beside the range control.

The Monitors inventory groups name, subtype, and target together. Filter by search, category, or enabled state. Enabled/disabled describes configuration; Last result describes the most recent execution, which remains visible for disabled monitors. Never run means no execution has been recorded. Duration and checked-at describe that last run; timestamps use your account timezone. Browser Back restores the inventory URL and filters.

Disabling or changing a monitor cancels obsolete scheduled executions on the next configuration reload. Overlapping or capacity-limited runs are skipped. Accessibility monitor forms display returned unsaved test results without adding them to monitor history.

The Monitors inventory is the central place to search, filter, create, inspect, edit, and delete monitors.

• Individual monitor creation asks only for a name and target. SiteCanary applies recommended protocol, schedule, timeout, validation, and enabled-recipient defaults; open the monitor’s Edit page to configure any of them.
• Every enabled monitor runs on its configured schedule. Initial jitter spreads load; later runs stay on fixed deadlines, and slow executions may overlap. Completions arriving out of order remain in their scheduled bucket while that minute is retained.
• Monitor detail pages show configuration and recent run history. Browser performance monitors can also expose the latest captured screenshot.
• Run timestamps represent actual execution start time. Displayed duration remains the measured execution length.
• Retention limits bound recent Postgres run history. Long-term aggregated trends remain available through ringstore according to its configured rings. The minute ring retains the latest 65 minute buckets even when its write index wraps.

Monitor types

Infrastructure timeouts cover resolution and handshakes. Browser timeouts include waiting for the browser. DNS supports A, AAAA, CNAME, MX, NS, TXT, and SRV; expected MX answers use priority and hostname, while SRV uses priority, weight, port, and hostname. TXT matching preserves case.

• HTTP validates availability, status, latency, response content, headers, redirects, and request configuration.
• HTML Performance loads a page in Chrome and records browser timings, web vitals, and screenshots.
• HTML Accessibility runs axe-core rules and evaluates violation-count thresholds by severity.
• JavaScript Errors observes browser console errors and log volume.
• DNS checks resolution, expected answers, name servers, and domain metadata.
• TCP checks whether a host and port accept a connection.
• TLS checks certificate verification, hostname, protocol, and expiry.
• SSH observes host keys, banners, and negotiated algorithms for availability and drift.

Alerts and recipients

Failed notification deliveries retry independently and survive checker restarts; each recipient has separate delivery state. Deployments with email enabled send alerts through Resend. Provider acceptance completes delivery, but inbox receipt is not guaranteed. Resend deduplicates retries with a stable delivery ID for 24 hours; duplicates remain possible after that window. Deployments with email disabled log alerts and mark them complete instead of sending email.

Recipients are organization-scoped email destinations that can be attached to multiple monitors.

• SiteCanary notifies selected recipients when a monitor transitions from healthy to unhealthy. Repeated unhealthy results do not send duplicate transition notifications.
• The Alerts view records alert history with the monitor, target, status, and failure context.
• Each unhealthy transition records its alert and all enabled recipient deliveries together. Restarts cannot queue a new monitor email without its alert record; replaying a recorded execution does not create another alert. Alerts still appear when no recipients are enabled.
• Open recipient delivery details in Alerts to distinguish Pending, Retrying, Accepted by Resend, and Logged deliveries. Details include attempts, last attempt, completion or next retry time, and a sanitized failure reason. Acceptance does not guarantee inbox receipt. Older alerts may have no linked delivery details.
• Create a recipient with only an email address. SiteCanary uses that address as the initial label and enables delivery; Edit controls the label, address, and enabled state.
• In Settings → Recipients → Edit, save the destination first, then use Send test email. Both email delivery and the saved recipient must be enabled. Tests enter the checker’s durable queue; refresh Edit to see the ten most recent test deliveries. Tests use the saved address, do not change monitor state, and are visible only within the recipient’s organization.

Incident workflow

Shared incidents resolve automatically after every affected monitor reports two consecutive healthy evaluations. Recovery evidence survives checker restarts. Reopening requires two new healthy evaluations from every affected monitor.

Incidents collect reliability events and the monitors affected by them.

• Open an incident to review affected monitors, its timeline, and an automatic summary when one is available.
• The Incidents list shows 20 incidents per page, newest first. Use Previous, Next, or a page number to browse your organization’s history; the page URL can be bookmarked and browser Back returns to the previous page.
• Long paginated lists show the first and last pages and pages near your current position. Ellipses indicate skipped page numbers; use Previous or Next to move one page at a time. The current page and numbered destinations are identified for assistive technology.
• Add timeline notes or move the incident through acknowledged, resolved, and reopened states.
• Incident summaries compare reliability before, during, and after the event and may identify the likely failing layer.

Reliability tools

Scalar comparisons and SLO calculations exclude source buckets crossing the selected boundaries. Burn alerts stay active during insufficient-data periods, and their coverage follows recorded adaptive schedules. A 100% objective breaches on any failure in sufficiently observed burn windows. Missing observations interrupt anomaly confirmation and recovery streaks; active detected shifts can recover after their original anomalies leave the lookback.

Open Reliability to choose between objective and capacity tools or reporting and communication tools.

• SLOs start from a name and monitor with a 99.9% objective over 30 days. Edit controls the monitor, objective, and 7-, 28-, or 30-day window. Delete SLO on the edit page asks for confirmation before removing the objective.
• Dependency topology lets you select one monitor, including its type, to explore the potential blast radius of its failure.
• Guardrails compare p95 latency or response size with a configured limit over a rolling window.
• Reports archive weekly and monthly summaries generated by canaryd, including SLO compliance and incident counts.
• Public status publishes selected monitors under safe display names for customers.
• Reliability insights and recommendations surface prioritized incidents, SLO burns, changes, and deterministic suggestions. Recommendations change configuration only after explicit acceptance.

Annotations and integrations

Annotations record deployments and operational changes so they can be compared with monitoring history.

• Add an annotation with a kind and note at the current time, or expand deployment details to set its occurrence time, environment, service, version, and URL. Select a monitor in deployment details to compare its availability and p95 latency before and after the annotation; annotations without a monitor show no calculated impact.
• Create an ingestion token for CI or deployment automation. Creation returns to Annotations and shows the plain token once; copy it before refreshing or leaving the page.
• Send token-authenticated annotations to POST /api/v1/annotations and revoke tokens that should no longer be accepted. To associate an API annotation with a monitor, supply both check_type and check_id; the monitor must belong to the token’s organization.

curl -X POST http://localhost:8080/api/v1/annotations \ -H "Authorization: Bearer sc_your_token" \ -H "Content-Type: application/json" \ -d '{"kind":"deployment","service":"api","version":"v1.2.3","occurred_at":"2026-07-12T16:00:00Z"}'

Public status pages

• Create a private page with only a name, then select monitors and review their safe display names before publishing.
• A private page is unavailable at its public URL. Use Publish page when it is ready.
• A published page exposes overall health, per-system status, a 90-day reliability history, recent incidents, and an SVG badge. Unpublishing makes both the page and badge unavailable.
• The page and SVG badge use the same overall health calculation, including unresolved incidents and components with missing data. Only incidents connected to monitors selected for that status page appear publicly. Public incident updates use safe lifecycle labels rather than internal event details.

Organization settings

• Initial organization setup asks only for a name. SiteCanary generates an available URL slug, uses the account email for billing, and chooses country and timezone defaults from available account, browser, locale, and request information. Timezone country inference uses exact IANA zone mappings; unmapped zones leave country selection to the remaining locale and account signals. When a reliable country signal is unavailable, it defaults to the United States.
• Only the organization owner or an administrator can delete the organization. The owner cannot be removed from the member list.
• Organization profile controls identity, billing email, country, and timezone defaults. The globally unique slug appears in organization URLs.
• Open the organization profile after creation to change any generated default. Slugs use 3–63 lowercase letters or numbers separated by single hyphens; changing one immediately invalidates links that use its previous value.
• Members adds existing users by email and creates new accounts with an initial password. New accounts inherit the organization timezone. Members can use Edit my account to change only their own email, password, and timezone; these account settings apply across organizations.
• Recipients controls alert delivery destinations.
• Authentication saves configurations for manual testing only. Create a disabled flow from its name and type, then use Edit to configure and test it. Flows cannot currently be attached to monitors.
• Scheduling manages adaptive scheduling policies for normal, incident, and stable conditions. Each saved policy identifies and links to its monitor so you can distinguish policies before updating or deleting them.
• Integrations provides deployment annotations and API tokens.

History and retention

Browser measurement failures produce gaps in typed metric graphs rather than artificial zeros, while execution health still records failure.

SiteCanary keeps two complementary forms of history.

• Postgres run rows retain detailed recent executions up to each monitor's configured limit.
• Ringstore keeps bounded aggregate time series for dashboards, comparisons, SLOs, reports, and public reliability history.
• Scheduled deadlines determine ringstore placement. Downtime and skipped deadlines stay empty rather than being backfilled.

Browsing lists and histories

Monitors, reliability inventories, organization settings lists, and execution histories show 20 rows per page. Use Previous, Next, or numbered links; longer lists show first/last pages and a compact window around the current page. Page URLs can be bookmarked and work without JavaScript. Filters and time ranges stay in those URLs.

Deployments and annotations has separate annotation and API token controls, so browsing one preserves the other list’s position. Invalid page values select the first page, and pages past the end select the final available page. Controls disappear when everything fits on one page.

Public status incident history is also paginated, but the overall health banner still accounts for every visible ongoing incident. Pagination never changes organization permissions or public monitor visibility. Graphs, form selectors, bounded previews, and an individual incident’s timeline remain complete rather than splitting their context across pages.

Outbound monitor safety

Monitor forms, scheduled runs, and form tests use the same destination policy to prevent monitors from reaching internal infrastructure.

• Forms reject direct IP targets before saving unless the address is explicitly allowed. Hostnames are revalidated after DNS resolution at runtime because their addresses can change.
• Private, loopback, link-local, reserved, and metadata destinations are blocked by default.
• HTTP and browser top-level redirects remain within the original registrable domain and stop after five hops. Browser subresources are checked before connection.
• For local-only or private development targets, OUTBOUND_ALLOWED_CIDRS accepts comma-separated exact CIDR exceptions such as 127.0.0.0/8,::1/128. Avoid broad exceptions in public deployments.

Alert transitions

Alerts are sent only when a check transitions from healthy to unhealthy. Recoveries do not trigger notifications.

Delivery runs in a separate background worker so a slow email provider does not delay monitor results. Failed requests retry automatically; interrupted deliveries resume after restart once their claim expires, normally within one minute. Alerts and recipient test history show delivery progress. Provider acceptance does not guarantee inbox receipt.

Auth flow types

Configuration and manual testing only. Open Settings → Authentication to create, edit, test, or delete organization-scoped auth flows. Scheduled monitors do not execute these flows, and there is no monitor attachment, credential cache, token refresh, or browser session reuse.

Create a flow from its name and type; it starts disabled and opens Edit. Configure one request or static headers, then choose Test auth flow to test the current form values. Testing does not save edits or results. Choose Save separately to persist configuration. The Enabled flag is saved metadata, not runtime activation; disabled flows can still be tested.

• Session cookie login manually sends the configured login request and displays extracted response values, including cookies. It does not retain a reusable session.
• Bearer token manually sends the configured token request and displays extracted values from JSON, headers, cookies, or regex matches. It does not inject tokens into monitor requests.
• API key previews configured static header values after secret substitution; no request is sent.
• Basic auth previews a configured Authorization header. Supply the Base64-encoded username:password value yourself; SiteCanary does not generate it.
• Custom headers previews configured headers without sending a request.

Request tests report the actual HTTP status and duration. Expected status is stored but not enforced by the test. Missing extracted values appear as Not found; inspect the results rather than treating a completed test as proof that authentication succeeded.

Organization members can manage and test their organization’s flows. Saved secrets are not encrypted by the application and are rendered in Edit fields; extracted credentials are visible in test results. Use disposable test credentials. HTTP monitor headers remain separately configurable on the monitor’s Edit page; auth-flow values are never copied automatically.

Turnstile sign-in protection

Deployments can optionally require Cloudflare Turnstile on login and signup while leaving authenticated application navigation unchanged.

• Enable it with TURNSTILE_ENABLED=true and configure the site key, secret key, and expected production hostname.
• The browser receives only the public site key. SiteCanary validates each single-use token, hostname, and form action with Cloudflare before checking credentials or creating an account.
• Verification failures fail closed with a retry message. CSRF protection, sessions, and normal authentication checks still apply.

HTTP redirects

Follow redirects controls whether the HTTP client follows 3xx responses. Redirects are limited to five hops within the original registrable domain, and every destination is revalidated before connection. Fail on redirects marks the check unhealthy if any redirect response is observed, even when redirects are not followed.

HTTP status codes

When a specific status code is selected, the response status must match exactly. Leaving the field empty allows any status code.

HTTP Content-Type matching

Content-Type matching compares the response header value before the first semicolon (e.g., text/html from text/html; charset=utf-8), case-insensitive.

HTTP required response headers

Each selected response header must be present and non-empty in the response.

HTTP body contains

Comma-separated values are compared as lowercased substrings against the response body. Every entry must be present.

HTTP body not contains

Comma-separated values are compared as lowercased substrings against the response body. Any match causes an alert.

HTTP response time threshold

Response time is measured as the total check duration, including DNS, connection, TLS, and HTTP processing.

HTTP security headers

SiteCanary's deployed web application emits CSP and HSTS on HTTPS responses, along with clickjacking, MIME-sniffing, referrer, and browser permissions protections.

When "Check security headers" is enabled for HTTP checks, SiteCanary validates the following headers on HTTPS responses:

• Strict-Transport-Security (HSTS) must be present and non-empty.
• Content-Security-Policy (CSP) must be present and non-empty.

Checks are skipped for non-HTTPS URLs.

HTML Performance TTFB

Time to First Byte is measured from navigation request start to response start, in milliseconds.

HTML Performance DOMContentLoaded

DOMContentLoaded is measured from navigation start to the DOMContentLoaded event end, in milliseconds.

HTML Performance Largest Contentful Paint

Largest Contentful Paint is captured from browser performance entries and reported in milliseconds.

HTML Performance Cumulative Layout Shift

CLS is the sum of layout shift scores that did not follow user input. Lower is better.

HTML Accessibility (axe-core)

HTML Accessibility checks run an axe-core scan in headless Chrome and count violations by impact (critical, serious, moderate, minor).

Thresholds are counts. If any enabled threshold is exceeded, the check is marked unhealthy.

DNS expected answers

Expected answers are compared against resolved A/AAAA results for the hostname. If any expected answer is missing, the check is marked unhealthy.

TLS expiry threshold

TLS checks alert when the earliest certificate expiry in the chain is within the configured number of days.

TCP connectivity

TCP checks alert when a TCP connection cannot be established to the configured host and port.

SSH host key alerts

SSH checks capture the server host key fingerprint (SHA256), banner, KEX algorithm, cipher, and MAC from the negotiated handshake.

When "Trust on first use" is enabled, the first successful check saves the host key fingerprint and algorithm for future comparisons.

Alerts fire when any enabled comparison changes (host key, banner, KEX, cipher, or MAC) or the host key does not match the configured fingerprint.