Create documentation page about events

docs/developer/explanations/events.rst

@@ -0,0 +1,67 @@
+Events Emitted by the Worker
+============================
+
+Blueapi adds new events on top of the `bluesky event model`_.
+
+Reasons
+-------
+
+Since the ``RunEngine`` is traditionally used by a human in front of an IPython terminal, it
+sometimes assumes intuitive behaviour. The worker replaces the human and so must fill in the
+gaps.
+
+The base engine programatically emits data events conforming to the `bluesky event model`_. These
+are meant to be handled by other subscribing code (e.g. databroker) and are decoupled from concerns such as whether
+a plan has started, finished, paused, errored etc. See the example below:
+
+.. figure:: ../../images/bluesky-events.png
+    :width: 600px
+    :align: center
+
+    sequence of event emission compared to plan start/finish, in a complicated case
+
+Note the gap between the start of the plan and the issue of the first `run start document`_, and the similar gap
+for the stop document vs end of the plan, thsse are typically used for setup and cleanup. 
+Also note that a plan can produce an arbitrary number of runs. This decoupling is fine in an IPython terminal
+because a human user can see when a plan has started, can see when it's finished and can see which runs are
+associated with which plans.
+
+New Events
+----------
+
+For the case of automation, we introduce a new set of events outside of the event model, specifically
+pertaining to the running of the plan and state of the ``RunEngine``. At a mimimum, an event is emitted
+every time the engine:
+
+* Starts a new plan
+* Completes a plan
+* Fails/errors
+
+In the latter case, information about the error is also included.
+
+
+Correlation ID
+--------------
+
+When controlling plans programatically, it can be useful to verify that event model documents really are related to 
+the plan you just asked the worker to run. The worker will therefore bundle a correlation ID into the headers of
+messages containing documents.
+
+.. seealso:: `Microsoft Playbook on Correlation IDs`_
+
+ActiveMQ will give this header a different name depending on the protocol you use.
+
+.. list-table:: Correlation ID Headers
+   :widths: 25 25
+   :header-rows: 1
+
+   * - Protocol
+     - Header name
+   * - JMS
+     - jms_correlationID
+   * - STOMP
+     - correlation-id
+
+.. _`bluesky event model`: https://blueskyproject.io/event-model/main/index.html
+.. _`run start document`: https://blueskyproject.io/event-model/main/user/explanations/data-model.html#run-start-document
+.. _`Microsoft Playbook on Correlation IDs`: https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/

docs/developer/index.rst

@@ -50,6 +50,7 @@ side-bar.
             explanations/architecture
             explanations/lifecycle
             explanations/type_validators
+            explanations/events
 
         +++