# coderanger/supervisor-stdout architecture

> Architecture diagram of the GitHub repository coderanger/supervisor-stdout, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coderanger/supervisor-stdout
- Repository: https://github.com/coderanger/supervisor-stdout

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    App["Supervised App"]:::app
    Core["Supervisord Core\n(config: stdout_events_enabled,\nstderr_events_enabled,\nevents=PROCESS_LOG)"]:::core
    Listener["supervisor-stdout Listener\n(entry point: supervisor_stdout:event_handler)"]:::listener
    External["External Logging System"]:::external

    App -->|"stdout/stderr"| Core
    Core -->|"PROCESS_LOG events"| Listener
    Listener -->|"parsed log lines"| External

    subgraph "Project Files"
        Psetup["setup.py"]:::files
        Preadme["README.md"]:::files
        Pgit[".gitignore"]:::files
    end

    click Listener "https://github.com/coderanger/supervisor-stdout/blob/master/supervisor_stdout.py"
    click Psetup "https://github.com/coderanger/supervisor-stdout/blob/master/setup.py"
    click Preadme "https://github.com/coderanger/supervisor-stdout/blob/master/README.md"
    click Pgit "https://github.com/coderanger/supervisor-stdout/blob/master/.gitignore"

    classDef app fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef listener fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef files fill:#F0F0F0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
