Skip to main content

airflow-failure-alerts

Global Apache Airflow task-failure alerting to the MAX and Telegram messengers. Installed as a pip package, it uses a cluster policy (the airflow.policy entry point) to attach an on_failure_callback to every task in every DAG - the DAGs themselves are not modified.

It works in managed environments where there is no access to $AIRFLOW_HOME/config or the plugins folder: the package is loaded from site-packages.

How it works

pyproject.toml registers the entry point:

[project.entry-points."airflow.policy"]
_ = "airflow_failure_alerts.policy"

On startup (settings.initialize -> policy plugin loading) Airflow imports airflow_failure_alerts.policy and registers its @hookimpl task_policy. During DAG parsing that policy sets on_failure_callback = notify_failure on every task (existing callbacks are preserved). On terminal task failure (after all retries are exhausted) a message is sent to MAX and Telegram.

Installation

Requires Apache Airflow 2.6+ (the airflow.policy entry point).

pip install airflow-failure-alerts

In a managed Airflow service, add airflow-failure-alerts to the cluster pip dependencies and apply the change (this restarts the components and loads the policy).

Airflow Variables

Set these in the Airflow UI -> Admin -> Variables. Each channel is optional; if a channel is not configured, alerts go only to the configured one.

Variable Description
TELEGRAM_BOT_TOKEN Telegram bot token (from @BotFather)
TELEGRAM_CHAT_ID chat/channel id (channels look like -100...)
MAX_BOT_TOKEN MAX bot token (from @MasterBot)
MAX_CHAT_ID MAX chat id
ALERTS_ENV (optional) environment label added to the message, e.g. prod

Getting a chat_id

  • Telegram: add the bot to the chat/channel, post a message, open https://api.telegram.org/bot<TOKEN>/getUpdates and read chat.id. For channels the bot must be an administrator.
  • MAX: create a bot via @MasterBot, add it to the chat; chat_id arrives in webhook events or after the first interaction in the chat.

Verification

Add a DAG with a deliberately failing task (retries=0, raise) and trigger it manually. Both messengers receive a message of the form:

Airflow task failed [prod]
DAG: my_pipeline
Task: my_task
Run: manual__2026-01-01T...
Execution date: 2026-01-01T00:00:00+00:00
Try: 1
Error: <exception text>
Log: https://airflow.../log?...

If no alert arrives, inspect the task log (the "Post task execution logs" section): notify_failure records the reason there (Variables not set, HTTP error) and never fails the task.

MAX Bot API

POST https://platform-api.max.ru/messages?chat_id=<id>, header Authorization: <token> (the raw token, no Bearer prefix), body {"text": "..."}. Text limit is 4000 characters.

Metadata

Release files for airflow-failure-alerts 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for airflow-failure-alerts 0.1.1
File Size Uploaded Provenance Actions
airflow_failure_alerts-0.1.1.tar.gz 4.4 kB Without provenance Details for airflow_failure_alerts-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for airflow-failure-alerts 0.1.1
File Interpreter ABI Platform Actions
airflow_failure_alerts-0.1.1-py3-none-any.whl Python 3 none any Details for airflow_failure_alerts-0.1.1-py3-none-any.whl

Total release size: 9.7 kB

Release files / airflow_failure_alerts-0.1.1.tar.gz

Download URL airflow_failure_alerts-0.1.1.tar.gz
Size 4.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f75d7c0f568ced2c6c9548c105e588dc6a2591b44c4a8486bee7d267a7dc5d8a
BLAKE2b-256 checksum
How to use checksums
e6e563b534d84bf62f6f5062ff8b2aaa8df952dfe9450e1095368cc68c3e5d1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.4

Release files / airflow_failure_alerts-0.1.1-py3-none-any.whl

Download URL airflow_failure_alerts-0.1.1-py3-none-any.whl
Size 5.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
aed263026f983951823b0eaa4afb9f81ce0cb69c9be1b73c2bca57a098519d49
BLAKE2b-256 checksum
How to use checksums
def808ffa499f38228adce3f636dc23644ca087dc7e3ae385390567cb5973dfa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.4

Security for airflow-failure-alerts 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page