on_message callback documentation added (#3478)

docs/userguide/calling.rst

@@ -172,6 +172,44 @@ The callbacks/errbacks will then be called in order, and all
 callbacks will be called with the return value of the parent task
 as a partial argument.
 
+.. _calling-on-message:
+
+On message
+============================
+
+Celery supports catching all states changes by setting on_message callback.
+
+For example for long-running tasks to send task progress you can do something like this:
+
+.. code-block:: python
+
+    @app.task(bind=True)
+    def hello(self, a, b):
+        time.sleep(1)
+        self.update_state(state="PROGRESS", meta={'progress': 50})
+        time.sleep(1)
+        self.update_state(state="PROGRESS", meta={'progress': 90})
+        time.sleep(1)
+        return 'hello world: %i' % (a+b)
+
+.. code-block:: python
+
+    def on_raw_message(body):
+        print(body)
+
+    r = hello.apply_async()
+    print(r.get(on_message=on_raw_message, propagate=False))
+
+Will generate output like this:
+
+.. code-block:: 
+
+    {'task_id': '5660d3a3-92b8-40df-8ccc-33a5d1d680d7', 'result': {'progress': 50}, 'children': [], 'status': 'PROGRESS', 'traceback': None}
+    {'task_id': '5660d3a3-92b8-40df-8ccc-33a5d1d680d7', 'result': {'progress': 90}, 'children': [], 'status': 'PROGRESS', 'traceback': None}
+    {'task_id': '5660d3a3-92b8-40df-8ccc-33a5d1d680d7', 'result': 'hello world: 10', 'children': [], 'status': 'SUCCESS', 'traceback': None}
+    hello world: 10
+
+
 .. _calling-eta:
 
 ETA and Countdown