by-framework 0.2.2.dev14__py3-none-any.whl → 0.2.2.dev16__py3-none-any.whl

by_framework/metrics/catalog.py

@@ -367,6 +367,60 @@ _CATALOG: dict[str, MetricDefinition] = {
             "Instrumentation reliability signal pinpointing exporter failures."
         ),
     ),
+    # Self-monitoring for the background collector in metrics/collector.py.
+    # Exactly one process holds its Redis lock and writes history points, so
+    # these answer "is anyone still collecting?" — a gap here means the
+    # dashboards go stale silently rather than erroring.
+    "by_framework_metrics_collector_cycles_total": MetricDefinition(
+        name="by_framework_metrics_collector_cycles_total",
+        kind=MetricKind.COUNTER,
+        unit=MetricUnit.NONE,
+        labels=("result",),
+        description=(
+            "Metrics collector cycles by result "
+            "(success, snapshot_failed, lock_skipped, disabled)."
+        ),
+        interpretation=(
+            "Collector health signal: only the lock holder reports success, so "
+            "lock_skipped dominating across a fleet is expected."
+        ),
+    ),
+    "by_framework_metrics_collector_snapshot_duration_ms": MetricDefinition(
+        name="by_framework_metrics_collector_snapshot_duration_ms",
+        kind=MetricKind.HISTOGRAM,
+        unit=MetricUnit.MILLISECONDS,
+        description=(
+            "Duration of one collector snapshot build plus history write."
+        ),
+        interpretation=(
+            "Latency signal for collection itself; approaching the collection "
+            "interval means cycles are about to overlap."
+        ),
+    ),
+    "by_framework_metrics_collector_lock_held": MetricDefinition(
+        name="by_framework_metrics_collector_lock_held",
+        kind=MetricKind.GAUGE,
+        unit=MetricUnit.NONE,
+        description=(
+            "Whether this process currently holds the metrics collector lock."
+        ),
+        interpretation=(
+            "Saturation signal: should sum to 1 across the fleet — 0 means "
+            "nobody is collecting, above 1 means the lock split."
+        ),
+    ),
+    "by_framework_metrics_collector_last_success_timestamp_ms": MetricDefinition(
+        name="by_framework_metrics_collector_last_success_timestamp_ms",
+        kind=MetricKind.GAUGE,
+        unit=MetricUnit.MILLISECONDS,
+        description=(
+            "Unix timestamp in milliseconds of the last successful collection."
+        ),
+        interpretation=(
+            "Freshness signal: alert on now minus this value exceeding a few "
+            "collection intervals."
+        ),
+    ),
 }
 
 

by_framework/worker/runner.py

@@ -83,6 +83,7 @@ class WorkerRunner:
         self.worker = worker
         self.group_name = group_name or self._auto_group_name()
         self.consumer_name = worker.worker_id
+        self.max_concurrency = max_concurrency
         self.semaphore = asyncio.Semaphore(max_concurrency)
         self.fetch_count = fetch_count
         # OTel for worker.execute is emitted via a live wrapping span (see
@@ -121,6 +122,14 @@ class WorkerRunner:
             float(self.worker.heartbeat_lease_ttl_seconds) * 2.0,
             stream_block_seconds * 3.0,
         )
+        # Poll interval used by _acquire_slot() while waiting for a saturated
+        # semaphore. Derived from _consumer_health_timeout_seconds (not a
+        # hardcoded constant) so it stays well under the health-check
+        # deadline under any configuration, with a floor to avoid busy-
+        # polling if the timeout is configured very small.
+        self._slot_wait_poll_seconds = max(
+            self._consumer_health_timeout_seconds / 4.0, 1.0
+        )
         # Set as the first step of _shutdown() - see
         # docs/architecture/worker-readiness-endpoint.md Decision 6.
         self._draining: bool = False
@@ -386,9 +395,23 @@ class WorkerRunner:
         finally:
             await self.redis.xack(stream_name, self.group_name, msg_id)
 
+    async def _acquire_slot(self) -> None:
+        """Wait for a concurrency slot, marking the consumer tick on every
+        poll so a saturated-but-alive loop isn't judged stalled.
+
+        Polling on `len(self._running_tasks)` instead of wrapping
+        `semaphore.acquire()` in `asyncio.wait_for()` avoids relying on
+        Semaphore cancellation semantics for a lock this runner is the only
+        waiter on — see design.md's "why not asyncio.wait_for" section.
+        """
+        while len(self._running_tasks) >= self.max_concurrency:
+            self._mark_consumer_tick()
+            await asyncio.sleep(self._slot_wait_poll_seconds)
+        await self.semaphore.acquire()
+
     async def _run_once(self) -> bool:
         """Fetch and start processing messages."""
-        await self.semaphore.acquire()
+        await self._acquire_slot()
 
         try:
             messages = await self.fetch_messages(
@@ -401,7 +424,7 @@ class WorkerRunner:
 
             for i, (stream_name, msg_id, data_dict) in enumerate(messages):
                 if i > 0:
-                    await self.semaphore.acquire()
+                    await self._acquire_slot()
 
                 task = asyncio.create_task(
                     self._process_and_release(stream_name, msg_id, data_dict)

{by_framework-0.2.2.dev14.dist-info → by_framework-0.2.2.dev16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: by-framework
-Version: 0.2.2.dev14
+Version: 0.2.2.dev16
 Summary: 分布式 Agent 调度框架
 License-File: LICENSE
 Requires-Python: >=3.12

{by_framework-0.2.2.dev14.dist-info → by_framework-0.2.2.dev16.dist-info}/RECORD

@@ -69,7 +69,7 @@ by_framework/errors/http.py,sha256=xtm4EKwbE1Z0n4yqWTjPOVbDd9fIPfmT8W4ou5aOLCQ,7
 by_framework/errors/protocol.py,sha256=MWr15TFIHs8Ql67mgvU9mebGdE04yPxmg4AOEGbF9E4,1269
 by_framework/errors/registry.py,sha256=LmcqSXiW8FSOghpLPHTllkbrQCnVcMYTLzO2cNU3wIw,842
 by_framework/metrics/__init__.py,sha256=8AQpVnOwAmHoQsDhCfkNXSKUOX_ZCBF_QajBXmsNhgc,11353
-by_framework/metrics/catalog.py,sha256=CR9-1M_L0rR-5jgGUw3M1TplTzntpTjN2MXG34s9lnw,17355
+by_framework/metrics/catalog.py,sha256=1yWxVCvvrbkT0Rdmi0x-rtRwtXFzQg6Dmuj75izN2X0,19684
 by_framework/metrics/collector.py,sha256=uIO2TJfX4zQTBi5gWbMfgwtdMjrhmhzjzW36BcqxBKE,8533
 by_framework/metrics/read_client.py,sha256=kcgHJlJh47eFPhlbH8QOyD-K6SpKbZHEX624XD6Mvxo,18511
 by_framework/metrics/snapshot.py,sha256=eI4JVV3uma7fT6nvp2bliO2ZUBJhJT6bzTvQDIeC-wk,101784
@@ -94,12 +94,12 @@ by_framework/worker/context.py,sha256=5As3GcnVrwIE1nCJDDYLt_Ke8-8nzh44CzQBvyncQs
 by_framework/worker/health_server.py,sha256=4Jw3ltAD7Ow4dPHhwTUU_4JjKz-iDCNG7RJzD2VzPlM,6090
 by_framework/worker/heartbeat.py,sha256=trHDS8FUALsA6jyzDPa087hpr8_2vY8ZUFn0ld1kI2o,15465
 by_framework/worker/processor.py,sha256=UgC4_p-bg2KOHVTEILeMXF44rT9VLrRP5vompX0EeiQ,16243
-by_framework/worker/runner.py,sha256=6_L_UUV1Kljys_4Eh_qnwMd7a-gGsikd4M_O5K879NA,51897
+by_framework/worker/runner.py,sha256=nkJDpziUQaqqVEXc8OhoF4DKGiw7fthpvXudDjxYdm0,53093
 by_framework/worker/worker.py,sha256=IaPFLWCFo5U5Xo7PIQHtTt4JmtxZA1O_3nAuGl_g4N0,49527
 by_framework/worker/sandbox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 by_framework/worker/sandbox/hook_sandbox.py,sha256=XXSdH5YGX814LvV03vkq-zn5DVIBPYYt2NhRv1lT1Bk,2329
-by_framework-0.2.2.dev14.dist-info/METADATA,sha256=LpR98e5DnEucXKFwftIul_FFYGw3BQvTR3QNP2cayX0,28018
-by_framework-0.2.2.dev14.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-by_framework-0.2.2.dev14.dist-info/entry_points.txt,sha256=5t6kgMjkR0UgJTpOsbuQDo0fOf7zeXjQW9DhkxfAGFc,56
-by_framework-0.2.2.dev14.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-by_framework-0.2.2.dev14.dist-info/RECORD,,
+by_framework-0.2.2.dev16.dist-info/METADATA,sha256=3Sbgc5Aw5L6vYzfRQpcfyMK9B-qYs9V-TMvAJGHwrAM,28018
+by_framework-0.2.2.dev16.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+by_framework-0.2.2.dev16.dist-info/entry_points.txt,sha256=5t6kgMjkR0UgJTpOsbuQDo0fOf7zeXjQW9DhkxfAGFc,56
+by_framework-0.2.2.dev16.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+by_framework-0.2.2.dev16.dist-info/RECORD,,