potiuk commented on code in PR #39544: URL: https://github.com/apache/airflow/pull/39544#discussion_r1596725025
########## docs/apache-airflow/administration-and-deployment/listeners.rst: ########## @@ -110,3 +110,87 @@ Airflow defines the specification as `hookspec <https://github.com/apache/airflo 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. 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. The logs and ``print()`` calls will be handled as part of the listeners. + + +Compatibility note +------------------ + +The listeners interface might change over time. We are using ``pluggy`` specifications which +means that implementation of the listeners written for older versions of the interface should be +forward-compatible with future versions of Airflow. + +However, the opposite is not guaranteed, so if your listener is implemented against a newer version of the +interface, it might not work with older versions of Airflow. It is not a problem if you target single version +of Airflow, because you can adjust your implementation to the version of Airflow you use, but it is important +if you are writing plugins or extensions that could be used with different versions of Airflow. + +For example if a new field is added to the interface (like the ``error`` field in the +``on_task_instance_failed`` method in 2.10.0), the listener implementation will not handle the case when +the field is not present in the event object and such listeners will only work for Airflow 2.10.0 and later. + +In order to implement a listener that is compatible with multiple versions of Airflow including using features +and fields added in newer versions of Airflow, you should check version of Airflow used and use newer version +of the interface implementation, but for older versions of Airflow you should use older version of the +interface. + +For example if you want to implement a listener that uses the ``error`` field in the ``on_task_instance_failed`` +You should use code like this: + +.. code-block:: python + + from importlib.metadata import version + from packaging.version import Version + from airflow.listeners import hookimpl + + + @hookimpl + def on_task_instance_failed(task_instance, **kwargs): Review Comment: Removed the kwargs example -- 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: commits-unsubscr...@airflow.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
