Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Concepts

This page lists what Shriek does today. Where something is missing or partial, it says “Not yet”.

Tenants

A tenant is the boundary around your data. Every /v1/shriek/ call acts on the tenant your credential belongs to, and no call can read or change another tenant’s data. A tenant name is lowercase letters, digits and -, starting with a letter or digit, and appears in your public status page’s URL.

Sources and services

A source names one thing you monitor:

{"service": "billing", "component": "nightly-export"}
  • service is a row on the board. Group related sources under one service.
  • component is the part within it.
  • Both are trimmed and must be 1 to 256 bytes. Case matters: Billing and billing are different services.

Alerts and the feed

An alert is one event: a source, a severity (info, warn or critical), a title, an optional detail, and the time Shriek recorded it (at).

  • Append-only. No endpoint edits or deletes an alert.
  • Recorded first. Shriek stores the alert before it tries to notify anyone, so an alert that reached Shriek stays in the feed even if a notification fails.
  • Alerts don’t colour the board. An alert you post with POST /v1/shriek/alert is a record of something that happened. To turn a row red until a person fixes it, open an incident.
  • Read it two ways: the whole feed (GET /v1/shriek/alerts, optionally ?since=<unix seconds>), or one service’s thread (GET /v1/shriek/alerts/{service}). Both list oldest first; alerts recorded in the same second come in no fixed order.

Shriek adds alerts of its own to your feed: “no signal” and “recovered” from your dead-man’s switches, “resolved” when you resolve an incident, and alerts about phone delivery (see Phone notifications).

Dead-man’s switches

Registering a source with POST /v1/shriek/expectations says “expect a heartbeat from this source at least every period_secs seconds”.

  • Deadline. A source’s deadline is its last heartbeat plus period_secs. Before the first heartbeat, it is since plus period_secs; since defaults to the time you register.
  • Checked every minute. Shriek checks every source once a minute, so a missed deadline is noticed within about a minute. period_secs must be at least 60.
  • Fire once. When a source passes its deadline, Shriek records one critical alert titled “no signal” and marks the source firing. It records nothing more while the source stays silent.
  • Recover once. The first check after a new heartbeat records one info alert titled “recovered” and marks the source ok. The heartbeat itself doesn’t turn the row green; the next check does.
  • Heartbeats need a registered source. A heartbeat for a source that isn’t registered returns 404, so a typo can’t look like a healthy source.
  • Registering again with new values changes the period and since, and keeps the last heartbeat and the current status.
  • Retiring. DELETE /v1/shriek/expectations with the source removes it from the board and stops the checks. The alerts it produced stay in the feed. A retired source isn’t registered: its heartbeats, and retiring it again, return 404.
  • Registering a retired source brings it back as if new: no last heartbeat, status ok, and its deadline counted from the new since.

Incidents

An incident is a problem you declare and later resolve.

  • Opening (POST /v1/shriek/incidents) records an alert in the feed that carries "incident": {"id": ..., "event": "opened"}, and turns the source’s service red on the board until it is resolved. This happens whatever the incident’s severity.
  • Its id. With a dedup_key, the id is {service}/{component}#{dedup_key}. Without one, it is a random UUID. Either way the response carries it.
  • Opening twice. Opening an incident whose id is already open returns the open incident, records nothing and notifies nobody. With a dedup_key, that makes opening safe to retry. Once resolved, the same dedup_key opens a new incident.
  • Resolving (POST /v1/shriek/incidents/resolve with the id) records an info alert titled “resolved” with "event": "resolved", and returns how long the incident was open. Resolving an id that isn’t open returns 404.

The board

GET /v1/shriek/board returns one row per service, sorted by name:

  • health is red if any of the service’s sources is firing or has an open incident, and green otherwise.
  • firing lists those sources.

A service appears once it has a registered source or an open incident. Posting an alert does not add a row.

Phone notifications

Every critical alert is also sent as a push notification to each phone registered to your tenant through the Shriek Android app. That includes a critical alert you post, a “no signal” alert, and the opening of a critical incident. info and warn alerts never notify.

  • The notification’s title is {service}: {title}, and its text is the start of detail, up to 240 bytes. It also carries the service, component, severity and time.
  • Delivery is best-effort. The feed is the record: a phone can be off or out of signal.
  • Each notification carries a receipt id. When the app reports that the notification was shown, Shriek records an info alert titled “page received” for that source. If no report arrives within 10 minutes of sending, Shriek records a warn alert titled “page not received” and opens a warn incident on the source shriek/push. The next “page received” resolves it.

The public status page

You decide what the public can see. Nothing is public until you publish it.

  • Components. POST /v1/shriek/public/components maps one of your registered sources to a public label such as “Payments”. Posting the same source again replaces its label. DELETE /v1/shriek/public/components takes a component off the board; posting it again puts it back.
  • Only registered sources. A component is green because its source is reporting, so the source must be a registered expectation, the same check a heartbeat gets: publishing any other source returns 404. Retiring a source also takes its component off the board; register and publish it again to bring it back. A source that only receives incidents or CloudWatch alarms has no registration, so it can’t be published yet.
  • What is shown. For each service with a published component: the service name, each component’s label, and green or red. A component is red while its source is firing or has an open incident. Component names, alert titles and details never appear.
  • Updates. POST /v1/shriek/public/updates publishes a message you write, with a service and a severity. Updates are never derived from alerts.
  • Where. https://shriek.dev/public/{tenant} is a ready-made page; the same data is JSON at /public/{tenant}/board and /public/{tenant}/{service}/updates. These need no credential and are cached at the edge for about 30 seconds. The page shows the 10 most recent updates for services that have a published component.
  • An unknown tenant returns an empty board, the same as a tenant that has published nothing.
curl -fsS https://shriek.dev/public/acme/board

Not yet:

  • Updates can’t be edited or removed.