Alerts & notifications

Okapi notifies people through rules. A rule names a trigger ("New issue occurs"), optional filters, and where to deliver. Rules live on a project's Alerts page. Rules that cover several projects live on a view's Alerts page.

Team rules and personal rules¶

Every rule has one of two scopes, and each scope has one owner, so no destination is controlled by two people's settings:

A team rule is on while at least one channel is attached to it. A personal rule is on while its Email or In-app destination is on.

Triggers¶

These triggers are for errors. A rule whose Source is Performance uses two triggers of its own for slow-query and N+1 performance issues; see Performance monitoring.

Both thresholds are inclusive. For Issue spikes with N = 100, the 100th event within the window fires the rule. For Issue affects many people with N = 100, the rule fires when the 100th distinct user is affected within the window, however many events that takes.

Okapi evaluates rules after the event is stored, outside the ingest path, so a slow destination never slows down ingest.

Snoozed and ignored issues never alert, whatever a rule's filters say. Resolved issues do: an event on a resolved issue is the regression. new_release is about the project, not one issue, so a snoozed issue cannot silence release alerts.

Filters¶

Filters narrow what a rule fires on. All filters on a rule must match. A rule with no filters matches everything its trigger fires on.

"Assignee is me" works on personal rules only. On new_release rules, only the Release filter has a value to compare; any other filter makes the rule never match.

Default rules¶

New projects start with a set of default rules, both as team rules and as personal rules for every member:

• New issue occurs, filtered to level at least error, and Resolved issue comes back start on. As personal rules they start with Email and In-app on. As team rules they get every channel marked Use for default alerts.
• Issue spikes (100 events in 60 minutes), Issue affects many people (100 people in 60 minutes), Issue hits a milestone, New release appears, and Every time issue occurs start off.

The level filter matters: Sentry SDKs send captureMessage as level info, and without the filter every new message would alert.

A member who joins later gets the personal defaults for every existing project. Projects created before default rules existed get the team defaults when an owner presses Reset defaults. Reset restores the defaults in place. Resetting your personal rules also removes the personal rules you added yourself; resetting team rules never touches team rules an owner added. Resetting team rules also resets their routing: Okapi removes every channel from the default team rules, then attaches only the channels marked Use for default alerts that cover the project to the two starter rules (New issue occurs and Resolved issue comes back). Channels you added to a default rule by hand are removed.

New personal defaults also include a weekly digest (Mondays at 09:00 in your timezone, level at least error), which starts on.

Send test¶

Send test on a rule delivers a sample alert — "ExampleError: this is a test alert from Okapi — delivery works", issue TEST-1 — to the rule's destinations, so you can check delivery without waiting for a real error. A rule with no destinations cannot be tested. In safe mode the test is refused.

Volume limits¶

Several limits keep an incident from turning into a flood. They apply in this order:

1. Per issue, by trigger. Edge triggers (new issue, regression, milestone, new release) fire once per event of their kind. Issue spikes and Issue affects many people fire at most once per window. Every time issue occurs follows its At most setting.
2. Per rule. One rule sends at most OKAPI_ALERT_RULE_MAX_PER_HOUR alerts (default 180) in a rolling hour, across all issues. Further alerts from that rule are dropped until the hour rolls off. When this happens, every member of the organization gets an in-app notification, "Alert rule rate-capped: <rule name>". It is deduplicated per rule and UTC hour while it is unread: once you read it, another can arrive for the same rule in the same hour. This notification cannot be turned off, because it reports that alerts are being lost. 0 disables the per-rule cap.
3. Per destination. A channel receives at most 300 alerts per hour, and a person receives at most 60 alert emails per hour. These caps are fixed. See Notification channels.
4. Per instance. OKAPI_EMAIL_MAX_PER_MINUTE (default 60, 0 disables) limits all outgoing email recipients per minute, as a backstop against a send loop.

Alert history¶

The History item of a project's or view's Alerts page lists what Okapi actually delivered: each delivery, its destination, and its status. Deliberately dropped deliveries show the cap that stopped them, for example dropped_channel_cap or dropped_recipient_cap, and safe-mode deliveries show suppressed_safe_mode. Other members' personal deliveries are not shown. Resolved deliveries are kept for 90 days.

The in-app inbox¶

Personal rules with In-app on deliver to the bell in the top bar and the Notifications page. In-app notifications never leave your instance, so they keep working in safe mode and without SMTP.

Three notifications have no rule and no off switch:

Email delivery¶

Email destinations need an email transport: SMTP, or Cloudflare via OKAPI_EMAIL_TRANSPORT. Without one, personal email cannot be delivered; in-app notifications and channels work normally.

The selected email transport also sends invite emails, email verification, and password resets. See Installation → Environment variables for OKAPI_EMAIL_TRANSPORT and the Cloudflare variables, and use the Compose override instructions to pass them to the app.

Next: Notification channels.