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)

display_name​

[string] - Refers to the display name for the alert

refresh​

[object] - Specifies the refresh schedule that Rill should follow to re-ingest and update the underlying data (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.

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] - Specifies one of the options to retrieve or compute the data used by 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.

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] - Defines how and where to send notifications. At least one method (email or Slack) is required. (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 IDs 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 metrics 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'