This is an automated email from the ASF dual-hosted git repository. kaxilnaik pushed a commit to branch v3-1-test in repository https://gitbox.apache.org/repos/asf/airflow.git
commit 00d5a974649884d8db0761cf33d758ced6ef5000 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. (cherry picked from commit dd3cfdb0373b324a544c5371d0a6014d95e13412) --- 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 ^^^^^^^^^^^^^^^^^^^^
