How-to guides

Configure priority routing and connect it to existing Airflow workflows. For a first Slack alert, use the tutorial.

How to select a priority and threshold

Add one priority tag to the DAG. P1 is highest urgency and P5 is lowest:

from datetime import datetime, timezone

from airflow import DAG

dag = DAG(
    dag_id="production-report",
    schedule="@daily",
    start_date=datetime(2025, 1, 1, tzinfo=timezone.utc),
    catchup=False,
    tags=["P2"],
)

Install the integration extra for each configured backend in the Airflow environment. Set a global threshold in airflow.cfg, then override it for individual backends:

[priority]
threshold = 3

[priority.slack]
token = YOUR_BOT_TOKEN
channel = airflow-alerts
threshold = 2

[priority.datadog]
api_key = YOUR_API_KEY
threshold = 3

This routes P1/P2 events to both backends and P3 events only to Datadog. A threshold filters only its own backend. Choose destinations in the backend reference.

How to inject configuration through environment variables

Use Airflow’s flat configuration section for deployment systems that cannot set environment-variable names containing dots:

export AIRFLOW__PRIORITY__SLACK_CHANNEL=airflow-alerts
export AIRFLOW__PRIORITY__SLACK_THRESHOLD=2

Inject AIRFLOW__PRIORITY__SLACK_TOKEN from your deployment’s secret store. An equivalent flat INI configuration is:

[priority]
slack_token = YOUR_BOT_TOKEN
slack_channel = airflow-alerts
slack_threshold = 2

Configure all processes that receive events, including the scheduler and Airflow 3 API server. Restart them after changes; configuration and clients are cached per process. See Airflow’s configuration guide for its environment-variable and secret-backend rules.

How to configure routing with airflow-config

Install the config extra alongside the backend extra:

pip install 'airflow-priority[config,slack]'

Save config.yaml at $AIRFLOW_HOME/dags/config/config.yaml:

# @package _global_
_target_: airflow_config.Configuration
_convert_: all

extensions:
  priority:
    _target_: airflow_priority.PriorityConfiguration
    slack:
      token: ${oc.env:PRIORITY_SLACK_TOKEN}
      channel: airflow-alerts
      threshold: 2
      send_running: false
      send_success: false
      update_message: false

Provide PRIORITY_SLACK_TOKEN to the scheduler and API server, then restart them. This configuration is loaded automatically by the priority plugin; it does not need a separate DAG loader. The lookup uses this location even when Airflow’s DAG folder is configured elsewhere.

Set the tag in an existing airflow-config DAG definition:

dags:
  production-report:
    schedule: "@daily"
    start_date: "2025-01-01"
    catchup: false
    tags: [P2]
    tasks:
      run:
        _target_: airflow_pydantic.BashTask
        bash_command: /opt/jobs/report

Materialize that DAG using your existing airflow-config loader. Backend configuration and DAG definitions may live in the same configuration file. Use native YAML booleans for notification flags, lists for Datadog tags, and mappings for New Relic tags. See the reference for precedence and model defaults.

How to alert on Supervisor, Nomad, and Cron failures

Apply a priority tag to the generated or parent DAG. A failed DAG run can then reach the configured priority backends:

tags: [P1]

Keep Supervisor or Nomad forward_logs: true when workload output is needed in task logs. Their failure branches and HA retrigger exhaustion report failed DAG runs. Cron conversion uses ordinary Bash tasks; preserve a failing exit status and set skip_on_exit_code: null if exit 99 must also fail.

Use task failure callbacks when you need a notification for a specific task or its process diagnostics. Priority listeners observe DAG-run state and send the DAG ID, priority, and state. They do not forward workload stdout/stderr or include task exception traces in backend messages.

How to troubleshoot missing alerts

Check these conditions in order:

  1. Confirm the installed backend extra and AirflowPriorityPlugin in airflow plugins.

  2. Inspect startup logs for backend registration and missing required options.

  3. Confirm one recognized priority tag and an inclusive backend threshold.

  4. Confirm the DAG run reached failed; a failed task alone may not establish that state.

  5. Inspect the Airflow process handling the event for Failed to send exceptions.

  6. Check the destination’s credentials, routing key or channel, and permissions.

Unconfigured optional backends log registration warnings. Diagnose the backend you intend to use. Sender errors are logged and processing continues to other eligible backends; delivery is not queued for retry by the tracker.

Airflow 3 UI/API state changes also emit DAG success/failure listener events. Use a test DAG and destination when manually changing state. See the listener documentation.