scietex.log-aggregator-service 0.1.0__tar.gz

scietex_log_aggregator_service-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Bondarenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scietex_log_aggregator_service-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: scietex.log_aggregator_service
+Version: 0.1.0
+Summary: Scietex microservice daemon that aggregates per-worker log streams
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License-Expression: MIT
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.log_aggregator_service/issues
+Project-URL: Homepage, https://github.com/bond-anton/scietex.log_aggregator_service
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scietex.service[valkey]~=5.2.0
+Provides-Extra: dev
+Requires-Dist: tox>=4.45.0; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: ty; extra == "lint"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Dynamic: license-file
+
+# scietex.log_aggregator_service
+
+**scietex.log_aggregator_service** is a `scietex.service` worker that merges the
+per-worker log streams of the configured services into one shared stream. Each
+`scietex.service` worker writes its own stream
+(`scietex:{service}:{instance_id}:log`); this service tails all of them and
+copies every entry into a single target stream (`scietex:log` by default),
+stamping each entry with a `source` field (`{service}:{instance_id}`) so
+consumers can tell which worker emitted it.
+
+The aggregator is the **sole writer** of the target stream, so it owns both the
+`MAXLEN ~` trim and the whole-key `EXPIRE`. The API backend reads that stream
+for the system log viewer and no longer trims it.
+
+**Python ≥ 3.10** · **License: MIT**
+
+## How it works
+
+```
+per-worker log streams                     shared stream                viewer
+scietex:{svc}:{inst}:log  ─┐
+scietex:{svc2}:{inst}:log  ─┤  XREAD (multi-key)   ┌────────────────┐   GET /logs/          ─► LogViewer
+scietex:{svcN}:{inst}:log  ─┘ ───────────────►    │ scietex:log    │   GET /logs/stream (SSE)   (Source col)
+                                                   │ XADD MAXLEN ~  │
+   ▲ each writer owns its stream                   │ EXPIRE ttl     │
+   │ (worker heartbeat refreshes its TTL)          └────────────────┘
+                                                   ▲ single owner
+                                   ┌───────────────┴────────────────┐
+                                   │ LogAggregatorService worker     │
+                                   │ (reads scietex:{agg}:config)    │
+                                   └─────────────────────────────────┘
+```
+
+- A **single supervisor loop** (not one task per stream) tails every source with
+  a multi-key `XREAD`, so the merge is natural and there is no task fan-out.
+- A periodic `SCAN` (`scietex:{service}:*:log`) picks up workers that appear or
+  disappear; the source set is rebuilt in place.
+- The target stream's TTL is refreshed on a timer (Valkey `EXPIRE` sets a TTL on
+  the key; `XADD` does not refresh it).
+- The aggregator's own service is excluded from the source set, so its logs do
+  not loop back into the stream it writes.
+
+## Installation
+
+```bash
+pip install scietex.log_aggregator_service
+```
+
+This pulls in `scietex.service[valkey]` (the worker framework and its Valkey
+transport).
+
+## Quick start
+
+### 1. Write a configuration file
+
+The service reads `log_aggregator.yml` from a `log_aggregator/` subdirectory of
+its config directory. Create it by hand, or let the service generate defaults on
+first run:
+
+```yaml
+source_services:
+  - ModbusService
+exclude_services:
+  - LogAggregatorService
+target_stream: scietex:log
+max_len: 100000
+ttl_seconds: 604800
+batch_size: 200
+block_ms: 1000
+scan_interval: 15.0
+```
+
+### 2. Run the service
+
+```bash
+start-log-aggregator --conf-dir /etc/scietex
+```
+
+The service resolves its config directory automatically when `--conf-dir` is
+omitted. It runs in the foreground until it receives `SIGINT` or `SIGTERM`.
+
+### 3. Register it with the backend
+
+The backend is the config authority: register the service so it can deliver the
+`log_aggregator` section (source services, target stream, `max_len`, `ttl`):
+
+```bash
+curl -X POST http://localhost:8000/api/v1/services/discovered/LogAggregatorService/register
+```
+
+## Configuration at a glance
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `source_services` | `[]` | Service names whose per-worker log streams are aggregated |
+| `exclude_services` | `[]` | Names removed from the source set (self-exclusion) |
+| `target_stream` | `scietex:log` | Shared stream the aggregator writes |
+| `max_len` | `100000` | `MAXLEN ~` applied on each write (`0` disables) |
+| `ttl_seconds` | `604800` | Whole-key TTL refreshed on a timer (`0` disables) |
+| `batch_size` | `200` | Entries per `XREAD` |
+| `block_ms` | `1000` | `XREAD` block timeout |
+| `scan_interval` | `15.0` | Seconds between source-set SCANs |
+
+## Development
+
+Dependencies are managed with **uv**; checks and tests run through **tox**:
+
+```bash
+uv sync --all-extras
+uv run tox                    # format, lint, type, py314
+uv run tox -e py314           # tests only
+```

scietex_log_aggregator_service-0.1.0/README.md

@@ -0,0 +1,112 @@
+# scietex.log_aggregator_service
+
+**scietex.log_aggregator_service** is a `scietex.service` worker that merges the
+per-worker log streams of the configured services into one shared stream. Each
+`scietex.service` worker writes its own stream
+(`scietex:{service}:{instance_id}:log`); this service tails all of them and
+copies every entry into a single target stream (`scietex:log` by default),
+stamping each entry with a `source` field (`{service}:{instance_id}`) so
+consumers can tell which worker emitted it.
+
+The aggregator is the **sole writer** of the target stream, so it owns both the
+`MAXLEN ~` trim and the whole-key `EXPIRE`. The API backend reads that stream
+for the system log viewer and no longer trims it.
+
+**Python ≥ 3.10** · **License: MIT**
+
+## How it works
+
+```
+per-worker log streams                     shared stream                viewer
+scietex:{svc}:{inst}:log  ─┐
+scietex:{svc2}:{inst}:log  ─┤  XREAD (multi-key)   ┌────────────────┐   GET /logs/          ─► LogViewer
+scietex:{svcN}:{inst}:log  ─┘ ───────────────►    │ scietex:log    │   GET /logs/stream (SSE)   (Source col)
+                                                   │ XADD MAXLEN ~  │
+   ▲ each writer owns its stream                   │ EXPIRE ttl     │
+   │ (worker heartbeat refreshes its TTL)          └────────────────┘
+                                                   ▲ single owner
+                                   ┌───────────────┴────────────────┐
+                                   │ LogAggregatorService worker     │
+                                   │ (reads scietex:{agg}:config)    │
+                                   └─────────────────────────────────┘
+```
+
+- A **single supervisor loop** (not one task per stream) tails every source with
+  a multi-key `XREAD`, so the merge is natural and there is no task fan-out.
+- A periodic `SCAN` (`scietex:{service}:*:log`) picks up workers that appear or
+  disappear; the source set is rebuilt in place.
+- The target stream's TTL is refreshed on a timer (Valkey `EXPIRE` sets a TTL on
+  the key; `XADD` does not refresh it).
+- The aggregator's own service is excluded from the source set, so its logs do
+  not loop back into the stream it writes.
+
+## Installation
+
+```bash
+pip install scietex.log_aggregator_service
+```
+
+This pulls in `scietex.service[valkey]` (the worker framework and its Valkey
+transport).
+
+## Quick start
+
+### 1. Write a configuration file
+
+The service reads `log_aggregator.yml` from a `log_aggregator/` subdirectory of
+its config directory. Create it by hand, or let the service generate defaults on
+first run:
+
+```yaml
+source_services:
+  - ModbusService
+exclude_services:
+  - LogAggregatorService
+target_stream: scietex:log
+max_len: 100000
+ttl_seconds: 604800
+batch_size: 200
+block_ms: 1000
+scan_interval: 15.0
+```
+
+### 2. Run the service
+
+```bash
+start-log-aggregator --conf-dir /etc/scietex
+```
+
+The service resolves its config directory automatically when `--conf-dir` is
+omitted. It runs in the foreground until it receives `SIGINT` or `SIGTERM`.
+
+### 3. Register it with the backend
+
+The backend is the config authority: register the service so it can deliver the
+`log_aggregator` section (source services, target stream, `max_len`, `ttl`):
+
+```bash
+curl -X POST http://localhost:8000/api/v1/services/discovered/LogAggregatorService/register
+```
+
+## Configuration at a glance
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `source_services` | `[]` | Service names whose per-worker log streams are aggregated |
+| `exclude_services` | `[]` | Names removed from the source set (self-exclusion) |
+| `target_stream` | `scietex:log` | Shared stream the aggregator writes |
+| `max_len` | `100000` | `MAXLEN ~` applied on each write (`0` disables) |
+| `ttl_seconds` | `604800` | Whole-key TTL refreshed on a timer (`0` disables) |
+| `batch_size` | `200` | Entries per `XREAD` |
+| `block_ms` | `1000` | `XREAD` block timeout |
+| `scan_interval` | `15.0` | Seconds between source-set SCANs |
+
+## Development
+
+Dependencies are managed with **uv**; checks and tests run through **tox**:
+
+```bash
+uv sync --all-extras
+uv run tox                    # format, lint, type, py314
+uv run tox -e py314           # tests only
+```

scietex_log_aggregator_service-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "scietex.log_aggregator_service"
+description = "Scietex microservice daemon that aggregates per-worker log streams"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+authors = [{ name = "Anton Bondarenko", email = "bond.anton@gmail.com" }]
+classifiers = [
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+]
+dependencies = [
+  "scietex.service[valkey]~=5.2.0",
+]
+dynamic = ["version"]
+
+[project.urls]
+"Bug Tracker" = "https://github.com/bond-anton/scietex.log_aggregator_service/issues"
+"Homepage" = "https://github.com/bond-anton/scietex.log_aggregator_service"
+
+[project.scripts]
+start-log-aggregator = "scietex.log_aggregator_service.run_worker:main"
+
+[project.optional-dependencies]
+dev = ["tox>=4.45.0"]
+lint = ["ruff", "ty"]
+test = ["pytest", "pytest-asyncio"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "scietex.log_aggregator_service.version.__version__" }
+
+[tool.setuptools.package-data]
+"scietex.log_aggregator_service" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

scietex_log_aggregator_service-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scietex_log_aggregator_service-0.1.0/src/scietex/log_aggregator_service/__init__.py

@@ -0,0 +1,21 @@
+"""Log Aggregator Service."""
+
+from .aggregator_worker import LogAggregatorWorker
+from .config import (
+    AGGREGATOR_CONFIG_FILE,
+    AGGREGATOR_CONFIG_SUBDIR,
+    AGGREGATOR_SECTION,
+    LogAggregatorSettings,
+    read_aggregator_config,
+)
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "LogAggregatorWorker",
+    "AGGREGATOR_CONFIG_FILE",
+    "AGGREGATOR_CONFIG_SUBDIR",
+    "AGGREGATOR_SECTION",
+    "LogAggregatorSettings",
+    "read_aggregator_config",
+]

scietex_log_aggregator_service-0.1.0/src/scietex/log_aggregator_service/aggregator_worker.py

@@ -0,0 +1,227 @@
+"""Log aggregator worker: a Valkey-backed service that merges worker log streams.
+
+`LogAggregatorWorker` extends `ValkeyWorker` and runs a single supervisor loop
+that tails every per-worker log stream of the configured source services and
+copies each entry into one shared stream. It is the sole writer of that stream,
+so it owns both the ``MAXLEN`` trim and the whole-key ``EXPIRE``.
+
+The loop is a single task (not one task per stream): a multi-key ``XREAD``
+merges all sources naturally, and a periodic ``SCAN`` picks up workers that
+appear or disappear. Each copied entry is stamped with ``source`` =
+``{service}:{instance_id}``, derived from the stream key, so consumers can tell
+which worker emitted it. The aggregator's own service is excluded from the
+source set to prevent its logs from looping back into the stream it writes.
+"""
+
+import asyncio
+import contextlib
+import time
+from collections.abc import Mapping
+from typing import Any, cast
+
+from glide import GlideError, StreamAddOptions, StreamReadOptions, TrimByMaxLen
+from scietex.service import ValkeyWorker, ValkeyWorkerConfig
+
+from .config import AGGREGATOR_SECTION, LogAggregatorSettings, read_aggregator_config
+
+#: Suffix of a per-worker log stream key: ``scietex:{service}:{instance_id}:log``.
+_LOG_STREAM_SUFFIX: str = ":log"
+
+
+class LogAggregatorWorker(ValkeyWorker):
+    """A `ValkeyWorker` that aggregates per-worker log streams into one stream.
+
+    Settings precedence: constructor default < ``log_aggregator.yml`` < framework
+    ``config.yml`` / remote ``log_aggregator`` section. The reader loop starts
+    after `super().initialize()` so the remote apply (which runs the
+    ``log_aggregator`` section hook) has already updated ``self._settings``.
+    """
+
+    def __init__(self, config: ValkeyWorkerConfig | None = None, *, client_factory=None, theme=None) -> None:
+        super().__init__(config, client_factory=client_factory, theme=theme)
+        self._settings: LogAggregatorSettings | None = None
+        self._reader_task: asyncio.Task | None = None
+        self.register_config_settings(AGGREGATOR_SECTION, LogAggregatorSettings, apply=self._apply_settings)
+
+    @property
+    def aggregator_settings(self) -> LogAggregatorSettings | None:
+        """The effective aggregator settings, or `None` before startup."""
+        return self._settings
+
+    async def initialize(self) -> bool:
+        """Load settings, initialize the framework, then start the reader loop.
+
+        The reader loop is started only after `super().initialize()` succeeds, so
+        the remote config apply has already run and ``self._settings`` reflects
+        the effective configuration.
+
+        Returns:
+            `True` if the framework initialized and the reader loop started;
+            `False` on any configuration or startup failure.
+        """
+        try:
+            self._settings = read_aggregator_config(self.conf_dir)
+        except RuntimeError as exc:
+            self.logger.error("Failed to load log aggregator configuration: %s", exc)
+            return False
+
+        if not await super().initialize():
+            return False
+
+        self._reader_task = asyncio.create_task(self._reader_loop(), name="LogAggregatorReader")
+        return True
+
+    async def cleanup(self) -> None:
+        """Cancel the reader loop, then tear down the framework resources."""
+        task, self._reader_task = self._reader_task, None
+        if task is not None:
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        await super().cleanup()
+
+    def _apply_settings(self, settings: LogAggregatorSettings) -> None:
+        """Store remote aggregator settings; the reader loop picks them up.
+
+        The loop detects the settings object identity change and forces a SCAN,
+        so a changed ``source_services`` set is reflected without restarting the
+        task. ``max_len`` and ``ttl_seconds`` apply on the next iteration.
+        """
+        self._settings = settings
+        self.logger.info(
+            "Log aggregator settings applied: %d source service(s), target=%s",
+            len(settings.source_services),
+            settings.target_stream,
+        )
+
+    async def _reader_loop(self) -> None:
+        """Tail every source stream and copy entries into the target stream.
+
+        A single loop owns all sources: ``last_ids`` maps each source stream key
+        to the last entry id read, and a multi-key ``XREAD`` merges them. The
+        source set is refreshed by SCAN on a timer (and immediately when the
+        settings object changes), so workers appearing or disappearing are
+        handled without per-stream tasks. Any iteration error is logged and the
+        loop continues; only cancellation ends it.
+        """
+        last_ids: dict[str, str] = {}
+        settings_seen: LogAggregatorSettings | None = None
+        last_scan = 0.0
+        last_expire = 0.0
+        while True:
+            try:
+                settings = self._settings
+                client = self.client
+                if settings is None or client is None:
+                    await asyncio.sleep(1.0)
+                    continue
+
+                now = time.monotonic()
+                if settings is not settings_seen or now - last_scan >= settings.scan_interval:
+                    await self._refresh_streams(settings, last_ids)
+                    last_scan = now
+                    settings_seen = settings
+
+                if settings.ttl_seconds > 0 and now - last_expire >= max(1.0, settings.ttl_seconds / 3):
+                    # EXPIRE is a no-op until the target stream exists (the first
+                    # XADD creates it), so only advance the timer on success;
+                    # otherwise the long interval would delay the TTL until the
+                    # next window even though the stream now exists.
+                    if await client.expire(settings.target_stream, settings.ttl_seconds):
+                        last_expire = now
+
+                if not last_ids:
+                    await asyncio.sleep(1.0)
+                    continue
+
+                entries = await client.xread(
+                    keys_and_ids=cast("Mapping[str | bytes, str | bytes]", last_ids),
+                    options=StreamReadOptions(count=settings.batch_size, block_ms=settings.block_ms),
+                )
+                for key_bytes, group in (entries or {}).items():
+                    key = key_bytes.decode() if isinstance(key_bytes, bytes) else str(key_bytes)
+                    for entry_id, fields in group.items():
+                        await self._copy(settings, key, fields)
+                        last_ids[key] = entry_id.decode() if isinstance(entry_id, bytes) else str(entry_id)
+            except asyncio.CancelledError:
+                raise
+            except GlideError as exc:
+                # Mirror the framework transport: report to TransportHealth so
+                # the single reconnect owner recovers the shared client, then
+                # retry. GlideError covers ClosingError too, which the framework
+                # raises when its reconnect closes the client mid-read.
+                self.logger.debug("Log aggregation read failed: %s", exc)
+                self._health.report_failure(exc)
+                await self._health.recover()
+                await asyncio.sleep(1.0)
+            except Exception:
+                self.logger.exception("Log aggregation iteration failed; continuing")
+                await asyncio.sleep(1.0)
+
+    async def _refresh_streams(self, settings: LogAggregatorSettings, last_ids: dict[str, str]) -> None:
+        """Rebuild ``last_ids`` from a SCAN of the configured source services.
+
+        Each source service contributes keys matching ``scietex:{service}:*:log``.
+        Keys that vanished are dropped; new keys start from ``"0"`` so their
+        backlog is copied. The dict is mutated in place so the reader loop keeps
+        a single reference.
+        """
+        client = self.client
+        if client is None:
+            return
+        excluded = set(settings.exclude_services)
+        found: set[str] = set()
+        for service in settings.source_services:
+            if service in excluded:
+                continue
+            cursor: bytes = b"0"
+            while True:
+                result = await client.scan(cursor, match=f"scietex:{service}:*{_LOG_STREAM_SUFFIX}", count=100)
+                cursor = cast(bytes, result[0])
+                for name in cast("list[bytes]", result[1]):
+                    found.add(name.decode() if isinstance(name, bytes) else str(name))
+                if cursor == b"0":
+                    break
+        for key in list(last_ids):
+            if key not in found:
+                del last_ids[key]
+        for key in found:
+            last_ids.setdefault(key, "0")
+
+    async def _copy(self, settings: LogAggregatorSettings, source_key: str, fields: Any) -> None:
+        """Copy one source entry into the target stream, stamped with ``source``.
+
+        ``fields`` is the Glide ``list[tuple[bytes, bytes]]`` payload. The
+        ``source`` label is derived from the stream key
+        (``scietex:a:1:log`` -> ``a:1``) and overrides any existing field, so a
+        consumer always sees the emitting worker. ``MAXLEN ~`` is applied on the
+        write when ``max_len > 0``.
+        """
+        client = self.client
+        if client is None:
+            return
+        decoded: dict[str, str] = {}
+        for pair in fields:
+            name = pair[0].decode() if isinstance(pair[0], bytes) else str(pair[0])
+            value = pair[1].decode() if isinstance(pair[1], bytes) else str(pair[1])
+            decoded[name] = value
+        decoded["source"] = _source_label(source_key)
+        options = (
+            StreamAddOptions(trim=TrimByMaxLen(exact=False, threshold=settings.max_len, limit=None))
+            if settings.max_len > 0
+            else None
+        )
+        await client.xadd(settings.target_stream, list(decoded.items()), options=options)
+
+
+def _source_label(stream_key: str) -> str:
+    """Derive ``{service}:{instance_id}`` from a per-worker log stream key.
+
+    ``scietex:{service}:{instance_id}:log`` -> ``{service}:{instance_id}``. A key
+    that does not match the expected shape is returned unchanged, so a
+    misconfigured source still produces a usable label.
+    """
+    parts = stream_key.split(":")
+    if len(parts) == 4 and parts[0] == "scietex" and parts[3] == "log":
+        return f"{parts[1]}:{parts[2]}"
+    return stream_key

scietex_log_aggregator_service-0.1.0/src/scietex/log_aggregator_service/config.py

@@ -0,0 +1,108 @@
+"""Configuration models and YAML loader for the log aggregator service.
+
+`LogAggregatorSettings` is the service-owned bootstrap snapshot stored in
+``log_aggregator.yml`` under the config directory. It is kept deliberately thin:
+it names the source services to aggregate, the target stream, and the retention
+policy the aggregator enforces on that stream.
+
+The aggregator is the sole writer of the target stream, so it owns both the
+``MAXLEN`` trim and the whole-key ``EXPIRE``. The API delivers these values as
+the remote ``log_aggregator`` section; the local YAML is only the bootstrap
+fallback used before the first remote apply.
+"""
+
+from pathlib import Path
+
+import msgspec
+
+#: Remote-config section name the settings are registered under.
+AGGREGATOR_SECTION: str = "log_aggregator"
+
+#: Subdirectory under the shared config dir that namespaces this service's
+#: files. The framework's ``config.yml`` snapshot and the service-owned
+#: ``log_aggregator.yml`` both live here, so services sharing one config dir
+#: (the framework resolves a single dir for all scietex services) cannot collide.
+AGGREGATOR_CONFIG_SUBDIR: str = "log_aggregator"
+
+#: Filename of the service-owned bootstrap snapshot in the config subdirectory.
+AGGREGATOR_CONFIG_FILE: str = "log_aggregator.yml"
+
+
+class LogAggregatorSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Top-level log aggregator settings.
+
+    ``source_services`` lists the service names whose per-worker log streams are
+    aggregated; ``exclude_services`` removes names from that set (the backend
+    sets it to the aggregator's own service name to prevent self-ingestion).
+    ``target_stream`` is the shared stream the aggregator writes; ``max_len`` and
+    ``ttl_seconds`` are the retention policy it enforces on it. A ``max_len`` or
+    ``ttl_seconds`` of ``0`` disables that half of the policy.
+    """
+
+    source_services: list[str] = msgspec.field(default_factory=list)
+    exclude_services: list[str] = msgspec.field(default_factory=list)
+    target_stream: str = "scietex:log"
+    max_len: int = 100_000
+    ttl_seconds: int = 604800
+    batch_size: int = 200
+    block_ms: int = 1000
+    scan_interval: float = 15.0
+
+
+def read_aggregator_config(conf_dir: Path | None, *, create_default: bool = True) -> LogAggregatorSettings:
+    """Read aggregator settings from ``log_aggregator/log_aggregator.yml``.
+
+    The service's files are namespaced in a ``log_aggregator/`` subdirectory so
+    they do not collide with other services sharing the framework's single config
+    dir. Mirrors `read_modbus_config`: the file (and, when missing, its
+    directory) is only created when ``create_default=True`` (the bootstrap path).
+    A ``None`` or non-directory ``conf_dir``, a missing file/directory with
+    ``create_default=False``, or an unparseable file each raise `RuntimeError`.
+    An existing-but-invalid file is left untouched regardless of ``create_default``.
+
+    Args:
+        conf_dir: Path to the configuration directory.
+        create_default: Whether to create the directory and write a default
+            ``log_aggregator.yml`` when missing. Default ``True``.
+
+    Returns:
+        A `LogAggregatorSettings` loaded from ``log_aggregator.yml`` or defaults.
+
+    Raises:
+        RuntimeError: If ``conf_dir`` is ``None`` or not a directory, the file
+            is missing with ``create_default=False``, or the file cannot be parsed.
+    """
+    if not isinstance(conf_dir, Path):
+        raise RuntimeError("Configuration dir was not set!")
+    service_dir = conf_dir / AGGREGATOR_CONFIG_SUBDIR
+    if not service_dir.exists():
+        if create_default:
+            try:
+                service_dir.mkdir(parents=True, exist_ok=True)
+            except Exception as exc:
+                raise RuntimeError(f"Failed to create configuration directory {service_dir}!") from exc
+        else:
+            raise RuntimeError(
+                f"Configuration directory {service_dir} does not exist and create_default=False (no default generated)."
+            )
+    elif not service_dir.is_dir():
+        raise RuntimeError(f"Provided configuration directory path {service_dir} is not a directory!")
+    config_yml = service_dir.joinpath(AGGREGATOR_CONFIG_FILE)
+    if not config_yml.exists():
+        if create_default:
+            settings = LogAggregatorSettings()
+            with open(config_yml, "wb") as f:
+                f.write(msgspec.yaml.encode(settings))
+            return settings
+        raise RuntimeError(
+            f"Log aggregator configuration file {config_yml} does not exist and create_default=False "
+            "(pass create_default=True to generate defaults)."
+        )
+    try:
+        with open(config_yml, "rb") as f:
+            return msgspec.yaml.decode(f.read(), type=LogAggregatorSettings, strict=True)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Failed to parse log aggregator configuration file {config_yml}. "
+            "Fix the file or remove it to regenerate defaults."
+        ) from exc

scietex_log_aggregator_service-0.1.0/src/scietex/log_aggregator_service/run_worker.py

@@ -0,0 +1,74 @@
+"""Entry point to run the log aggregator worker as a foreground daemon."""
+
+import argparse
+import asyncio
+import os
+
+from scietex.service import ValkeyWorkerConfig
+
+from .aggregator_worker import LogAggregatorWorker
+from .config import AGGREGATOR_CONFIG_SUBDIR
+from .version import __version__
+
+#: Environment fallbacks for the CLI options, so a container can be configured
+#: with ``-e`` without overriding its command. An explicit CLI flag still wins.
+ENV_SERVICE_NAME: str = "SCIETEX_SERVICE_NAME"
+ENV_LOGGING_LEVEL: str = "SCIETEX_LOGGING_LEVEL"
+
+DEFAULT_SERVICE_NAME: str = "LogAggregatorService"
+DEFAULT_LOGGING_LEVEL: str = "INFO"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser with environment-variable fallbacks.
+
+    ``--conf-dir`` defaults to ``None`` so the framework's ``prepare_conf_dir``
+    resolves it (it already honors ``SCIETEX_CONFIG_DIR``); the other options
+    fall back to their environment variables when no flag is given.
+    """
+    parser = argparse.ArgumentParser(description="Run the log aggregator worker.")
+    parser.add_argument("--conf-dir", default=None, help="Configuration directory (default: auto-resolved)")
+    parser.add_argument(
+        "--service-name",
+        default=os.environ.get(ENV_SERVICE_NAME, DEFAULT_SERVICE_NAME),
+        help=f"Service name (default: ${ENV_SERVICE_NAME} or {DEFAULT_SERVICE_NAME})",
+    )
+    parser.add_argument(
+        "--logging-level",
+        default=os.environ.get(ENV_LOGGING_LEVEL, DEFAULT_LOGGING_LEVEL),
+        help=f"Logging level (default: ${ENV_LOGGING_LEVEL} or {DEFAULT_LOGGING_LEVEL})",
+    )
+    return parser
+
+
+def _build_config(args: argparse.Namespace) -> ValkeyWorkerConfig:
+    """Build the worker config from parsed CLI arguments."""
+    return ValkeyWorkerConfig(
+        service_name=args.service_name,
+        version=__version__,
+        conf_dir=args.conf_dir,
+        logging_level=args.logging_level,
+        remote_config_enabled=True,
+        valkey_config=None,
+        # Namespace the framework snapshot under the same subdir as
+        # log_aggregator.yml, so services sharing one config dir cannot clobber
+        # each other's config.
+        config_file=f"{AGGREGATOR_CONFIG_SUBDIR}/config.yml",
+    )
+
+
+def main() -> None:
+    """Parse CLI arguments and run the aggregator worker until exit is requested."""
+    args = _build_parser().parse_args()
+    config = _build_config(args)
+
+    async def run() -> None:
+        worker = LogAggregatorWorker(config)
+        await worker.start()
+        await worker.events["exit"].wait()
+
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

scietex_log_aggregator_service-0.1.0/src/scietex/log_aggregator_service/version.py

@@ -0,0 +1,3 @@
+"""Version of the `scietex.log_aggregator_service` package"""
+
+__version__ = "0.1.0"

scietex_log_aggregator_service-0.1.0/src/scietex.log_aggregator_service.egg-info/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: scietex.log_aggregator_service
+Version: 0.1.0
+Summary: Scietex microservice daemon that aggregates per-worker log streams
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License-Expression: MIT
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.log_aggregator_service/issues
+Project-URL: Homepage, https://github.com/bond-anton/scietex.log_aggregator_service
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scietex.service[valkey]~=5.2.0
+Provides-Extra: dev
+Requires-Dist: tox>=4.45.0; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: ty; extra == "lint"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Dynamic: license-file
+
+# scietex.log_aggregator_service
+
+**scietex.log_aggregator_service** is a `scietex.service` worker that merges the
+per-worker log streams of the configured services into one shared stream. Each
+`scietex.service` worker writes its own stream
+(`scietex:{service}:{instance_id}:log`); this service tails all of them and
+copies every entry into a single target stream (`scietex:log` by default),
+stamping each entry with a `source` field (`{service}:{instance_id}`) so
+consumers can tell which worker emitted it.
+
+The aggregator is the **sole writer** of the target stream, so it owns both the
+`MAXLEN ~` trim and the whole-key `EXPIRE`. The API backend reads that stream
+for the system log viewer and no longer trims it.
+
+**Python ≥ 3.10** · **License: MIT**
+
+## How it works
+
+```
+per-worker log streams                     shared stream                viewer
+scietex:{svc}:{inst}:log  ─┐
+scietex:{svc2}:{inst}:log  ─┤  XREAD (multi-key)   ┌────────────────┐   GET /logs/          ─► LogViewer
+scietex:{svcN}:{inst}:log  ─┘ ───────────────►    │ scietex:log    │   GET /logs/stream (SSE)   (Source col)
+                                                   │ XADD MAXLEN ~  │
+   ▲ each writer owns its stream                   │ EXPIRE ttl     │
+   │ (worker heartbeat refreshes its TTL)          └────────────────┘
+                                                   ▲ single owner
+                                   ┌───────────────┴────────────────┐
+                                   │ LogAggregatorService worker     │
+                                   │ (reads scietex:{agg}:config)    │
+                                   └─────────────────────────────────┘
+```
+
+- A **single supervisor loop** (not one task per stream) tails every source with
+  a multi-key `XREAD`, so the merge is natural and there is no task fan-out.
+- A periodic `SCAN` (`scietex:{service}:*:log`) picks up workers that appear or
+  disappear; the source set is rebuilt in place.
+- The target stream's TTL is refreshed on a timer (Valkey `EXPIRE` sets a TTL on
+  the key; `XADD` does not refresh it).
+- The aggregator's own service is excluded from the source set, so its logs do
+  not loop back into the stream it writes.
+
+## Installation
+
+```bash
+pip install scietex.log_aggregator_service
+```
+
+This pulls in `scietex.service[valkey]` (the worker framework and its Valkey
+transport).
+
+## Quick start
+
+### 1. Write a configuration file
+
+The service reads `log_aggregator.yml` from a `log_aggregator/` subdirectory of
+its config directory. Create it by hand, or let the service generate defaults on
+first run:
+
+```yaml
+source_services:
+  - ModbusService
+exclude_services:
+  - LogAggregatorService
+target_stream: scietex:log
+max_len: 100000
+ttl_seconds: 604800
+batch_size: 200
+block_ms: 1000
+scan_interval: 15.0
+```
+
+### 2. Run the service
+
+```bash
+start-log-aggregator --conf-dir /etc/scietex
+```
+
+The service resolves its config directory automatically when `--conf-dir` is
+omitted. It runs in the foreground until it receives `SIGINT` or `SIGTERM`.
+
+### 3. Register it with the backend
+
+The backend is the config authority: register the service so it can deliver the
+`log_aggregator` section (source services, target stream, `max_len`, `ttl`):
+
+```bash
+curl -X POST http://localhost:8000/api/v1/services/discovered/LogAggregatorService/register
+```
+
+## Configuration at a glance
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `source_services` | `[]` | Service names whose per-worker log streams are aggregated |
+| `exclude_services` | `[]` | Names removed from the source set (self-exclusion) |
+| `target_stream` | `scietex:log` | Shared stream the aggregator writes |
+| `max_len` | `100000` | `MAXLEN ~` applied on each write (`0` disables) |
+| `ttl_seconds` | `604800` | Whole-key TTL refreshed on a timer (`0` disables) |
+| `batch_size` | `200` | Entries per `XREAD` |
+| `block_ms` | `1000` | `XREAD` block timeout |
+| `scan_interval` | `15.0` | Seconds between source-set SCANs |
+
+## Development
+
+Dependencies are managed with **uv**; checks and tests run through **tox**:
+
+```bash
+uv sync --all-extras
+uv run tox                    # format, lint, type, py314
+uv run tox -e py314           # tests only
+```

scietex_log_aggregator_service-0.1.0/src/scietex.log_aggregator_service.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/scietex.log_aggregator_service.egg-info/PKG-INFO
+src/scietex.log_aggregator_service.egg-info/SOURCES.txt
+src/scietex.log_aggregator_service.egg-info/dependency_links.txt
+src/scietex.log_aggregator_service.egg-info/entry_points.txt
+src/scietex.log_aggregator_service.egg-info/requires.txt
+src/scietex.log_aggregator_service.egg-info/top_level.txt
+src/scietex/log_aggregator_service/__init__.py
+src/scietex/log_aggregator_service/aggregator_worker.py
+src/scietex/log_aggregator_service/config.py
+src/scietex/log_aggregator_service/py.typed
+src/scietex/log_aggregator_service/run_worker.py
+src/scietex/log_aggregator_service/version.py
+tests/test_aggregator_worker.py
+tests/test_config.py
+tests/test_run_worker.py

scietex_log_aggregator_service-0.1.0/src/scietex.log_aggregator_service.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scietex_log_aggregator_service-0.1.0/src/scietex.log_aggregator_service.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+start-log-aggregator = scietex.log_aggregator_service.run_worker:main

scietex_log_aggregator_service-0.1.0/src/scietex.log_aggregator_service.egg-info/requires.txt

@@ -0,0 +1,12 @@
+scietex.service[valkey]~=5.2.0
+
+[dev]
+tox>=4.45.0
+
+[lint]
+ruff
+ty
+
+[test]
+pytest
+pytest-asyncio

scietex_log_aggregator_service-0.1.0/src/scietex.log_aggregator_service.egg-info/top_level.txt

@@ -0,0 +1 @@
+scietex

scietex_log_aggregator_service-0.1.0/tests/test_aggregator_worker.py

@@ -0,0 +1,154 @@
+"""Tests for the LogAggregatorWorker reader loop, copy, and config apply hook."""
+
+import asyncio
+import contextlib
+import logging
+from unittest.mock import AsyncMock
+
+import pytest
+from scietex.service import ValkeyWorker, ValkeyWorkerConfig
+
+from scietex.log_aggregator_service.aggregator_worker import LogAggregatorWorker, _source_label
+from scietex.log_aggregator_service.config import LogAggregatorSettings
+
+
+def _make_worker(tmp_path) -> LogAggregatorWorker:
+    """Build a worker with a real conf_dir and no remote-config handlers."""
+    return LogAggregatorWorker(
+        ValkeyWorkerConfig(
+            service_name="test",
+            conf_dir=str(tmp_path),
+            remote_config_enabled=False,
+        )
+    )
+
+
+def test_source_label_derives_service_and_instance() -> None:
+    """A per-worker stream key maps to ``{service}:{instance_id}``."""
+    assert _source_label("scietex:modbus:abc123:log") == "modbus:abc123"
+
+
+def test_source_label_passes_through_unexpected_keys() -> None:
+    """A key that does not match the expected shape is returned unchanged."""
+    assert _source_label("scietex:log") == "scietex:log"
+    assert _source_label("other:modbus:abc:log") == "other:modbus:abc:log"
+
+
+@pytest.mark.asyncio
+async def test_cleanup_safe_when_never_started(tmp_path) -> None:
+    """cleanup() is a no-op when the reader loop was never started."""
+    worker = _make_worker(tmp_path)
+
+    await worker.cleanup()
+
+    assert worker.aggregator_settings is None
+
+
+def test_apply_hook_stores_settings(tmp_path, caplog) -> None:
+    """The apply hook stores the settings and logs the source count."""
+    worker = _make_worker(tmp_path)
+    settings = LogAggregatorSettings(source_services=["ModbusService"])
+
+    with caplog.at_level(logging.INFO):
+        worker._apply_settings(settings)
+
+    assert worker.aggregator_settings is settings
+    assert any("settings applied" in record.message for record in caplog.records)
+
+
+@pytest.mark.asyncio
+async def test_copy_stamps_source_and_applies_maxlen(tmp_path) -> None:
+    """_copy decodes fields, stamps source, and passes MAXLEN on the write."""
+    worker = _make_worker(tmp_path)
+    client = AsyncMock()
+    worker._client = client
+    settings = LogAggregatorSettings(max_len=500)
+
+    await worker._copy(
+        settings,
+        "scietex:modbus:abc123:log",
+        [(b"level", b"INF"), (b"message", b"boot"), (b"name", b"modbus")],
+    )
+
+    client.xadd.assert_awaited_once()
+    args, kwargs = client.xadd.await_args
+    assert args[0] == "scietex:log"
+    fields = dict(args[1])
+    assert fields["source"] == "modbus:abc123"
+    assert fields["message"] == "boot"
+    trim = kwargs["options"].trim
+    assert trim.threshold == 500
+
+
+@pytest.mark.asyncio
+async def test_copy_omits_trim_when_maxlen_disabled(tmp_path) -> None:
+    """A max_len of 0 leaves the stream unbounded (no trim option)."""
+    worker = _make_worker(tmp_path)
+    client = AsyncMock()
+    worker._client = client
+    settings = LogAggregatorSettings(max_len=0)
+
+    await worker._copy(settings, "scietex:modbus:abc123:log", [(b"message", b"boot")])
+
+    _, kwargs = client.xadd.await_args
+    assert kwargs["options"] is None
+
+
+@pytest.mark.asyncio
+async def test_refresh_streams_prunes_vanished_and_excludes_self(tmp_path) -> None:
+    """SCAN results replace the source set; excluded services are skipped."""
+    worker = _make_worker(tmp_path)
+    client = AsyncMock()
+    worker._client = client
+    client.scan.return_value = (b"0", [b"scietex:modbus:abc123:log"])
+    settings = LogAggregatorSettings(
+        source_services=["ModbusService", "LogAggregatorService"],
+        exclude_services=["LogAggregatorService"],
+    )
+    last_ids = {"scietex:modbus:gone:log": "5-0"}
+
+    await worker._refresh_streams(settings, last_ids)
+
+    assert last_ids == {"scietex:modbus:abc123:log": "0"}
+    # Only the non-excluded service is scanned.
+    assert client.scan.await_count == 1
+    assert client.scan.await_args.kwargs["match"] == "scietex:ModbusService:*:log"
+
+
+@pytest.mark.asyncio
+async def test_reader_loop_retries_expire_until_stream_exists(tmp_path) -> None:
+    """EXPIRE is retried each iteration until it succeeds (stream created)."""
+    worker = _make_worker(tmp_path)
+    client = AsyncMock()
+    worker._client = client
+    worker._settings = LogAggregatorSettings(source_services=["ModbusService"], ttl_seconds=3, scan_interval=0.0)
+    client.scan.return_value = (b"0", [b"scietex:ModbusService:abc:log"])
+    client.xread.return_value = None
+    # First EXPIRE misses (stream absent), second succeeds.
+    client.expire.side_effect = [False, True, True, True]
+
+    task = asyncio.create_task(worker._reader_loop())
+    await asyncio.sleep(0.2)
+    task.cancel()
+    with contextlib.suppress(asyncio.CancelledError):
+        await task
+
+    assert client.expire.await_count >= 2
+
+
+@pytest.mark.asyncio
+async def test_initialize_fails_on_bad_config(tmp_path, monkeypatch) -> None:
+    """A config load failure returns False without starting the reader loop."""
+
+    async def fake_initialize(self) -> bool:
+        return True
+
+    monkeypatch.setattr(ValkeyWorker, "initialize", fake_initialize)
+    worker = _make_worker(tmp_path)
+    monkeypatch.setattr(
+        "scietex.log_aggregator_service.aggregator_worker.read_aggregator_config",
+        lambda *a, **k: (_ for _ in ()).throw(RuntimeError("bad config")),
+    )
+
+    assert await worker.initialize() is False
+    assert worker._reader_task is None

scietex_log_aggregator_service-0.1.0/tests/test_config.py

@@ -0,0 +1,84 @@
+"""Tests for the log aggregator configuration models and YAML loader."""
+
+from pathlib import Path
+
+import pytest
+
+from scietex.log_aggregator_service.config import (
+    AGGREGATOR_CONFIG_FILE,
+    AGGREGATOR_CONFIG_SUBDIR,
+    LogAggregatorSettings,
+    read_aggregator_config,
+)
+
+
+def _config_path(conf_dir: Path) -> Path:
+    """The namespaced path the loader reads and writes."""
+    return conf_dir / AGGREGATOR_CONFIG_SUBDIR / AGGREGATOR_CONFIG_FILE
+
+
+def test_defaults_are_sane() -> None:
+    """The default settings aggregate nothing and target the shared stream."""
+    settings = LogAggregatorSettings()
+
+    assert settings.source_services == []
+    assert settings.exclude_services == []
+    assert settings.target_stream == "scietex:log"
+    assert settings.max_len == 100_000
+    assert settings.ttl_seconds == 604800
+
+
+def test_read_aggregator_config_writes_defaults_when_missing(tmp_path: Path) -> None:
+    """A missing file is created under the subdir with default settings."""
+    settings = read_aggregator_config(tmp_path)
+
+    assert settings == LogAggregatorSettings()
+    assert _config_path(tmp_path).is_file()
+
+
+def test_read_aggregator_config_malformed_raises_and_leaves_file(tmp_path: Path) -> None:
+    """An unparseable file raises RuntimeError and is left untouched."""
+    path = _config_path(tmp_path)
+    path.parent.mkdir(parents=True)
+    path.write_text("unterminated: [flow\n")
+
+    with pytest.raises(RuntimeError):
+        read_aggregator_config(tmp_path)
+
+    assert path.read_text() == "unterminated: [flow\n"
+
+
+def test_read_aggregator_config_none_dir_raises() -> None:
+    """A None conf_dir is rejected with RuntimeError."""
+    with pytest.raises(RuntimeError):
+        read_aggregator_config(None)
+
+
+def test_read_aggregator_config_missing_without_create_raises(tmp_path: Path) -> None:
+    """A missing file with create_default=False raises and writes nothing."""
+    with pytest.raises(RuntimeError):
+        read_aggregator_config(tmp_path, create_default=False)
+
+    assert not _config_path(tmp_path).exists()
+
+
+def test_read_aggregator_config_roundtrips_values(tmp_path: Path) -> None:
+    """Explicit values survive a write/read round-trip."""
+    path = _config_path(tmp_path)
+    path.parent.mkdir(parents=True)
+    path.write_text(
+        "source_services:\n"
+        "  - ModbusService\n"
+        "exclude_services:\n"
+        "  - LogAggregatorService\n"
+        "target_stream: scietex:log\n"
+        "max_len: 500\n"
+        "ttl_seconds: 60\n"
+    )
+
+    settings = read_aggregator_config(tmp_path)
+
+    assert settings.source_services == ["ModbusService"]
+    assert settings.exclude_services == ["LogAggregatorService"]
+    assert settings.max_len == 500
+    assert settings.ttl_seconds == 60

scietex_log_aggregator_service-0.1.0/tests/test_run_worker.py

@@ -0,0 +1,70 @@
+"""Tests for the entry point's CLI/env-var configuration."""
+
+from scietex.log_aggregator_service.config import AGGREGATOR_CONFIG_SUBDIR
+from scietex.log_aggregator_service.run_worker import (
+    DEFAULT_LOGGING_LEVEL,
+    DEFAULT_SERVICE_NAME,
+    ENV_LOGGING_LEVEL,
+    ENV_SERVICE_NAME,
+    _build_config,
+    _build_parser,
+)
+from scietex.log_aggregator_service.version import __version__
+
+
+def test_defaults_when_no_env_or_flags(monkeypatch) -> None:
+    """Without env vars or flags, the built-in defaults apply."""
+    monkeypatch.delenv(ENV_SERVICE_NAME, raising=False)
+    monkeypatch.delenv(ENV_LOGGING_LEVEL, raising=False)
+
+    args = _build_parser().parse_args([])
+
+    assert args.service_name == DEFAULT_SERVICE_NAME
+    assert args.logging_level == DEFAULT_LOGGING_LEVEL
+    assert args.conf_dir is None
+
+
+def test_env_vars_supply_defaults(monkeypatch) -> None:
+    """Environment variables override the built-in defaults."""
+    monkeypatch.setenv(ENV_SERVICE_NAME, "FromEnv")
+    monkeypatch.setenv(ENV_LOGGING_LEVEL, "DEBUG")
+
+    args = _build_parser().parse_args([])
+
+    assert args.service_name == "FromEnv"
+    assert args.logging_level == "DEBUG"
+
+
+def test_cli_flags_win_over_env(monkeypatch) -> None:
+    """An explicit CLI flag takes precedence over the environment."""
+    monkeypatch.setenv(ENV_SERVICE_NAME, "FromEnv")
+    monkeypatch.setenv(ENV_LOGGING_LEVEL, "DEBUG")
+
+    args = _build_parser().parse_args(["--service-name", "FromFlag", "--logging-level", "WARNING"])
+
+    assert args.service_name == "FromFlag"
+    assert args.logging_level == "WARNING"
+
+
+def test_build_config_namespaces_framework_snapshot(monkeypatch) -> None:
+    """The framework snapshot is namespaced under the aggregator subdir."""
+    monkeypatch.delenv(ENV_SERVICE_NAME, raising=False)
+    monkeypatch.delenv(ENV_LOGGING_LEVEL, raising=False)
+    args = _build_parser().parse_args([])
+
+    config = _build_config(args)
+
+    assert config.config_file == f"{AGGREGATOR_CONFIG_SUBDIR}/config.yml"
+    assert config.remote_config_enabled is True
+    assert config.valkey_config is None
+
+
+def test_build_config_reports_package_version(monkeypatch) -> None:
+    """The worker reports its own package version, not the framework default."""
+    monkeypatch.delenv(ENV_SERVICE_NAME, raising=False)
+    monkeypatch.delenv(ENV_LOGGING_LEVEL, raising=False)
+    args = _build_parser().parse_args([])
+
+    config = _build_config(args)
+
+    assert config.version == __version__