BasPH commented on code in PR #28450: URL: https://github.com/apache/airflow/pull/28450#discussion_r1052014084
########## docs/apache-airflow/administration-and-deployment/listeners.rst: ########## @@ -18,43 +18,59 @@ Listeners ========= -Airflow gives you an option to be notified of events happening in Airflow -by writing listeners. Listeners are powered by `pluggy <https://pluggy.readthedocs.io/en/stable/>`__ +You can write listeners to enable Airflow to notify you when events happen. +`Pluggy <https://pluggy.readthedocs.io/en/stable/>`__ powers these listeners. -Right now Airflow exposes few types of events. +Airflow supports notifications for the following events: -Lifecycle events -^^^^^^^^^^^^^^^^ -Those events - ``on_starting`` and ``before_stopping`` allow you to react to -lifecycle to an Airflow ``Job``, like ``SchedulerJob`` or ``BackfillJob``. +Lifecycle Events +---------------- -TaskInstance state change events -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Those events - ``on_task_instance_running``, ``on_task_instance_success`` and ``on_task_instance_failed`` -once ``TaskInstance`` state changes to one of the respective states. This generally happens on ``LocalTaskJob``. +- ``on_starting`` +- ``before_stopping`` -DagRun state change events -^^^^^^^^^^^^^^^^^^^^^^^^^^ -Those events - ``on_dag_run_running``, ``on_dag_run_success`` and ``on_dag_run_failed`` -once ``DagRun`` state changes to one of the respective states. This generally happens on ``SchedulerJob`` or ``BackfillJob``. +Lifecycle events allow you to react to start and stop events for an Airflow ``Job``, like ``SchedulerJob`` or ``BackfillJob``. + +TaskInstance State Change Events +-------------------------------- + +- ``on_task_instance_running`` +- ``on_task_instance_success`` +- ``on_task_instance_failed`` + +TaskInstance state change events occur when a ``TaskInstance`` changes state. +You can use these events to react to ``LocalTaskJob`` state changes. + +DagRun State Change Events +-------------------------- + +- ``on_dag_run_running`` +- ``on_dag_run_success`` +- ``on_dag_run_failed`` + +DagRun state change events occur when a ``DagRun`` changes state. +You can use these events to react to ``SchedulerJob`` or ``BackfillJob`` state changes. Usage -===== +----- + +To create a listener: -To create a listener you will need to derive the import -``airflow.listeners.hookimpl`` and implement the ``hookimpls`` for -events you want to be notified at. +- import ``airflow.listeners.hookimpl`` +- implement the ``hookimpls`` for events that you'd like to generate notifications -Their specification is defined as ``hookspec`` in ``airflow/listeners/spec`` directory. -Your implementation needs to accept the same named parameters as defined in hookspec, or Pluggy will complain about your plugin. -On the other hand, you don't need to implement every method - it's perfectly fine to have a listener that implements just one method, or any subset of methods. +Airflow defines the specification as `hookspec <https://github.com/apache/airflow/tree/main/airflow/listeners/spec>`__. +Your implementation must accept the same named parameters as defined in hookspec. +If you don't use the same parameters as hookspec, Pluggy throws an error when you try to use your plugin. +But you don't need to implement every method. +Many listeners only implement one method, or a subset of methods. -To include listener in your Airflow installation, include it as a part of an :doc:`Airflow Plugin </authoring-and-scheduling/plugins>` +To include the listener in your Airflow installation, include it as a part of an :doc:`Airflow Plugin </authoring-and-scheduling/plugins>` -Listener API is meant to be called across all dags, and all operators - in contrast to methods like -``on_success_callback``, ``pre_execute`` and related family which are meant to provide callbacks -for particular dag authors, or operator creators. There is no possibility to listen on events generated -by particular dag. +Listener API is meant to be called across all DAGs and all operators. +You can't listen to events generated by specific DAGs. +For that behavior, try methods like ``on_success_callback`` and ``pre_execute``. +These provide callbacks for particular DAG authors or operator creators. Review Comment: Same comment, would write as one paragraph. ########## docs/apache-airflow/administration-and-deployment/listeners.rst: ########## @@ -18,43 +18,59 @@ Listeners ========= -Airflow gives you an option to be notified of events happening in Airflow -by writing listeners. Listeners are powered by `pluggy <https://pluggy.readthedocs.io/en/stable/>`__ +You can write listeners to enable Airflow to notify you when events happen. +`Pluggy <https://pluggy.readthedocs.io/en/stable/>`__ powers these listeners. -Right now Airflow exposes few types of events. +Airflow supports notifications for the following events: -Lifecycle events -^^^^^^^^^^^^^^^^ -Those events - ``on_starting`` and ``before_stopping`` allow you to react to -lifecycle to an Airflow ``Job``, like ``SchedulerJob`` or ``BackfillJob``. +Lifecycle Events +---------------- -TaskInstance state change events -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Those events - ``on_task_instance_running``, ``on_task_instance_success`` and ``on_task_instance_failed`` -once ``TaskInstance`` state changes to one of the respective states. This generally happens on ``LocalTaskJob``. +- ``on_starting`` +- ``before_stopping`` -DagRun state change events -^^^^^^^^^^^^^^^^^^^^^^^^^^ -Those events - ``on_dag_run_running``, ``on_dag_run_success`` and ``on_dag_run_failed`` -once ``DagRun`` state changes to one of the respective states. This generally happens on ``SchedulerJob`` or ``BackfillJob``. +Lifecycle events allow you to react to start and stop events for an Airflow ``Job``, like ``SchedulerJob`` or ``BackfillJob``. + +TaskInstance State Change Events +-------------------------------- + +- ``on_task_instance_running`` +- ``on_task_instance_success`` +- ``on_task_instance_failed`` + +TaskInstance state change events occur when a ``TaskInstance`` changes state. +You can use these events to react to ``LocalTaskJob`` state changes. + +DagRun State Change Events +-------------------------- + +- ``on_dag_run_running`` +- ``on_dag_run_success`` +- ``on_dag_run_failed`` + +DagRun state change events occur when a ``DagRun`` changes state. +You can use these events to react to ``SchedulerJob`` or ``BackfillJob`` state changes. Review Comment: Not 100% related to the spirit of this PR, but I believe these events don't actually exist in Airflow. I can't find any reference to the mentioned events in the source code. ########## docs/apache-airflow/administration-and-deployment/listeners.rst: ########## @@ -18,43 +18,59 @@ Listeners ========= -Airflow gives you an option to be notified of events happening in Airflow -by writing listeners. Listeners are powered by `pluggy <https://pluggy.readthedocs.io/en/stable/>`__ +You can write listeners to enable Airflow to notify you when events happen. +`Pluggy <https://pluggy.readthedocs.io/en/stable/>`__ powers these listeners. -Right now Airflow exposes few types of events. +Airflow supports notifications for the following events: -Lifecycle events -^^^^^^^^^^^^^^^^ -Those events - ``on_starting`` and ``before_stopping`` allow you to react to -lifecycle to an Airflow ``Job``, like ``SchedulerJob`` or ``BackfillJob``. +Lifecycle Events +---------------- -TaskInstance state change events -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Those events - ``on_task_instance_running``, ``on_task_instance_success`` and ``on_task_instance_failed`` -once ``TaskInstance`` state changes to one of the respective states. This generally happens on ``LocalTaskJob``. +- ``on_starting`` +- ``before_stopping`` -DagRun state change events -^^^^^^^^^^^^^^^^^^^^^^^^^^ -Those events - ``on_dag_run_running``, ``on_dag_run_success`` and ``on_dag_run_failed`` -once ``DagRun`` state changes to one of the respective states. This generally happens on ``SchedulerJob`` or ``BackfillJob``. +Lifecycle events allow you to react to start and stop events for an Airflow ``Job``, like ``SchedulerJob`` or ``BackfillJob``. + +TaskInstance State Change Events +-------------------------------- + +- ``on_task_instance_running`` +- ``on_task_instance_success`` +- ``on_task_instance_failed`` + +TaskInstance state change events occur when a ``TaskInstance`` changes state. +You can use these events to react to ``LocalTaskJob`` state changes. + +DagRun State Change Events +-------------------------- + +- ``on_dag_run_running`` +- ``on_dag_run_success`` +- ``on_dag_run_failed`` + +DagRun state change events occur when a ``DagRun`` changes state. +You can use these events to react to ``SchedulerJob`` or ``BackfillJob`` state changes. Usage -===== +----- + +To create a listener: -To create a listener you will need to derive the import -``airflow.listeners.hookimpl`` and implement the ``hookimpls`` for -events you want to be notified at. +- import ``airflow.listeners.hookimpl`` +- implement the ``hookimpls`` for events that you'd like to generate notifications -Their specification is defined as ``hookspec`` in ``airflow/listeners/spec`` directory. -Your implementation needs to accept the same named parameters as defined in hookspec, or Pluggy will complain about your plugin. -On the other hand, you don't need to implement every method - it's perfectly fine to have a listener that implements just one method, or any subset of methods. +Airflow defines the specification as `hookspec <https://github.com/apache/airflow/tree/main/airflow/listeners/spec>`__. +Your implementation must accept the same named parameters as defined in hookspec. +If you don't use the same parameters as hookspec, Pluggy throws an error when you try to use your plugin. +But you don't need to implement every method. +Many listeners only implement one method, or a subset of methods. Review Comment: Would write this as one paragraph instead of sentences on separate lines. I haven't built the docs with these changes but assume each gets printed on a new line. -- 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]
