Create an alert
Turn a stable production signal into a notification with a clear owner, threshold, and response.
An alert should answer one operational question: when does this signal require action?
A detection can label every repeated tool loop without notifying anyone. An alert decides that a single high-risk loop, a burst of failures, a metric threshold, or missing telemetry deserves attention now.
Write the response before the rule
Complete this sentence:
When this fires, who will do what, within how long?
If the answer is unclear, keep the signal on a dashboard until an operational response exists. Alert volume without ownership creates noise rather than reliability.
Start from a stable signal
Before creating an alert from a detection:
- review representative matches and non-matches;
- understand normal frequency;
- confirm the project the alert belongs to (an alert watches one project and has no environment selector);
- check whether traffic volume changes the expected count;
- give the detection a name responders will understand.
For metrics, establish the normal range and whether the response should depend on a sum, average, minimum, maximum, P95, P99, or count.
Choose the rule that matches the incident
| Rule type | Use it when | Example |
|---|---|---|
| Per event | One occurrence deserves immediate attention | A high-risk data exposure detection matches |
| Threshold | Count within a time window indicates a burst or sustained problem | Five payment-tool failures occur in 10 minutes |
| Compound | Several detection conditions together make the signal actionable | Repeated tool calls and an error response occur in the same window |
| Metric threshold | An aggregate measurement crosses an operational boundary | P95 latency rises above 8,000 ms |
| Ingestion health | Missing telemetry is the failure | A production project stops receiving traces |
Per event, Threshold, and Compound rules watch detection matches, so they are evaluated as detection results arrive for completed traces. Metric threshold and Ingestion health rules are checked on a schedule, about once a minute.
Use per-event alerts sparingly. A condition that appears often should usually use a threshold or metric rule.
Create the alert
Creating, editing, enabling, disabling, or deleting an alert requires the Project Member or Project Admin role on the project. If you are a Project Viewer, ask a project admin or an organization owner or admin to make the change.
Start a new alert. Select alerts in the sidebar, then New alert. To alert on one detection, open that detection, select its Alerts tab, and select Create alert: the wizard opens with the detection selected and Per event preselected.
Type. Choose Threshold, Per event, Metric threshold, Compound, or Ingestion health, then select Continue.
Condition. Fill in the fields for the type, described in Window and threshold. Threshold and Per event rules also offer Optional Filters.
Details. Enter a Rule name responders will recognize and choose a Severity: Critical, Warning, or Info.
Response. Choose the channels that should receive the alert. See Delivery channel.
Confirm. Review the summary, then select Create alert. The alert is enabled as soon as it is saved.
The Alert action in the Detection summary table on analytics also opens a Metric threshold alert prefilled with that detection's Detection rate. To manage alert rules outside the app, use the Public API or the neatlogs alerts CLI commands.
Configure the response policy
Scope
An alert belongs to the project selected when you create it, and its recipients are that project's members. Threshold and Per event rules watch one detection, Compound rules watch several, Metric threshold rules aggregate across the project's traces, and Ingestion health watches the whole project.
Alerts have no environment or workflow selector. To narrow a detection-based alert, narrow the detection's scope, or add Optional Filters to a Threshold or Per event rule. Each filter row compares one trace field: use cost, tokens, or latency (milliseconds) with a suffix such as _gt, _gte, _lt, _lte, or _eq (for example, key cost_gt and value 0.5), or status or framework for an exact match. A trace must match every row to count.
An alert scoped across unrelated workflows is difficult to route and interpret.
Window and threshold
The window defines how much recent evidence is evaluated. The threshold defines how much of that evidence constitutes an incident.
Short windows respond quickly but can overreact to noise. Longer windows smooth variation but delay detection.
| Rule type | Condition fields |
|---|---|
| Threshold | Detection, Threshold count, and Time window (min). Fires when the number of matches in the sliding window reaches the count. The defaults are 10 matches in 10 minutes. |
| Per event | Detection. Fires on each match outside the cooldown. |
| Compound | Under Conditions, one row per detection with an operator (at least, greater than, equals, less than, or at most) and a count, joined by AND or OR, plus a Shared time window (min). |
| Metric threshold | Metric, Aggregation (Sum, Average, Min, Max, P95, P99, or Count), Condition (an operator and a value), and a Time window in minutes, days, or months. Detection rate also asks for a Detection to track. |
| Ingestion health | One field, labeled Silence after alert (min), with a default of 30. Despite its label, it sets how long the project must go without receiving any data before the alert fires. |
The Metric options are Total cost ($), Latency, Error rate, Error count, Tokens (total), Tokens (input), Tokens (output), Trace count, Tool failure rate, and Detection rate. Latency is trace duration in milliseconds. Rates are fractions, so enter 0.05 for 5%.
Severity
Severity communicates impact and expected response:
- Critical: urgent customer, security, safety, or availability impact;
- Warning: meaningful degradation that needs timely review;
- Info: awareness or lower-urgency operational follow-up.
Severity also controls routing. Critical alerts follow each member's Critical alerts notification preference and are delivered even during quiet hours. Warning and Info alerts follow Non-critical alerts and wait until a member's quiet hours end.
Severity is not classifier confidence or match count.
Cooldown or silence period
Cooldown prevents one continuing incident from sending the same notification repeatedly. Choose a duration long enough to reduce duplicates but short enough to expose a new incident.
Threshold and Metric threshold rules offer a Cooldown (min) of 5, 15, 30, or 60 minutes. Per event rules accept any number of minutes. Compound and Ingestion health rules have no cooldown field and use 15 minutes.
Matches during a cooldown are not sent individually. The alert's page counts them as Repeats bundled, and when the cooldown ends Neatlogs sends one follow-up if the condition still holds.
Delivery channel
The Response step lists four channels:
- In-app: always on. Project members see the alert in the app.
- Email: sent to project members.
- Slack: requires Slack to be connected under Settings → Organization → Integrations. Choose a channel in Slack Channel Override to post once to that channel, and add the Neatlogs app to it. Without a channel, Neatlogs sends a direct message to each member who turned on Slack for the alert's severity and Receive Slack direct messages.
- Webhooks: choose one webhook that subscribes to the alert's event, or Do not send to a webhook. A project admin adds webhooks under Settings → Project → Webhooks.
Email and Slack start from each member's own preferences under Settings → Account → Notifications. Turning a channel off on the alert stops it for everyone; turning it on does not override a member who turned that channel off. There is no Discord, Microsoft Teams, or PagerDuty destination; use a webhook to reach other systems.
Route the notification to people who can perform the expected response.
Example: alert on repeated payment failures
Signal: payment_tool_error detection
Rule: Threshold
Threshold count: 5
Time window: 10 minutes
Severity: Critical
Cooldown: 30 minutes
Delivery: Slack (channel override #checkout-operations), Email
Response: inspect affected traces, confirm provider status,
and open or update the checkout incident.This alert groups a burst into one operational signal rather than notifying on every failed tool call.
Test the complete path
Testing the destination alone is not enough, but it is the first check. Open the alert from the Alerts tab on alerts, select Configuration, and under Test delivery select Send test next to In-app, Email, or Slack channel.
A test uses the saved rule, is marked as a test, and does not fire the alert or start its cooldown. The Email and Slack channel tests are available only when that channel is on for the alert, and the Slack test needs a saved channel. Webhooks cannot be tested from this page. Sending a test requires the Project Member or Project Admin role.
Then verify:
- the source detection or metric produces the expected value;
- the alert evaluates in the intended project and window;
- the threshold and operator behave correctly;
- cooldown suppresses duplicate notifications as intended;
- the selected channel receives the message;
- the message includes enough project and evidence context;
- the responder can open the linked object.
Use a safe known condition to trigger a real firing, then confirm it in alert history. The History tab on alerts lists every firing with Fired at, Severity, Alert, Type, Source, Condition, and Matches, and each alert's Fire history tab shows its own. Open a firing to see the triggering traces and the delivery result for each channel, including why a channel was skipped, such as quiet hours or the Neatlogs app missing from the Slack channel.
Diagnose a noisy alert
| Symptom | Likely adjustment |
|---|---|
| Too many notifications from one incident | Increase cooldown or use a threshold |
| Normal traffic bursts trigger it | Adjust window or threshold, or use a rate metric such as Error rate or Detection rate |
| Unrelated workflows are mixed | Narrow the detection's scope or add Optional Filters |
| Notification has no clear response | Rewrite ownership and severity before tuning volume |
| Compound rule rarely fires | Check each underlying detection, its operator and count, and the AND or OR choice |
| Ingestion alert fires during expected quiet periods | Raise Silence after alert (min) above the longest normal gap in traffic |
Do not fix noise only by muting the Slack channel or turning off a route. Improve the rule, or disable or delete the alert when no response is required.
Frequently asked questions
Why did an alert not fire?
Check that the alert is Enabled, then check its project, source detection or metric, window, threshold, and cooldown. If it fired but nobody was notified, open the firing from History to see each channel's delivery result, and check the recipient's preferences in Settings → Account → Notifications. An Ingestion health alert never fires for a project that has not yet received any data.
Can one alert watch several detections?
Yes. Use a Compound rule: give each detection an operator and a count, and join the conditions with AND or OR over one shared window.
Can an alert detect missing telemetry?
Yes. Use Ingestion health and set Silence after alert (min) longer than the project's normal gaps in traffic.
Can I mute or snooze an alert?
No. Open the alert, select More actions, then Disable to stop it, and Enable to turn it back on. You can also use the switch on the alert's card.
Do incidents need an alert rule?
No. New incidents notify project members according to their Incident alerts preference. See Detections, incidents, and alerts.
Does deleting an alert delete its detection?
No. Alert rules and detection definitions are separate.
Should every critical detection use per-event delivery?
No. Choose per event only when every occurrence requires action. Severity and notification frequency solve different problems.