Problem
Supervisor's [group:x] sections serve a dual purpose: they define process lifecycle ownership and act as the only mechanism for logically grouping processes together. This coupling creates a limitation — there is no way to define a logical grouping of processes that spans multiple groups.
For example, consider a deployment with these groups:
[group:web]
programs=nginx,gunicorn
[group:workers]
programs=celery-worker,celery-beat
[group:monitoring]
programs=prometheus-exporter,node-exporter
If an operator wants to view or restart all processes related to the "web tier" — say nginx, gunicorn, and prometheus-exporter — they must issue separate commands against each group. There is no way to express "these processes across different groups form a logical unit" in the configuration.
This has been requested before in #556 and #1026. Those issues identified the problem clearly but were closed without an implementation. I've built one.
Proposed Solution
A new [collection:x] config section that defines a named, read-through view over processes from one or more groups:
[collection:web-tier]
programs=nginx,gunicorn,celery-worker
priority=100
[collection:monitoring]
groups=metrics
programs=prometheus-exporter
Key Design Decisions
- Collections do not own lifecycle. Groups remain the sole owners of process lifecycle. Collections reference processes by name or include entire groups, then delegate all start/stop/signal operations to the owning group.
- A process can belong to multiple collections. Collections are views, not containers — overlapping membership is expected.
- Missing references are silently skipped. If a referenced program or group doesn't exist (e.g., during a rolling config update), the collection resolves without it rather than failing.
- Collections are resolved at runtime. Membership is evaluated against currently active process groups, so collections stay consistent after
reread/update.
Scope
The implementation touches:
- Configuration: New
[collection:x] section with programs, groups, and priority keys
- XML-RPC API:
listCollections, getCollectionProcessInfo, startCollection, stopCollection, signalCollection
- supervisorctl:
collection status [name], collection start <name>, collection stop <name> with tab completion
- Events:
CollectionAddedEvent, CollectionRemovedEvent
- Reread/update cycle: Collections are diffed and reconciled alongside groups during
update
Backwards Compatibility
Fully backwards compatible. No existing configuration keys, API methods, CLI commands, or behaviors are modified. Collections are entirely opt-in.
Implementation
I have a working implementation with full test coverage and documentation, submitted as a PR. Happy to iterate on the design if there's interest.
Problem
Supervisor's
[group:x]sections serve a dual purpose: they define process lifecycle ownership and act as the only mechanism for logically grouping processes together. This coupling creates a limitation — there is no way to define a logical grouping of processes that spans multiple groups.For example, consider a deployment with these groups:
If an operator wants to view or restart all processes related to the "web tier" — say
nginx,gunicorn, andprometheus-exporter— they must issue separate commands against each group. There is no way to express "these processes across different groups form a logical unit" in the configuration.This has been requested before in #556 and #1026. Those issues identified the problem clearly but were closed without an implementation. I've built one.
Proposed Solution
A new
[collection:x]config section that defines a named, read-through view over processes from one or more groups:Key Design Decisions
reread/update.Scope
The implementation touches:
[collection:x]section withprograms,groups, andprioritykeyslistCollections,getCollectionProcessInfo,startCollection,stopCollection,signalCollectioncollection status [name],collection start <name>,collection stop <name>with tab completionCollectionAddedEvent,CollectionRemovedEventupdateBackwards Compatibility
Fully backwards compatible. No existing configuration keys, API methods, CLI commands, or behaviors are modified. Collections are entirely opt-in.
Implementation
I have a working implementation with full test coverage and documentation, submitted as a PR. Happy to iterate on the design if there's interest.