Add [collection:xxx] config section for cross-group program organization

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>

Author: owensk

docs/api.rst

@@ -351,6 +351,21 @@ Process Control
 
     .. automethod:: removeProcessGroup
 
+Collections
+-----------
+
+  .. autoclass:: SupervisorNamespaceRPCInterface
+
+    .. automethod:: listCollections
+
+    .. automethod:: getCollectionProcessInfo
+
+    .. automethod:: startCollection
+
+    .. automethod:: stopCollection
+
+    .. automethod:: signalCollection
+
 Process Logging
 ---------------
 

docs/configuration.rst

@@ -1526,6 +1526,73 @@ above constraints and additions.
    environment=A="1",B="2"
    serverurl=AUTO
 
+``[collection:x]`` Section Settings
+------------------------------------
+
+Collections provide a way to organize programs into logical groups that
+can span multiple process groups.  Unlike ``[group:x]`` sections which
+own process lifecycle, collections are purely organizational — they
+allow you to view and control sets of related processes without
+affecting which group owns them.
+
+A program can belong to any number of collections.  Collection
+operations like start and stop delegate to the owning process groups.
+
+To define a collection, add a ``[collection:x]`` section in your
+configuration file.  The header value is the word "collection",
+followed by a colon, then the collection name.  A header value of
+``[collection:foo]`` describes a collection with the name "foo".  The
+name must not include a colon character or a bracket character.
+
+``[collection:x]`` Section Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``programs``
+
+  A comma-separated list of program names.  The programs referenced
+  here are resolved at runtime to their owning process groups.  Missing
+  references are silently skipped.
+
+  *Required*:  No (but at least one of ``programs`` or ``groups`` is
+  required).
+
+  *Introduced*: 4.0
+
+``groups``
+
+  A comma-separated list of group names.  All processes in the
+  referenced groups become members of this collection.  Missing
+  references are silently skipped.
+
+  *Required*:  No (but at least one of ``programs`` or ``groups`` is
+  required).
+
+  *Introduced*: 4.0
+
+``priority``
+
+  A priority number analogous to a ``[program:x]`` priority value.
+
+  *Default*: 999
+
+  *Required*:  No.
+
+  *Introduced*: 4.0
+
+``[collection:x]`` Section Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: ini
+
+   [collection:web-tier]
+   programs=nginx,gunicorn,celery-worker
+   priority=100
+
+   [collection:monitoring]
+   groups=metrics
+   programs=nginx,prometheus-exporter
+
+
 ``[rpcinterface:x]`` Section Settings
 -------------------------------------
 

supervisor/collection.py

@@ -0,0 +1,12 @@
+class Collection:
+    """A logical grouping of processes from potentially different groups.
+    Collections do not own process lifecycle — they are purely
+    organizational and delegate start/stop to the owning groups."""
+
+    def __init__(self, config, members):
+        self.config = config          # CollectionConfig
+        self.members = members        # list of (ProcessGroup, Subprocess) tuples
+
+    def get_processes(self):
+        """Return list of (group, process) tuples."""
+        return list(self.members)

supervisor/events.py

@@ -177,6 +177,19 @@ class ProcessGroupAddedEvent(ProcessGroupEvent):
 class ProcessGroupRemovedEvent(ProcessGroupEvent):
     pass
 
+class CollectionEvent(Event):
+    def __init__(self, collection):
+        self.collection = collection
+
+    def payload(self):
+        return 'collectionname:%s\n' % self.collection
+
+class CollectionAddedEvent(CollectionEvent):
+    pass
+
+class CollectionRemovedEvent(CollectionEvent):
+    pass
+
 class TickEvent(Event):
     """ Abstract """
     def __init__(self, when, supervisord):

supervisor/options.py

@@ -448,6 +448,7 @@ def __init__(self):
                  "s", "silent", flag=1, default=0)
         self.pidhistory = {}
         self.process_group_configs = []
+        self.collection_configs = []
         self.parse_criticals = []
         self.parse_warnings = []
         self.parse_infos = []
@@ -544,6 +545,9 @@ def process_config(self, do_usage=True):
         new = self.configroot.supervisord.process_group_configs
         self.process_group_configs = new
 
+        new_collections = self.configroot.supervisord.collection_configs
+        self.collection_configs = new_collections
+
     def read_config(self, fp):
         # Clear parse messages, since we may be re-reading the
         # config a second time after a reload.
@@ -667,6 +671,7 @@ def get(opt, default, **kwargs):
                 env = section.environment.copy()
                 env.update(proc.environment)
                 proc.environment = env
+        section.collection_configs = self.collections_from_parser(parser)
         section.server_configs = self.server_configs_from_parser(parser)
         section.profile_options = None
         return section
@@ -840,6 +845,46 @@ def get(section, opt, default, **kwargs):
         groups.sort()
         return groups
 
+    def collections_from_parser(self, parser):
+        collections = []
+        all_sections = parser.sections()
+
+        common_expansions = {'here':self.here}
+        def get(section, opt, default, **kwargs):
+            expansions = kwargs.get('expansions', {})
+            expansions.update(common_expansions)
+            kwargs['expansions'] = expansions
+            return parser.saneget(section, opt, default, **kwargs)
+
+        for section in all_sections:
+            if not section.startswith('collection:'):
+                continue
+            name = process_or_group_name(section.split(':', 1)[1])
+            priority = integer(get(section, 'priority', 999))
+            programs_str = get(section, 'programs', None)
+            groups_str = get(section, 'groups', None)
+
+            program_names = []
+            if programs_str is not None:
+                program_names = list_of_strings(programs_str)
+
+            group_names = []
+            if groups_str is not None:
+                group_names = list_of_strings(groups_str)
+
+            if not program_names and not group_names:
+                raise ValueError(
+                    '[%s] must specify at least one of programs or groups'
+                    % section)
+
+            collections.append(
+                CollectionConfig(self, name, priority,
+                                 program_names, group_names)
+            )
+
+        collections.sort()
+        return collections
+
     def parse_fcgi_socket(self, sock, proc_uid, socket_owner, socket_mode,
             socket_backlog):
         if sock.startswith('unix://'):
@@ -2055,6 +2100,41 @@ def make_group(self):
         from supervisor.process import FastCGIProcessGroup
         return FastCGIProcessGroup(self)
 
+class CollectionConfig:
+    def __init__(self, options, name, priority, program_names, group_names):
+        self.options = options
+        self.name = name
+        self.priority = priority
+        self.program_names = program_names  # list of str
+        self.group_names = group_names      # list of str
+
+    def __eq__(self, other):
+        if not isinstance(other, CollectionConfig):
+            return False
+        return (self.name == other.name and
+                self.priority == other.priority and
+                self.program_names == other.program_names and
+                self.group_names == other.group_names)
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __lt__(self, other):
+        return self.priority < other.priority
+
+    def __le__(self, other):
+        return self.priority <= other.priority
+
+    def __gt__(self, other):
+        return self.priority > other.priority
+
+    def __ge__(self, other):
+        return self.priority >= other.priority
+
+    def __repr__(self):
+        return '<%s instance named %s at %s>' % (self.__class__,
+                                                  self.name, id(self))
+
 def readFile(filename, offset, length):
     """ Read length bytes from the file named by filename starting at
     offset """

supervisor/rpcinterface.py

@@ -198,7 +198,16 @@ def reloadConfig(self):
         added = [group.name for group in added]
         changed = [group.name for group in changed]
         removed = [group.name for group in removed]
-        return [[added, changed, removed]] # cannot return len > 1, apparently
+
+        coll_added, coll_changed, coll_removed = \
+            self.supervisord.diff_collections_to_active()
+
+        coll_added = [c.name for c in coll_added]
+        coll_changed = [c.name for c in coll_changed]
+        coll_removed = [c.name for c in coll_removed]
+
+        return [[added, changed, removed],
+                [coll_added, coll_changed, coll_removed]]
 
     def addProcessGroup(self, name):
         """ Update the config for a running process from config file.
@@ -917,6 +926,128 @@ def sendProcessStdin(self, name, chars):
 
         return True
 
+    # Collection API methods
+
+    def listCollections(self):
+        """ Get info about all configured collections.
+
+        @return array result  An array of collection info structs
+        """
+        self._update('listCollections')
+        result = []
+        for coll in self.supervisord.collections.values():
+            result.append({
+                'name': coll.config.name,
+                'priority': coll.config.priority,
+                'program_names': coll.config.program_names,
+                'group_names': coll.config.group_names,
+            })
+        return result
+
+    def getCollectionProcessInfo(self, name):
+        """ Get info about all processes in a collection named name.
+
+        @param string name  The name of the collection
+        @return array result  An array of process status results
+        """
+        self._update('getCollectionProcessInfo')
+
+        collection = self.supervisord.collections.get(name)
+        if collection is None:
+            raise RPCError(Faults.BAD_NAME, name)
+
+        output = []
+        seen = set()
+        for group, process in collection.get_processes():
+            key = (group.config.name, process.config.name)
+            if key not in seen:
+                seen.add(key)
+                namespec = make_namespec(group.config.name,
+                                         process.config.name)
+                output.append(self.getProcessInfo(namespec))
+        return output
+
+    def startCollection(self, name, wait=True):
+        """ Start all processes in the collection named 'name'
+
+        @param string name     The collection name
+        @param boolean wait    Wait for each process to be fully started
+        @return array result   An array of process status info structs
+        """
+        self._update('startCollection')
+
+        collection = self.supervisord.collections.get(name)
+        if collection is None:
+            raise RPCError(Faults.BAD_NAME, name)
+
+        seen = set()
+        processes = []
+        for group, process in collection.get_processes():
+            key = (group.config.name, process.config.name)
+            if key not in seen:
+                seen.add(key)
+                processes.append((group, process))
+
+        startall = make_allfunc(processes, isNotRunning, self.startProcess,
+                                wait=wait)
+        startall.delay = 0.05
+        startall.rpcinterface = self
+        return startall  # deferred
+
+    def stopCollection(self, name, wait=True):
+        """ Stop all processes in the collection named 'name'
+
+        @param string name     The collection name
+        @param boolean wait    Wait for each process to be fully stopped
+        @return array result   An array of process status info structs
+        """
+        self._update('stopCollection')
+
+        collection = self.supervisord.collections.get(name)
+        if collection is None:
+            raise RPCError(Faults.BAD_NAME, name)
+
+        seen = set()
+        processes = []
+        for group, process in collection.get_processes():
+            key = (group.config.name, process.config.name)
+            if key not in seen:
+                seen.add(key)
+                processes.append((group, process))
+
+        killall = make_allfunc(processes, isRunning, self.stopProcess,
+                               wait=wait)
+        killall.delay = 0.05
+        killall.rpcinterface = self
+        return killall  # deferred
+
+    def signalCollection(self, name, signal):
+        """ Send a signal to all processes in the collection named 'name'
+
+        @param string name    The collection name
+        @param string signal  Signal to send, as name ('HUP') or number ('1')
+        @return array
+        """
+        self._update('signalCollection')
+
+        collection = self.supervisord.collections.get(name)
+        if collection is None:
+            raise RPCError(Faults.BAD_NAME, name)
+
+        seen = set()
+        processes = []
+        for group, process in collection.get_processes():
+            key = (group.config.name, process.config.name)
+            if key not in seen:
+                seen.add(key)
+                processes.append((group, process))
+
+        sendall = make_allfunc(processes, isSignallable, self.signalProcess,
+                               signal=signal)
+        result = sendall()
+        self._update('signalCollection')
+        return result
+
     def sendRemoteCommEvent(self, type, data):
         """ Send an event that will be received by event listener
         subprocesses subscribing to the RemoteCommunicationEvent.