nexus-queue 0.1.1__tar.gz → 0.1.2__tar.gz

{nexus_queue-0.1.1 → nexus_queue-0.1.2}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.2](https://github.com/Zetesis-Labs/PayloadAgents/compare/nexus-queue-v0.1.1...nexus-queue-v0.1.2) (2026-06-17)
+
+
+### Features
+
+* **nexus-queue:** serve worker Prometheus metrics over HTTP ([#100](https://github.com/Zetesis-Labs/PayloadAgents/issues/100)) ([cb5af8a](https://github.com/Zetesis-Labs/PayloadAgents/commit/cb5af8aaa944681358175e425ef88b2ee9e282be))
+
 ## [0.1.1](https://github.com/Zetesis-Labs/PayloadAgents/compare/nexus-queue-v0.1.0...nexus-queue-v0.1.1) (2026-06-17)
 
 

{nexus_queue-0.1.1 → nexus_queue-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexus-queue
-Version: 0.1.1
+Version: 0.1.2
 Summary: Nexus-Queue — portable taskiq + Redis Streams worker runtime: namespaced streams, versioned envelope, ports-and-adapters, retry/DLQ/idempotency/tracing/metrics middleware.
 Project-URL: Homepage, https://github.com/Zetesis-Labs/PayloadAgents
 Project-URL: Repository, https://github.com/Zetesis-Labs/PayloadAgents

{nexus_queue-0.1.1 → nexus_queue-0.1.2}/nexus_queue/config.py

@@ -69,6 +69,21 @@ class RuntimeConfig(BaseModel):
         description="Approx MAXLEN for the dead-letter stream; 0 = unbounded.",
     )
 
+    # ── Observability ──────────────────────────────────────────────────────
+    metrics_port: int | None = Field(
+        default=None,
+        gt=0,
+        lt=65_536,
+        description=(
+            "If set, the worker serves Prometheus metrics on this port via an "
+            "in-process HTTP server (scrape target for a ServiceMonitor). The "
+            "taskiq worker has no HTTP server otherwise, so its consume counters "
+            "are invisible without this. Run the worker single-process "
+            "(taskiq --workers 1) and scale by pods, or the port will collide. "
+            "None disables it."
+        ),
+    )
+
     # ── Logging ────────────────────────────────────────────────────────────
     log_level: str = Field(default="INFO")
 

{nexus_queue-0.1.1 → nexus_queue-0.1.2}/nexus_queue/lifecycle.py

@@ -11,12 +11,15 @@ import logging
 
 import redis.asyncio as aioredis
 import structlog
+from prometheus_client import start_http_server
 from taskiq import AsyncBroker, TaskiqEvents, TaskiqState
 
 from nexus_queue.config import RuntimeConfig
 from nexus_queue.delayed import DelayedRetryPoller
 from nexus_queue.naming import idempotency_redis_key
 
+logger = structlog.get_logger("nexus_queue.lifecycle")
+
 
 class IdempotencyStore:
     """Redis mark-done dedup keyed by the message's ``nq_idem`` label.
@@ -71,6 +74,28 @@ def configure_logging(config: RuntimeConfig) -> None:
     )
 
 
+def _start_metrics_server(config: RuntimeConfig) -> None:
+    """Serve the Prometheus registry over HTTP from the worker process.
+
+    The consume counters/histogram live in this process; the kicker is a
+    separate pod with its own registry, so without this the worker's metrics
+    have no scrape endpoint. Best-effort: a metrics-server failure (e.g. a
+    port collision when mistakenly run multi-process) must never take the
+    worker down."""
+    if config.metrics_port is None:
+        return
+    try:
+        start_http_server(config.metrics_port)
+        logger.info("metrics-server-started", port=config.metrics_port)
+    except OSError as exc:
+        logger.warning(
+            "metrics-server-failed",
+            port=config.metrics_port,
+            error=str(exc),
+            hint="run the worker single-process (taskiq --workers 1)",
+        )
+
+
 def register_lifecycle(
     broker: AsyncBroker,
     config: RuntimeConfig,
@@ -89,6 +114,7 @@ def register_lifecycle(
     async def _startup(state: TaskiqState) -> None:  # pyright: ignore[reportUnusedFunction]
         state.nexus_config = config
         state.nexus_adapters = adapters
+        _start_metrics_server(config)
         store = IdempotencyStore(config)
         await store.startup()
         state.nexus_idempotency = store

{nexus_queue-0.1.1 → nexus_queue-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nexus-queue"
-version = "0.1.1"
+version = "0.1.2"
 description = "Nexus-Queue — portable taskiq + Redis Streams worker runtime: namespaced streams, versioned envelope, ports-and-adapters, retry/DLQ/idempotency/tracing/metrics middleware."
 requires-python = ">=3.12"
 readme = "README.md"