Skip to main content

Alert YAML

Along with alertings at the dashboard level and can be created via the UI, there might be more extensive alerting that you might want to develop and can be done so the an alert.yaml. When creating an alert via a YAML file, you'll see this denoted in the UI as Created through code.

Properties​

type​

[string] - Refers to the resource type and must be alert (required)

refresh​

[object] - Refresh schedule for the alert

refresh:
  cron: "* * * * *"
  #every: "24h"

(required)

  • cron - [string] - A cron expression that defines the execution schedule

  • time_zone - [string] - Time zone to interpret the schedule in (e.g., 'UTC', 'America/Los_Angeles').

  • disable - [boolean] - If true, disables the resource without deleting it.

  • ref_update - [boolean] - If true, allows the resource to run when a dependency updates.

  • run_in_dev - [boolean] - If true, allows the schedule to run in development mode.

display_name​

[string] - Display name for the alert

description​

[string] - Description for the alert

intervals​

[object] - define the interval of the alert to check

  • duration - [string] - a valid ISO8601 duration to define the interval duration

  • limit - [integer] - maximum number of intervals to check for on invocation

  • check_unclosed - [boolean] - boolean, whether unclosed intervals should be checked

watermark​

[string] - Specifies how the watermark is determined for incremental processing. Use 'trigger_time' to set it at runtime or 'inherit' to use the upstream model's watermark.

timeout​

[string] - define the timeout of the alert in seconds (optional).

data​

[oneOf] - Data source for the alert (required)

  • option 1 - [object] - Executes a raw SQL query against the project's data models.

    • sql - [string] - Raw SQL query to run against existing models in the project. (required)

    • connector - [string] - specifies the connector to use when running SQL or glob queries.

  • option 2 - [object] - Executes a SQL query that targets a defined metrics view.

    • metrics_sql - [string] - SQL query that targets a metrics view in the project (required)

  • option 3 - [object] - Calls a custom API defined in the project to compute data.

    • api - [string] - Name of a custom API defined in the project. (required)

    • args - [object] - Arguments to pass to the custom API.

  • option 4 - [object] - Uses a file-matching pattern (glob) to query data from a connector.

    • glob - [anyOf] - Defines the file path or pattern to query from the specified connector. (required)

      • option 1 - [string] - A simple file path/glob pattern as a string.

      • option 2 - [object] - An object-based configuration for specifying a file path/glob pattern with advanced options.

    • connector - [string] - Specifies the connector to use with the glob input.

  • option 5 - [object] - Uses the status of a resource as data.

    • resource_status - [object] - Based on resource status (required)

      • where_error - [boolean] - Indicates whether the condition should trigger when the resource is in an error state.

  • option 6 - [object] - Uses AI to generate insights and analysis from metrics data. Only available for reports.

    • ai - [object] - AI resolver configuration for generating automated insights (required)

      • prompt - [string] - Custom prompt to guide the AI analysis. If not provided, a default analysis prompt is used.

      • time_range - [object] - Time range for the analysis period

        • iso_duration - [string] - ISO 8601 duration (e.g., P7D for 7 days, P1M for 1 month)

        • iso_offset - [string] - ISO 8601 offset from current time (e.g., P1D to start from yesterday)

        • start - [string] - Start timestamp in ISO 8601 format

        • end - [string] - End timestamp in ISO 8601 format

        • expression - [string] - Rill time expression (e.g., 'last 7 days', 'this month')

      • comparison_time_range - [object] - Optional comparison time range for period-over-period analysis

        • iso_duration - [string] - ISO 8601 duration for comparison period

        • iso_offset - [string] - ISO 8601 offset for comparison period (e.g., P7D to compare with previous week)

        • start - [string] - Start timestamp in ISO 8601 format

        • end - [string] - End timestamp in ISO 8601 format

        • expression - [string] - Rill time expression for comparison period

      • context - [object] - Context to constrain the AI analysis

        • explore - [string] - Name of the explore dashboard to analyze

        • dimensions - [array of string] - List of dimensions to include in analysis

        • measures - [array of string] - List of measures to include in analysis

for​

[oneOf] - Specifies how user identity or attributes should be evaluated for security policy enforcement.

  • option 1 - [object] - Specifies a unique user identifier for applying security policies.

    • user_id - [string] - The unique user ID used to evaluate security policies. (required)

  • option 2 - [object] - Specifies a user's email address for applying security policies.

    • user_email - [string] - The user's email address used to evaluate security policies. (required)

  • option 3 - [object] - Specifies a set of arbitrary user attributes for applying security policies.

    • attributes - [object] - A dictionary of user attributes used to evaluate security policies. (required)

on_recover​

[boolean] - Send an alert when a previously failing alert recovers. Defaults to false.

on_fail​

[boolean] - Send an alert when a failure occurs. Defaults to true.

on_error​

[boolean] - Send an alert when an error occurs during evaluation. Defaults to false.

renotify​

[boolean] - Enable repeated notifications for unresolved alerts. Defaults to false.

renotify_after​

[string] - Defines the re-notification interval for the alert (e.g., '10m','24h'), equivalent to snooze duration in UI, defaults to 'Off'

notify​

[object] - Notification configuration for email and Slack delivery (required)

  • email - [object] - Send notifications via email.

    • recipients - [array of string] - An array of email addresses to notify. (required)

  • slack - [object] - Send notifications via Slack.

    • users - [array of string] - An array of Slack user IDs to notify.

    • channels - [array of string] - An array of Slack channel names to notify.

    • webhooks - [array of string] - An array of Slack webhook URLs to send notifications to.

annotations​

[object] - Key value pair used for annotations

Common Properties​

name​

[string] - Name is usually inferred from the filename, but can be specified manually.

refs​

[array of string] - List of resource references

dev​

[object] - Overrides any properties in development environment.

prod​

[object] - Overrides any properties in production environment.

Examples​

# Example: To send alert when data lags by more than 1 day to slack channel #rill-cloud-alerts
type: alert
display_name: Data lags by more than 1 day
# Check the alert every hour.
refresh:
    cron: 0 * * * *
# Query that returns non-empty results if the measures lag by more than 1 day.
data:
    sql: |-
        SELECT  *
        FROM
        (
          SELECT  MAX(event_time) AS max_time
          FROM rill_metrics_model
        )
        WHERE max_time < NOW() - INTERVAL '1 day'
# Send notifications in Slack.
notify:
    slack:
        channels:
            - '#rill-cloud-alerts'