feat: group Docker/Podman container logs by category instead of one file per container

Real usability gap found via live testing on an actual ovos-docker
install: bridging each of ~26 containers to its own file/log-source
meant 26 Sources: checkboxes and 26 different tag colors (all falling
back to the same default color, since none matched the known
skills/audio/voice/etc names) - unwieldy compared to a normal
install's small, familiar set.

Fixed with categorize_container_name(): maps real ovos-docker
container names (confirmed against a live install) to the SAME
category names file-based installs already use - every ovos_skill_*
container (and ovos_core, whose own log content is exactly what
already lands in skills.log on a normal install) maps to "skills",
ovos_audio to "audio", ovos_listener to "voice", ovos_messagebus to
"bus", ovos_phal/ovos_phal_admin to "phal", anything with "gui" in the
name to "gui", and anything unrecognized (ovos_cli,
ovos_plugin_ggwave, confirmed via the same live install) to a new
"other" category.

start_container_log_bridges() now groups containers by this category
and has every container in a group append to the SAME shared file
(skills.log, audio.log, etc) rather than its own separate one -
multiple containers' `docker logs -f` subprocesses writing to one file
concurrently is safe without locking (POSIX guarantees atomic writes
under PIPE_BUF with O_APPEND, true for any normal single log line).
This means discover_log_sources() no longer needs a custom `names=`
override for the bridge case at all - the files it creates already
match the default KNOWN_LOG_NAMES (added "other" to that list), so
coloring, tag formatting, and the Sources: checkboxes all work
completely unchanged, identical in shape to a normal install.

Verified end-to-end against real, locally-run podman containers
(two separate "skill" containers deliberately given different names -
confirmed both landed in the same skills.log, correctly interleaved,
tagged [skills] and colored green together, while a third "audio"
container stayed separate and yellow).

222 tests passing (9 new - categorize_container_name coverage per
category, plus a test confirming the grouping/shared-file behavior
specifically); verified sdist->wheel build.

Author: andlo

README.md

@@ -94,13 +94,17 @@ documentation directly, not guessed at:
   install that follows that guide as written, there are no log files
   on the host filesystem at all, only container stdout. When this tool
   finds no log files but detects a Docker/Podman install, it
-  automatically bridges each container's `docker logs -f` (or
-  `podman logs -f`) into a temp file and tails that instead - the
-  Sources: checkboxes then show the actual container names
-  (`ovos_core`, `ovos_audio`, etc) rather than the usual `skills`/
-  `audio`/etc, since there's no fully-confirmed container-name ->
-  service-name mapping to translate through. Bridge processes are
-  cleaned up on quit. If bridging isn't possible for some reason (no
+  automatically bridges each container's `docker logs -f` (or `podman
+  logs -f`) into the same small set of log files a normal install
+  already produces - `skills.log`, `audio.log`, `voice.log`, etc,
+  grouped by container name pattern (every `ovos_skill_*` container
+  lands in `skills.log` together, `ovos_audio` in `audio.log`, and so
+  on; anything unrecognized goes to `other.log`) - not one file/
+  checkbox per container. Confirmed against a real ovos-docker install
+  with 26 running containers: this keeps the Sources: checkboxes down
+  to a handful of familiar categories with the usual colors, instead
+  of two dozen individually-named ones. Bridge processes are cleaned
+  up on quit. If bridging isn't possible for some reason (no
   `docker`/`podman` binary available), it says so explicitly instead
   and points at `docker logs <container>` / `docker compose logs -f`
   directly.

ovos_tui_client/app.py

@@ -578,7 +578,16 @@ def on_mount(self) -> None:
                 self.log_bridge_handles = start_container_log_bridges(containers, bridge_dir)
                 if self.log_bridge_handles:
                     self.log_dir = bridge_dir
-                    self.log_sources = discover_log_sources(bridge_dir, names=containers)
+                    # No `names=` override here - start_container_log_
+                    # bridges() groups containers into the SAME
+                    # skills.log/audio.log/etc filenames a normal
+                    # install already uses (see
+                    # categorize_container_name()), not one file per
+                    # container, so the default KNOWN_LOG_NAMES
+                    # already finds them - same coloring, same
+                    # Sources: checkboxes, no special-casing needed
+                    # here at all.
+                    self.log_sources = discover_log_sources(bridge_dir)
                     bridged = True
                     self._write_status(
                         f"No log files, but bridged {len(containers)} Docker/Podman "

ovos_tui_client/logs.py

@@ -32,6 +32,7 @@
 # since which one exists depends on install age.
 KNOWN_LOG_NAMES = [
     "bus", "skills", "audio", "media", "voice", "gui", "enclosure", "phal",
+    "other",  # Docker/Podman bridge catch-all - see services.py's categorize_container_name()
 ]
 
 

ovos_tui_client/services.py

@@ -157,14 +157,70 @@ def _find_container_binary():
     return None
 
 
+def categorize_container_name(name):
+    """Maps a Docker/Podman container name to the SAME category names
+    file-based installs already use (see logs.py's KNOWN_LOG_NAMES) -
+    "skills", "audio", "voice", "bus", "phal", "gui" - or "other" if it
+    doesn't recognizably fit one of those.
+
+    This exists so start_container_log_bridges() (below) can make
+    Docker/Podman container logs land in the exact same small,
+    familiar set of log files a normal systemd/venv install already
+    produces - "skills.log", "audio.log", etc - rather than one file
+    per container (which on a real ovos-docker install is easily 15-25
+    separate files/checkboxes for what's conceptually still just a
+    handful of categories). Confirmed directly against a real,
+    running ovos-docker install's actual container names (ovos_core,
+    ovos_audio, ovos_listener, ovos_messagebus, ovos_phal,
+    ovos_phal_admin, ovos_skill_*, plus a few - ovos_cli,
+    ovos_plugin_ggwave - that don't map to anything and land in
+    "other").
+
+    Pattern-matched, not an exhaustive lookup table - "ovos_skill_"
+    (any suffix) always maps to "skills", matching how every
+    individual skill already shares ONE skills.log file on a normal
+    install, not one file per skill. "ovos_core" also maps to
+    "skills" specifically because its own log content (intent-service/
+    pipeline handling) is exactly what already lands in skills.log on
+    a normal install - confirmed by comparing real log line prefixes
+    between a systemd install and this container's own output."""
+    n = name.lower()
+    if n.startswith("ovos_skill") or n == "ovos_core":
+        return "skills"
+    if n == "ovos_audio":
+        return "audio"
+    if n == "ovos_listener":
+        return "voice"
+    if n == "ovos_messagebus":
+        return "bus"
+    if n.startswith("ovos_phal"):
+        return "phal"
+    if "gui" in n:
+        return "gui"
+    return "other"
+
+
 def start_container_log_bridges(container_names, target_dir):
-    """For each container name, starts 'docker logs -f <name>' (or
-    podman, whichever detect_container_runtime() would have used) with
-    its combined stdout+stderr redirected into target_dir/<name>.log -
-    then that directory can be handed to discover_log_sources() and
-    treated exactly like any other log directory, reusing 100% of the
-    existing file-tailing/filtering machinery. No new "log source"
-    abstraction needed inside the app itself.
+    """Bridges Docker/Podman container stdout into the SAME small set
+    of log files a normal file-based install already produces
+    (skills.log, audio.log, voice.log, bus.log, phal.log, plus
+    other.log for anything uncategorized - see
+    categorize_container_name() above) - not one file per container.
+    Then that directory can be handed to discover_log_sources() (its
+    DEFAULT KNOWN_LOG_NAMES, no override needed) and treated exactly
+    like any other log directory, reusing 100% of the existing
+    file-tailing/coloring/filtering machinery, including the Sources:
+    checkboxes actually being a small, meaningful set instead of one
+    checkbox per container.
+
+    Multiple containers sharing a category (most commonly "skills" -
+    every ovos_skill_* container) each get their OWN `docker logs -f`
+    subprocess, but all of them append to the SAME shared file -
+    concurrent appends from separate processes are safe here without
+    explicit locking, since POSIX guarantees a single write() to a
+    file opened with O_APPEND is atomic as long as it's smaller than
+    PIPE_BUF (4096 bytes on Linux) - true for any normal single log
+    line.
 
     This exists because a confirmed real gap (see the discussion that
     led here): on a Docker/Podman install following ovos-docker's own
@@ -174,15 +230,6 @@ def start_container_log_bridges(container_names, target_dir):
     log file, rather than teaching the app a second, parallel way to
     receive log lines.
 
-    Log source NAMES intentionally come from the container names
-    themselves (e.g. "ovos_core", "ovos_audio"), not a hardcoded
-    container->service mapping - the exact mapping isn't fully
-    confirmed for every core service (see issue #24's own notes on
-    this), and guessing wrong would silently mislabel things. Using
-    the container's own name sidesteps that entirely: whatever it's
-    actually called is what shows up, no mapping table to get wrong or
-    keep in sync as ovos-docker's own naming evolves.
-
     Returns a list of subprocess.Popen handles - the caller owns their
     lifecycle and MUST terminate them (e.g. on app quit); they are not
     cleaned up automatically here. Returns [] immediately (no
@@ -193,7 +240,8 @@ def start_container_log_bridges(container_names, target_dir):
     target_dir.mkdir(parents=True, exist_ok=True)
     handles = []
     for name in container_names:
-        log_path = target_dir / f"{name}.log"
+        category = categorize_container_name(name)
+        log_path = target_dir / f"{category}.log"
         log_file = open(log_path, "a")
         try:
             proc = subprocess.Popen(

tests/test_app.py

@@ -118,10 +118,11 @@ async def test_no_log_sources_on_a_docker_install_explains_stdout_logging(tmp_pa
 @pytest.mark.asyncio
 async def test_no_log_sources_bridges_docker_containers_when_possible(tmp_path):
     """The success path: start_container_log_bridges() actually
-    returns process handles (mocked here - real subprocess behavior is
-    covered separately in test_services.py) - the app should pick up
-    the bridged sources and NOT show the "no logs found" fallback
-    message at all."""
+    returns process handles (mocked here - real subprocess behavior,
+    including the container-name -> category grouping, is covered
+    separately in test_services.py) - the app should pick up the
+    bridged sources and NOT show the "no logs found" fallback message
+    at all."""
     empty_dir = tmp_path / "empty"
     empty_dir.mkdir()
     app = OVOSTUIApp(log_dir_override=str(empty_dir))
@@ -135,16 +136,20 @@ def fake_bridge(container_names, target_dir):
         # test can predict ahead of time - so writing it here, once
         # on_mount() passes in the real path, is the reliable way to
         # populate it before the (unmocked) discover_log_sources() call
-        # right after this one runs)
+        # right after this one runs). "ovos_core" categorizes to
+        # "skills" (see categorize_container_name()), so the file is
+        # named skills.log, not ovos_core.log - matching how the real
+        # bridge now groups containers into the same small set of
+        # filenames a normal install already uses.
         target_dir.mkdir(parents=True, exist_ok=True)
-        (target_dir / "ovos_core.log").write_text("")
+        (target_dir / "skills.log").write_text("")
         return [fake_proc]
 
     with patch("ovos_tui_client.app.detect_container_runtime", return_value=["ovos_core"]), \
          patch("ovos_tui_client.app.start_container_log_bridges", side_effect=fake_bridge):
         async with app.run_test() as pilot:
             assert len(app.log_sources) == 1
-            assert app.log_sources[0].name == "ovos_core"
+            assert app.log_sources[0].name == "skills"
             assert app.log_bridge_handles == [fake_proc]
             conv = app.query_one("#conversation", RichLog)
             conv_text = "\n".join(str(line) for line in conv.lines)

tests/test_services.py

@@ -2,7 +2,7 @@
 real service management is exercised here."""
 from unittest.mock import MagicMock, patch
 
-from ovos_tui_client.services import discover_services, discover_services_with_state, restart_service, stop_service, start_service, detect_container_runtime, start_container_log_bridges, stop_container_log_bridges
+from ovos_tui_client.services import discover_services, discover_services_with_state, restart_service, stop_service, start_service, detect_container_runtime, start_container_log_bridges, stop_container_log_bridges, categorize_container_name
 
 
 def _fake_completed(stdout="", stderr="", returncode=0):
@@ -182,6 +182,46 @@ def fake_run(cmd, **kwargs):
 # podman container during development - these tests cover the
 # subprocess-management logic itself, mocked)
 
+# --- categorize_container_name(): maps real ovos-docker container
+# names (confirmed against a real, running install) to the same
+# category names file-based installs already use ---
+
+def test_categorize_container_name_skills():
+    assert categorize_container_name("ovos_skill_wikihow") == "skills"
+    assert categorize_container_name("ovos_skill_date_time") == "skills"
+    assert categorize_container_name("ovos_core") == "skills"
+
+
+def test_categorize_container_name_audio():
+    assert categorize_container_name("ovos_audio") == "audio"
+
+
+def test_categorize_container_name_voice():
+    assert categorize_container_name("ovos_listener") == "voice"
+
+
+def test_categorize_container_name_bus():
+    assert categorize_container_name("ovos_messagebus") == "bus"
+
+
+def test_categorize_container_name_phal():
+    assert categorize_container_name("ovos_phal") == "phal"
+    assert categorize_container_name("ovos_phal_admin") == "phal"
+
+
+def test_categorize_container_name_gui():
+    assert categorize_container_name("ovos_gui_websocket") == "gui"
+
+
+def test_categorize_container_name_falls_back_to_other():
+    """Real container names seen on a live install that don't map to
+    a known category - ovos_cli (a debug/interactive tool, not a
+    logging service) and ovos_plugin_ggwave (an audio-data-over-sound
+    plugin, not one of the core categories)."""
+    assert categorize_container_name("ovos_cli") == "other"
+    assert categorize_container_name("ovos_plugin_ggwave") == "other"
+
+
 def test_start_container_log_bridges_spawns_one_process_per_container(tmp_path):
     with patch("subprocess.run", return_value=_fake_completed(returncode=0)):
         with patch("subprocess.Popen") as mock_popen:
@@ -190,6 +230,24 @@ def test_start_container_log_bridges_spawns_one_process_per_container(tmp_path):
     assert len(handles) == 2
 
 
+def test_start_container_log_bridges_groups_same_category_containers_into_one_file(tmp_path):
+    """The actual point of this design: on a real ovos-docker install
+    there can be 15-25 individual skill containers - all of them must
+    append to the SAME skills.log, not create 15-25 separate files/
+    checkboxes for what's conceptually one category."""
+    with patch("subprocess.run", return_value=_fake_completed(returncode=0)):
+        with patch("subprocess.Popen") as mock_popen:
+            start_container_log_bridges(
+                ["ovos_skill_wikihow", "ovos_skill_weather", "ovos_skill_wolfie"], tmp_path
+            )
+    # 3 separate `docker logs -f` processes (one per container - each
+    # needs its own subprocess, docker can't merge streams itself)...
+    assert mock_popen.call_count == 3
+    # ...but all writing to the same single file
+    stdout_targets = {call.kwargs["stdout"].name for call in mock_popen.call_args_list}
+    assert stdout_targets == {str(tmp_path / "skills.log")}
+
+
 def test_start_container_log_bridges_uses_docker_logs_dash_f_with_container_name(tmp_path):
     with patch("subprocess.run", return_value=_fake_completed(returncode=0)):
         with patch("subprocess.Popen") as mock_popen: