How coderanger/supervisor-stdout works
Project type and purpose
• This is an open-source event listener utility for supervisord, written in Python.
• Its sole purpose is to capture PROCESS_LOG events from supervisord and write them to stdout, allowing external systems (e.g., Heroku’s logging aggregator) to pick them up.
File structure
• Top level:
• README.md – project description, usage, and configuration example
• setup.py – packaging and entry-point definition
• supervisor_stdout.py – the single module implementing the listener and event handler
• .gitignore – standard ignore rules
• No subdirectories or complex modules: all logic lives in one file, registered as a console script.
README for additional insights
• It shows minimal configuration: enable stdout/stderr events in your program section, then register this listener under [eventlistener:stdout].
• The “result_handler = supervisor_stdout:event_handler” line calls the Python function on each PROCESS_LOG event.
Main components
a. Supervised Application(s)
• One or more worker/web processes managed by supervisord
b. Supervisord Core
• Orchestrates processes, emits events on stdout/stderr
c. Event Listener (supervisor-stdout)
• A separate process spawned by supervisord
• Listens on STDIN for PROCESS_LOG messages
• Invokes event_handler() in supervisor_stdout.py
• Writes parsed log lines to its STDOUT
d. External Logging Sink
• Any external collector reading the listener’s STDOUT (e.g., Heroku’s Logplex, syslog, file sink)
Architectural patterns and design principles
• Plugin pattern: supervisord spawns external event listeners by convention
• Single Responsibility: listener only transforms and forwards logs
• Loose coupling: any external log collector can subscribe to STDOUT
Key technologies and frameworks
• Python (console_scripts entry point)
• supervisord event listener protocol (stdin/stdout event bus)
• pip packaging / setuptools for installation
Detail
• Listener component with “entry point: supervisor_stdout:event_handler”
• Supervisord.conf settings: stdout_events_enabled, stderr_events_enabled, events=PROCESS_LOG
• That buffer_size controls backpressure but is outside code scope