trellum
Docs / Portal guide / Alerts

Alerts

Applies to: latest

You rarely know what to alert on until you need to be alerted. A threshold written in advance is a guess; the number that matters this week was not the one anyone thought of last month. So an alert here is not a threshold. It is a report, plain-language instructions and a cadence. Each time the rule runs, the assistant looks at the report's data and decides whether the requested condition is met, not met or unknown. Notification policy and cooldown then decide whether a met condition is eligible for mail.

Open Alerts under Studio work in the console sidebar. Studio developers and admins create and edit them; viewers see the same rules and their run logs, read-only. Anyone who can see the studio can be a recipient.

Alerts need the AI assistant to be configured for the organization — the evaluation is an assistant turn. Organization admins choose the shared provider and model for chats and alert evaluations under Organization settings → AI settings.

The two meet in both directions: tell the assistant "watch this for me" in a conversation and it proposes the rule for approval, and every alert email carries an Open in the assistant link that opens a conversation seeded from that evaluation — see Actions and approval.

Writing instructions

Instructions are a few sentences to a colleague who can read the report and query its data. Say what to watch and when to speak up; the assistant works out the numbers. Some that work well:

Ask Instructions
An outage Tell me if DAU or sessions drop sharply in any region.
A launch We launched Neon Racer on 2026-06-29; tell me whether it moved revenue and DAU.
A promotion The weekend coin sale ran 2026-08-23 to 27; tell me if IAP revenue rose and whether the refund rate rose with it.
A threshold in words Alert me if D1 retention is below its four-week average for three days running.
Anything off (leave blank) — the assistant reads it as "tell me if anything looks off"

The assistant judges the requested condition. Repeated conditions remain Met, even when delivery is suppressed. Ordinary seasonality, records on an existing trend and gradual growth alone do not satisfy blank instructions. If it gets a decision wrong, the fix is usually one more sentence — "compare with the same weekday last week", "only the EU region", "good news counts too".

Triggers

  • After every build (the default). A report's data only changes when it is rebuilt, so this is where an evaluation belongs: right after a successful build, once per build. A build that failed is not evaluated — build failure notices already cover that.
  • On a schedule. Hourly, daily, weekdays, weekly or monthly at a time and timezone you pick — for "every Monday morning, tell me whether…".

Recipients

The same picker as a delivery: people by name, the studio's admins or developers, everyone in the studio, or an organization permission group. Roles and groups are resolved when the alert fires, so a joiner starts hearing from it and a leaver stops. Whoever is picked, only people who can currently see the studio are mailed.

Cooldown

Cooldown is the minimum time since the last transport-accepted delivery (24 hours by default). Evaluations continue during cooldown and consume assistant budget, so recovery can be observed. Recovery never erases the delivery timestamp. The form and run log show the next eligible time.

The default policy repeats while the condition is met, at the next eligible evaluation after cooldown. Once per condition episode sends once, then waits for recovery. Initial Unknown → Met starts an episode. A condition first met during cooldown stays pending: the next eligible evaluation sends only if it is still met. Recovery cancels pending delivery; Unknown neither clears nor confirms it.

Zero cooldown removes the time gate. Duplicate triggers for the same rule revision and build or schedule slot still share one evaluation/delivery claim. Predicate, report or interpretation-timezone edits reset the baseline to Unknown, preserving cooldown; recipient and cadence edits retain episodes.

Specify the window, scope and currency in instructions. Rolling last 60 minutes differs from the last completed clock hour; a 48-hour net drain differs from any draining hour in those 48 hours. Strict >1000 excludes exactly 1000. The run stores its interpreted window, timezone, dataset scope, freshness and revision with evidence. Missing or incomplete evidence means Unknown.

The run log

Every evaluation is recorded under the rule, newest first: the decision, the title and message the assistant wrote, the figures it cited, what it cost, who was mailed, and any error. A quiet run is as informative as an alert — its message says why it stayed quiet ("revenue moved within its weekly range; the 12 % Sunday dip matches the last four Sundays"). That is the tuning loop: if a quiet run should have alerted, or an alert should have stayed quiet, the message tells you which sentence to add.

Other things a run can say:

  • Not evaluated — the report's last build did not succeed.
  • Met / Not met / Unknown — condition truth; Unknown means insufficient evidence.
  • OK — execution completed; it does not mean healthy or delivered.
  • Suppressed — cooldown, an already-notified episode or an obsolete evaluation.
  • Skipped: budget — the owner's assistant budget is spent (see below).
  • Error — with the reason; a rule with no owner requires billing-owner repair. The ordinary editor preserves this owner and cannot reassign it.

Transport acceptance does not confirm inbox receipt. SMTP cannot guarantee exactly-once delivery. Uncertain acceptance or an interrupted delivery claim shows Delivery outcome uncertain / review required, with its run link. Automatic delivery stays held across recovery and recurrence. Check the provider and evaluation outcome before using Mark as notified (starts cooldown at review time) or Confirm nothing was accepted (allows a future eligible evaluation to send, risking a duplicate if transport acceptance actually occurred). Both actions require developer access, are audited, send no mail and preserve the original transport evidence.

Test now

Test now evaluates the rule immediately, with delivery switched off: the decision, message and evidence land in the run log marked as a test, nobody is emailed, and the cooldown is not touched — it runs even while the rule is in cooldown, because tuning instructions is what it is for. Use it after writing or changing a rule, before waiting for the next build. The test also shows a read-only policy simulation; it never claims a production delivery or changes a live episode. A simulation is not a delivery result. On the create and edit forms, Test draft evaluates the current unsaved fields in place. It does not save the rule, send mail or send a budget warning. The requesting developer's assistant budget pays for that test; preview runs use isolated history. Saving a rule keeps its existing creator and live evaluations remain billed to that creator. When testing an existing rule, the preview may add an isolated test run and updates only that rule's last-test timestamp.

What it costs, and who pays

An evaluation has a small cap on how many queries it may run; the run log records its actual cost. Live evaluations are billed to the assistant budget of the person who created the rule, the same per-user budget the assistant panel uses. Draft tests are billed to the developer who requested them. If a live evaluation finds the creator's budget exhausted, the run is recorded as Skipped: budget, and the owner receives a budget warning when delivery is not paused. The rule resumes on its own when the budget allows. Draft tests send no budget warning. A rule without an owner cannot be evaluated live; it needs billing-owner repair, which ordinary edits cannot perform.