Managing alert policies with the dagster-cloud CLI#

This guide is applicable to Dagster+.

In this guide, we'll walk you through managing Dagster+ alert policies using the dagster-cloud CLI. Alert policies apply to a full deployment (ex: prod), not Branch Deployments.

Don't want to work in code? You can also define and set alert policies using the Dagster+ UI.

How it works#

Alert policies are defined in a YAML file and then, using the dagster-cloud CLI, set for a deployment. The YAML file should contain a single top-level key (alert_policies) and contain a list of alert policy objects. For example:


# alert_policies.yaml

alert_policies:
  - name: "email-alert-policy"
    description: "An alert policy to email company executives during job failure."
    tags:
      - key: "level"
        value: "critical"
    event_types:
      - "JOB_FAILURE"
    notification_service:
      email:
        email_addresses:
          - "richard.hendricks@hooli.com"
          - "nelson.bighetti@hooli.com"

Compatible event types#

Only certain event_types can be specified together when using the CLI to create alerts. For example, multiple run-based event types can be included in the same policy, but attempting to include a tick event (such as TICK_FAILURE) will result in an error.

Prerequisites#

To follow the steps in this guide, you'll need:

To install the dagster-cloud CLI. Refer to the dagster-cloud CLI reference for instructions.
Organization, Admin, or Editor permissions in Dagster+, which are required to create and manage alerts
Optional: If using an integration like Microsoft Teams or Slack as a notification service, complete the integration setup before proceeding. Refer to the Supported notification services for a complete list of integrations.

Setting policies for a deployment#

In this example, we'll configure an email alert when a job fails. This job, named important_job, has a level tag of "critical":


def important_computation():
    ...


@job(tags={"level": "critical"})
def important_job():
    important_computation()

First, define a list of alert policies in a YAML file. For example, the following policy listens for jobs with a tag of level: critical to fail:


# alert_policies.yaml

alert_policies:
  - name: "email-alert-policy"
    description: "An alert policy to email company executives during job failure."
    tags:
      - key: "level"
        value: "critical"
    event_types:
      - "JOB_FAILURE"
    notification_service:
      email:
        email_addresses:
          - "richard.hendricks@hooli.com"
          - "nelson.bighetti@hooli.com"

Next, use the following command to set the policies for the deployment:


dagster-plus deployment alert-policies sync -a /path/to/alert_policies.yaml

Viewing a deployment's policies#

To list the policies currently configured on the deployment, run: