Configuring an Event Listener

A supervisor event listener is specified via a [eventlistener:x]section in the configuration file. Supervisor [eventlistener:x]sections are treated almost exactly like supervisor [program:x]section with the respect to the keys allowed in their configurationexcept that Supervisor does not respect “capture mode” output fromevent listener processes (ie. event listeners cannot bePROCESS_COMMUNICATIONS_EVENT event generators). Therefore it isan error to specify stdout_capture_maxbytes orstderr_capture_maxbytes in the configuration of an eventlistener.There is no artificial constraint on the number of eventlistenersections that can be placed into the configuration file.

When an [eventlistener:x] section is defined, it actually definesa “pool”, where the number of event listeners in the pool isdetermined by the numprocs value within the section.

The events parameter of the [eventlistener:x] sectionspecifies the events that will be sent to a listener pool. Awell-written event listener will ignore events that it cannot process,but there is no guarantee that a specific event listener won’t crashas a result of receiving an event type it cannot handle. Therefore,depending on the listener implementation, it may be important tospecify in the configuration that it may receive only certain types ofevents. The implementor of the event listener is the only person whocan tell you what these are (and therefore what value to put in theevents configuration). Examples of eventlistenerconfigurations that can be placed in supervisord.conf are asfollows.

[eventlistener:memmon]
command=memmon -a 200MB -m bob@example.com
events=TICK_60

[eventlistener:mylistener]
command=my_custom_listener.py
events=PROCESS_STATE,TICK_60

Note

An advanced feature, specifying an alternate “result handler” for apool, can be specified via the result_handler parameter of an[eventlistener:x] section in the form of a pkg_resources “entrypoint” string. The default result handler issupervisord.dispatchers:default_handler. Creating an alternateresult handler is not currently documented.

When an event notification is sent by supervisor, all event listenerpools which are subscribed to receive events for the event’s type(filtered by the events value in the eventlistenersection) will be found. One of the listeners in each listener poolwill receive the event notification (any “available” listener).

Every process in an event listener pool is treated equally bysupervisor. If a process in the pool is unavailable (because it isalready processing an event, because it has crashed, or because it haselected to removed itself from the pool), supervisor will chooseanother process from the pool. If the event cannot be sent becauseall listeners in the pool are “busy”, the event will be buffered andnotification will be retried later. “Later” is defined as “the nexttime that the supervisord select loop executes”. Forsatisfactory event processing performance, you should configure a poolwith as many event listener processes as appropriate to handle yourevent load. This can only be determined empirically for any givenworkload, there is no “magic number” but to help you determine theoptimal number of listeners in a given pool, Supervisor will emitwarning messages to its activity log when an event cannot be sentimmediately due to pool congestion. There is no artificial constraintplaced on the number of processes that can be in a pool, it is limitedonly by your platform constraints.

A listener pool has an event buffer queue. The queue is sized via thelistener pool’s buffer_size config file option. If the queue isfull and supervisor attempts to buffer an event, supervisor will throwaway the oldest event in the buffer and log an error.