This is an automated email from the ASF dual-hosted git repository.
ferruzzi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new dd3cfdb0373 Update templating support in Deadline Alert docs (#55429)
dd3cfdb0373 is described below
commit dd3cfdb0373b324a544c5371d0a6014d95e13412
Author: Ramit Kataria <[email protected]>
AuthorDate: Wed Sep 10 09:11:34 2025 -0700
Update templating support in Deadline Alert docs (#55429)
There were some recent changes in templating/context for Deadline Alert
callbacks. This updates the docs to reflect those changes.
---
airflow-core/docs/core-concepts/dags.rst | 4 +--
airflow-core/docs/howto/deadline-alerts.rst | 39 +++++++++++++++++++++--------
2 files changed, 31 insertions(+), 12 deletions(-)
diff --git a/airflow-core/docs/core-concepts/dags.rst
b/airflow-core/docs/core-concepts/dags.rst
index 04551838bed..101977b3aa2 100644
--- a/airflow-core/docs/core-concepts/dags.rst
+++ b/airflow-core/docs/core-concepts/dags.rst
@@ -857,8 +857,8 @@ Here's a simple example using the existing email Notifier:
interval=timedelta(minutes=30),
callback=SmtpNotifier(
to="[email protected]",
- subject="[Alert] Dag {{ dag.dag_id }} exceeded time threshold",
- html_content="The Dag has been running for more than 30
minutes since being queued.",
+ subject="🚨 Dag {{ dag_run.dag_id }} missed deadline at {{
deadline.deadline_time }}",
+ html_content="The Dag Run {{ dag_run.dag_run_id }} has been
running for more than 30 minutes since being queued.",
),
),
):
diff --git a/airflow-core/docs/howto/deadline-alerts.rst
b/airflow-core/docs/howto/deadline-alerts.rst
index 19b4ea58e78..edfcc3b2e77 100644
--- a/airflow-core/docs/howto/deadline-alerts.rst
+++ b/airflow-core/docs/howto/deadline-alerts.rst
@@ -64,7 +64,9 @@ Below is an example Dag implementation. If the Dag has not
finished 15 minutes a
interval=timedelta(minutes=15),
callback=AsyncCallback(
SlackWebhookNotifier,
- kwargs={"text": "Dag 'slack_deadline_alert' still running
after 30 minutes."},
+ kwargs={
+ "text": "🚨 Dag {{ dag_run.dag_id }} missed deadline at {{
deadline.deadline_time }}. DagRun: {{ dag_run }}"
+ },
),
),
):
@@ -108,7 +110,9 @@ Here's an example using a fixed datetime:
interval=timedelta(minutes=-30), # Alert 30 minutes before the
reference.
callback=AsyncCallback(
SlackWebhookNotifier,
- kwargs={"text": "Dag 'slack_deadline_alert' still running
after 30 minutes."},
+ kwargs={
+ "text": "🚨 Dag {{ dag_run.dag_id }} missed deadline at {{
deadline.deadline_time }}. DagRun: {{ dag_run }}"
+ },
),
),
):
@@ -128,9 +132,10 @@ The timeline for this example would look like this:
Using Callbacks
---------------
-When a deadline is exceeded, the callback is executed. You can use an existing
:doc:`Notifier </howto/notifications>`
-or create a custom callback function. A callback must be an
:class:`~airflow.sdk.definitions.deadline.AsyncCallback`,
-with support coming soon for
:class:`~airflow.sdk.definitions.deadline.SyncCallback`.
+When a deadline is exceeded, the callback's callable is executed with the
specified kwargs. You can use an
+existing :doc:`Notifier </howto/notifications>` or create a custom callable.
A callback must be an
+:class:`~airflow.sdk.definitions.deadline.AsyncCallback`, with support coming
soon for
+:class:`~airflow.sdk.definitions.deadline.SyncCallback`.
Using Built-in Notifiers
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -146,7 +151,9 @@ Here's an example using the Slack Notifier if the Dag run
has not finished withi
interval=timedelta(minutes=30),
callback=AsyncCallback(
SlackWebhookNotifier,
- kwargs={"text": "Dag 'slack_deadline_alert' still running
after 30 minutes."},
+ kwargs={
+ "text": "🚨 Dag {{ dag_run.dag_id }} missed deadline at {{
deadline.deadline_time }}. DagRun: {{ dag_run }}"
+ },
),
),
):
@@ -155,7 +162,7 @@ Here's an example using the Slack Notifier if the Dag run
has not finished withi
Creating Custom Callbacks
^^^^^^^^^^^^^^^^^^^^^^^^^
-You can create custom callbacks for more complex handling. If ``kwargs`` are
specified in the ``Callback``,
+You can create custom callables for more complex handling. If ``kwargs`` are
specified in the ``Callback``,
they are passed to the callback function. **Asynchronous callbacks** must be
defined somewhere in the
Triggerer's system path.
@@ -163,7 +170,8 @@ Triggerer's system path.
Regarding Async Custom Deadline callbacks:
* Async callbacks are executed by the Triggerer, so users must ensure they
are importable by the Triggerer.
- * One easy way to do this is to place the callback as a top-level method
in a new file in the plugins folder.
+ * One easy way to do this is to place the callable as a top-level method
in a new file in the plugins folder.
+ Nested callables are not currently supported.
* The Triggerer will need to be restarted when a callback is added or
changed in order to reload the file.
@@ -175,7 +183,9 @@ A **custom asynchronous callback** might look like this:
async def custom_async_callback(**kwargs):
"""Handle deadline violation with custom logic."""
- print(f"Deadline exceeded for Dag {kwargs.get("dag_id")}!")
+ context = kwargs.get("context", {})
+ print(f"Deadline exceeded for Dag {context.get("dag_run",
{}).get("dag_id")}!")
+ print(f"Context: {context}")
print(f"Alert type: {kwargs.get("alert_type")}")
# Additional custom handling here
@@ -199,12 +209,21 @@ A **custom asynchronous callback** might look like this:
interval=timedelta(minutes=15),
callback=AsyncCallback(
custom_async_callback,
- kwargs={"alert_type": "time_exceeded", "dag_id":
"custom_deadline_alert"},
+ kwargs={"alert_type": "time_exceeded"},
),
),
):
EmptyOperator(task_id="example_task")
+Templating and Context
+^^^^^^^^^^^^^^^^^^^^^^
+
+Currently, a relatively simple version of the Airflow context is passed to
callables and Airflow does not run
+:ref:`concepts:jinja-templating` on the kwargs. However, ``Notifier``s already
run templating with the
+provided context as part of their execution. This means that templating can be
used when using a ``Notifier``
+as long as the variables being templated are included in the simplified
context. This currently includes the
+ID and the calculated deadline time of the Deadline Alert as well as the data
included in the ``GET`` REST API
+response for Dag Run. Support for more comprehensive context and templating
will be added in future versions.
Deadline Calculation
^^^^^^^^^^^^^^^^^^^^
