Skip to content

Add [collection:x] config section for cross-group process organization#1716

Closed
owensk wants to merge 1 commit intoSupervisor:mainfrom
owensk:feature/collections
Closed

Add [collection:x] config section for cross-group process organization#1716
owensk wants to merge 1 commit intoSupervisor:mainfrom
owensk:feature/collections

Conversation

@owensk
Copy link
Copy Markdown

@owensk owensk commented Mar 28, 2026

Summary

Adds [collection:x], a new configuration section that defines logical, cross-group views over processes without affecting lifecycle ownership. Closes #1715.

This has been requested before (#556, #1026) but never implemented. Collections are intentionally lightweight — they don't own process lifecycle, groups still do. A collection simply references processes by name or includes entire groups, then delegates operations to the owning group.

Example Configuration

[collection:web-tier]
programs=nginx,gunicorn,celery-worker
priority=100

[collection:monitoring]
groups=metrics
programs=nginx,prometheus-exporter

Changes

Component Files Description
Core model supervisor/collection.py Collection class — thin wrapper holding config + resolved (group, process) members
Configuration supervisor/options.py CollectionConfig data class, collections_from_parser() for [collection:x] sections
Daemon supervisor/supervisord.py resolve_collection, add_collection, remove_collection, diff_collections_to_active
XML-RPC supervisor/rpcinterface.py listCollections, getCollectionProcessInfo, startCollection, stopCollection, signalCollection
CLI supervisor/supervisorctl.py collection status/start/stop commands with tab completion
Events supervisor/events.py CollectionAddedEvent, CollectionRemovedEvent
Docs docs/configuration.rst, docs/api.rst Config reference and API reference
Tests supervisor/tests/test_collection.py 31 unit tests covering config, parsing, resolution, deduplication, diffing, and events

Design

  • Collections don't own lifecycle[group:x] retains that responsibility
  • A process can appear in multiple collections — they're views, not containers
  • Missing references are silently skipped — graceful during rolling config updates
  • Collections are re-resolved on update — membership stays in sync with config changes

Backwards Compatibility

No existing configuration, API, CLI, or event behavior is modified. The [collection:x] section prefix is new and does not conflict with existing section types. All changes are additive. The full existing test suite (1,385 tests) passes without modification.

Test Plan

  • CollectionConfig equality, ordering, and repr
  • collections_from_parser parses programs, groups, both, and rejects empty collections
  • collections_from_parser sorts by priority and ignores non-collection sections
  • resolve_collection matches by program name, group name, cross-group, and deduplicates
  • resolve_collection silently skips missing programs and groups
  • add_collection / remove_collection update runtime state and fire events
  • diff_collections_to_active detects added, changed, and removed collections
  • CollectionAddedEvent / CollectionRemovedEvent produce correct payloads

Collections allow programs to be logically grouped across multiple
process groups without affecting lifecycle ownership. Groups still own
start/stop/restart; collections are a purely organizational layer that
delegates operations to the owning groups.

New config format:
  [collection:web-tier]
  programs=nginx,gunicorn
  groups=workers

New RPC methods: listCollections, getCollectionProcessInfo,
startCollection, stopCollection, signalCollection. New CLI commands:
collection status/start/stop. Web UI supports ?collection= filtering.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@mnaberez
Copy link
Copy Markdown
Member

#1715 (closed) has nearly the same description also.

@mnaberez
Copy link
Copy Markdown
Member

Closing as a duplicate of #556. While this was mentioned before about ten years ago as you note, managing process "tiers" remains out of scope for the core Supervisor project. I think the maintenance burden of dealing with all this additional complexity and code outweighs the benefits for the majority of users, so we will not be pursuing this.

@mnaberez mnaberez closed this Mar 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

Feature: [collection:x] config section for cross-group process organization

2 participants