Alerts

Telemetry alerts let you monitor query output and get notified by email when a metric crosses a threshold.

Use the Alert API to list, create, update, or delete these alert definitions programmatically.

Why alerting starts with one time-series line

Telemetry enables Create Alert for a line chart with time on the x-axis, one numeric metric on the y-axis, and no Group by or Split by dimension. The alert evaluator requires this result shape.

A single time-series line gives the alert a definition that a person can explain and review:

• Each point asks the same question about a successive time bucket.
• Every value has the same metric, unit, filters, and population.
• "Last N data points" maps to an ordered set of recent buckets.
• The threshold produces one state: the signal is either within the expected range or it is not.

A multi-series chart is useful for investigation, but it leaves important alert behavior undefined. Should the alert fire when any line crosses the threshold or only when every line does? Should each route, customer, region, or release have separate state and notifications? What should happen when a series disappears, a new value appears, or one threshold does not fit every group? Telemetry does not silently choose those semantics for you.

Dashboards can preserve multi-line comparisons and broad context. An alert should be a small, deterministic assertion with one owner and one response. The query behind that line can still contain joins, filters, ratios, minimum-volume guards, or other complex logic; its final result should reduce that logic to one ordered signal.

Turn a grouped chart into an alert

If a useful dashboard chart has several lines:

1. Keep the multi-series version on the dashboard for comparison and diagnosis.
2. Choose the specific condition that has an owner and response.
3. Filter to one population or aggregate the groups deliberately in SQL.
4. Return an explicit time bucket and one numeric value for each bucket.
5. Select a Line chart and remove Group by or Split by.
6. Create separate alerts when different groups need different thresholds, owners, or response procedures.

If Create Alert is not visible, first check the result shape. In Explore, use a line chart with no Split by. For a SQL result, use a line chart, select a time column for the x-axis and a numeric value for the y-axis, and set Group by to None.

How alerts work

Each alert evaluation follows the same flow:

1. Run the saved Explore or SQL query.
2. Order rows by timestamp, newest first.
3. To skip the latest row, enable Ignore the last data point.
4. Take the last N data points.
5. Compute an aggregation such as avg, sum, or p95.
6. Compare the value to your threshold.
7. Send notifications when the alert triggers or resolves.

Create an alert from explore

1. Open /team/{team}/table/{table}?tab=explore.
2. Select a Line chart, one metric, a time range, and any filters.
3. Leave Split by empty so the result is one line.
4. Click Run.
5. In the results toolbar above the chart, click Create Alert.
6. Configure condition, interval, and recipients.
7. Click Create Alert to save.

After you run an Explore query, the alert button appears on the right side of the results toolbar next to Add to Dashboard:

After creation, you will land on /team/{team}/alert/{alertSlug} where you can inspect status and event history.

Create an alert from SQL query results

1. Open a saved query that returns one time column and one numeric signal.
2. Run the query and switch to the Chart tab.
3. Select a Line chart, set the time column as the x-axis, set the numeric signal as the y-axis, and leave Group by as None.
4. Click Create Alert from the Results or Chart tab.
5. Choose aggregation and threshold logic.
6. Save and verify the alert detail page.

Alert condition fields

Interactive inline examples

/team/{team}/table/{table}?tab=explore&graphType=line&agg=p95&metric=latency_ms&time=7d

SELECT
  date_trunc('minute', timestamp_utc) AS time_bucket,
  COUNT(*) AS errors
FROM
  http_logs
WHERE
  status_code >= 500
  AND timestamp_utc >= now() - INTERVAL '2 hours'
GROUP BY
  time_bucket
ORDER BY
  time_bucket DESC;

Troubleshooting

1. No notifications: verify recipient emails are valid and alert is enabled.
2. False positives: increase Last N data points or keep Ignore last data point enabled.
3. Alert never triggers: lower threshold or confirm the selected metric column is numeric.