Document event types.

README.txt

@@ -739,7 +739,133 @@ Process States
 
 Supervisor Events
 
-  XXX TODO
+  At certain predefined points during supervisord's operation, "event
+  notifications" are emitted.  An event denotes that something
+  potentially interesting happened.  Event listeners (see the "Event
+  Listeners" section below) can be configured to subscribe to event
+  notifications selectively, and may perform arbitrary actions based
+  on an event notification (send email, make an HTTP request, etc).
+
+  Event types that may be subscribed to by event listeners are
+  predefined by supervisor and fall into several major categories,
+  including "process state change", "process communication",
+  "supervisor state change", and "event system meta" events.  These
+  are described in detail below.
+
+  EVENT -- The base event type.  This event type is abstract.  It will
+  never be sent directly.  Subscribing to this event type will cause a
+  subscriber to receive all event notifications emitted by supervisor.
+
+  Subtypes of EVENT:
+
+    PROCESS_STATE_CHANGE -- The value of this event type will be the
+    process name.  Subscribing to this event type will cause a
+    subscriber to receive event notifications of all the types listed
+    below in "Subtypes of PROCESS_STATE_CHANGE".
+
+    The serialized body of a PROCESS_STATE_CHANGE event (and all
+    subtypes) is in the form::
+
+      process_name: <name>
+      group_name: <name>
+
+    Subtypes of PROCESS_STATE_CHANGE:
+
+      STARTING -- indicates a process has moved from a state to the
+      STARTING state.  Subscribing to this event type will cause a
+      subscriber to receive event notifications of all the types
+      listed below in "Subtypes of STARTING".
+
+      Subtypes of STARTING:
+
+        STARTING_FROM_STOPPED -- subtype of STARTING, indicates a
+        process has moved from the STOPPED state from the STARTING
+        state.
+
+        STARTING_FROM_BACKOFF -- subtype of STARTING, indicates a
+        process has moved from BACKOFF state to the STARTING state.
+
+        STARTING_FROM_EXITED -- subtype of STARTING, indicates a
+        process has moved from the EXITED state to the STARTING
+        state.
+
+        STARTING_FROM_FATAL -- subtype of STARTING, indicates a
+        process has moved to the FATAL state to the STARTING state.
+
+      RUNNING -- inidicates a process has moved from the STARTING state
+      to the RUNNING state.
+
+      BACKOFF -- indicates a process has moved from the STARTING state
+      to the BACKOFF state.
+
+      STOPPING_FROM_RUNNING -- indicates a process has moved from the
+      RUNNING state to the STOPPING state.
+
+      STOPPING_FROM_STARTING -- indicates a process has moved from
+      the RUNNING state to the STARTING state.
+
+      EXITED_OR_STOPPED -- indicates a process has undergone a state
+      change which caused it to move to the EXITED or STOPPED state.
+
+      Subtypes of EXITED_OR_STOPPED:
+
+        EXITED -- indicates a process has moved from the RUNNING
+        state to the EXITED state.
+
+        STOPPED -- indicates a process has moved from the STOPPING
+        state to the STOPPED state.
+
+      FATAL -- indicates a process has moved from the BACKOFF state
+      to the FATAL state.
+
+      UNKNOWN -- indicates a process has moved from a state to the
+      UNKNOWN state (indicates an error in supervisord).
+
+    PROCESS_COMMUNICATION -- an event type raised when any process
+    attempts to send information between <!--XSUPERVISOR:BEGIN--> and
+    <--XSUPERVISOR:END--> tags in its output.  Subscribing to this
+    event type will cause a subscriber to receive event notifications
+    of all the types listed below in "Subtypes of
+    PROCESS_COMMUNICATION".
+
+    The serialized body of a PROCESS_COMMUNICATION event (and all
+    subtypes) is::
+
+      process_name: <name>
+      group_name: <name>
+      <data>
+
+    Subtypes of PROCESS_COMMUNICATION:
+
+      PROCESS_COMMUNICATION_STDOUT -- indicates a process has sent a
+      message to supervisor on its stdout file descriptor.
+
+      PROCESS_COMMUNICATION_STDERR -- indicates a process has sent a
+      message to supervisor on its stderr file descriptor.
+
+    SUPERVISOR_STATE_CHANGE -- an event type raised when supervisor's
+    state changes.  There is no value.  Subscribing to this event type
+    will cause a subscriber to receive event notifications of all the
+    types listed below in "Subtypes of SUPERVISOR_STATE_CHANGE".
+
+    The serialization of a SUPERVISOR_STATE_CHANGE event is the empty
+    string.
+
+    Subtypes of SUPERVISOR_STATE_CHANGE:
+
+      SUPERVISOR_RUNNING -- indicates that supervisor has started.
+
+      SUPERVISOR_STOPPING -- indicates that supervisor is stopping or
+      restarting.
+
+    EVENT_BUFFER_OVERFLOW -- an event type raised when a listener
+    pool's event buffer is overflowed.
+
+    The serialization of an EVENT_BUFFER_OVERFLOW body
+    is::
+
+      group_name: <name>
+      event_type: <type>
 
 Event Listeners