pierrejeambrun commented on code in PR #54677:
URL: https://github.com/apache/airflow/pull/54677#discussion_r2348334805
##########
airflow-core/docs/howto/customize-ui.rst:
##########
@@ -81,19 +111,65 @@ or announcing changes to end users. The following example
shows how to add alert
UIAlert(text="Critical error detected!", category="error"),
]
- See :ref:`Configuring local settings
<set-config:configuring-local-settings>` for details on how to
- configure local settings.
+.. image:: ../img/ui-alert-message.png
-2. Restart Airflow Webserver, and you should now see:
+Markdown Content in Alerts
+--------------------------
-.. image:: ../img/ui-alert-message.png
+Markdown can be included in alert messages for richer formatting. In the
following example, we show an alert
+message of heading 2 with a link included:
-Alert messages also support Markdown. In the following example, we show an
alert message of heading 2 with a link included.
+.. code-block:: python
- .. code-block:: python
+ from airflow.www.utils import UIAlert
- DASHBOARD_UIALERTS = [
- UIAlert(text="## Visit
[airflow.apache.org](https://airflow.apache.org)", category="info"),
- ]
+ DASHBOARD_UIALERTS = [
+ UIAlert(text="## Visit
[airflow.apache.org](https://airflow.apache.org)", category="info"),
+ ]
.. image:: ../img/ui-alert-message-markdown.png
+
+Dynamic Dashboard Alerts
+------------------------
+
+Dashboard alerts support dynamic content that updates each time the dashboard
page is refreshed. This allows for real-time
+status updates without requiring webserver restarts. Dynamic alerts must be
defined as an instance of an iterable object.
+The recommended approach is to create a class that subclasses ``list`` and
implements a custom ``__iter__`` method that
+yields fresh alerts each time Airflow iterates over the alerts.
+
+.. note::
+ When implementing dynamic alerts it is important to keep alert generation
logic lightweight to avoid
+ impacting dashboard load times. Consider caching results for expensive
operations and handle exceptions
+ gracefully to prevent alert generation from breaking the UI.
+
+Dynamic alerts are particularly useful for:
+
+- **Real-time notifications**: Display current status updates or announcements
+- **Deployment notifications**: Show current deployment status, build
progress, or GitOps state
+- **Temporary maintenance alerts**: Provide time-sensitive information about
ongoing maintenance or issues
+- **Environment-specific warnings**: Display different alerts based on current
environment conditions
+- **External service status**: Show the availability of dependent services or
APIs
+
+Creating Dynamic Alerts
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To create dynamic alerts, define ``DASHBOARD_UIALERTS`` as an instance of a
class that subclasses ``list`` and implements the ``__iter__`` method:
+
+.. code-block:: python
+
+ import random
+ from airflow.www.utils import UIAlert
+
+
+ class DynamicAlerts(list):
+ def __iter__(self):
+ # This method is called each time Airflow iterates over
DASHBOARD_UIALERTS
+ # Example: Flip a coin
+ if random.choice([True, False]):
+ yield UIAlert("Heads!", category="info")
+ else:
+ yield UIAlert("Tails!", category="warning")
Review Comment:
This example shows that on every `get_configs` calls code sample is run and
the response will keep changing (dynamic aspect of alerts). I don't think we
need 100 lines of code to demonstrate all use cases.
Users are free to implement `__iter__` with their own logic, replacing the
random generation by an http call for instance.
This code sample + the documentation on how that logic should be kept
`lightweight` for the reasons mentioned are enough IMO, I don't want to
complicate the doc by adding extra lines of codes unrelated to airflow
(fetching external resources, converting an http response into a generator,
etc...)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
