Child Process Logs

The stdout of child processes spawned by supervisor, by default, iscaptured for redisplay to users of supervisorctl and otherclients. If no specific logfile-related configuration is performed ina [program:x], [fcgi-program:x], or [eventlistener:x]section in the configuration file, the following is true:

• supervisord will capture the child process’ stdout andstderr output into temporary files. Each stream is captured to aseparate file. This is known as AUTO log mode.
• AUTO log files are named automatically and placed in thedirectory configured as childlogdir of the [supervisord]section of the config file.
• The size of each AUTO log file is bounded by the{streamname}_logfile_maxbytes value of the program section(where {streamname} is “stdout” or “stderr”). When it reaches thatnumber, it is rotated (like the activity log), based on the{streamname}_logfile_backups.

The configuration keys that influence child process logging in[program:x] and [fcgi-program:x] sections are these:

redirect_stderr, stdout_logfile, stdout_logfile_maxbytes,stdout_logfile_backups, stdout_capture_maxbytes, stdout_syslog,stderr_logfile, stderr_logfile_maxbytes,stderr_logfile_backups, stderr_capture_maxbytes, andstderr_syslog.

[eventlistener:x] sections may not specifyredirect_stderr, stdout_capture_maxbytes, orstderr_capture_maxbytes, but otherwise they accept the same values.

The configuration keys that influence child process logging in the[supervisord] config file section are these:childlogdir, and nocleanup.

Capture Mode

Capture mode is an advanced feature of Supervisor. You needn’tunderstand capture mode unless you want to take actions based on dataparsed from subprocess output.

If a [program:x] section in the configuration file defines anon-zero stdoutcapture_maxbytes or stderr_capture_maxbytesparameter, each process represented by the program section may emitspecial tokens on its stdout or stderr stream (respectively) whichwill effectively cause supervisor to emit a PROCESS_COMMUNICATIONevent (see [_Events]($b660ed3c59d10b4f.md#events) for a description of events).

The process communications protocol relies on two tags, one whichcommands supervisor to enter “capture mode” for the stream and onewhich commands it to exit. When a process stream enters “capturemode”, data sent to the stream will be sent to a separate buffer inmemory, the “capture buffer”, which is allowed to contain a maximum ofcapture_maxbytes bytes. During capture mode, when the buffer’slength exceeds capture_maxbytes bytes, the earliest data in thebuffer is discarded to make room for new data. When a process streamexits capture mode, a PROCESS_COMMUNICATION event subtype isemitted by supervisor, which may be intercepted by event listeners.

The tag to begin “capture mode” in a process stream is<!—XSUPERVISOR:BEGIN—>. The tag to exit capture mode is<!—XSUPERVISOR:END—>. The data between these tags may bearbitrary, and forms the payload of the PROCESS_COMMUNICATIONevent. For example, if a program is set up with astdout_capture_maxbytes of “1MB”, and it emits the following onits stdout stream:

<!--XSUPERVISOR:BEGIN-->Hello!<!--XSUPERVISOR:END-->

In this circumstance, supervisord will emit aPROCESS_COMMUNICATIONS_STDOUT event with data in the payload of“Hello!”.

An example of a script (written in Python) which emits a processcommunication event is in the scripts directory of thesupervisor package, named sample_commevent.py.

The output of processes specified as “event listeners”([eventlistener:x] sections) is not processed this way.Output from these processes cannot enter capture mode.