feat: add low-cardinality observation port

app/runtime/observability/__init__.py

@@ -0,0 +1,99 @@
+"""低基数运行指标端口与进程级 Facade。"""
+
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Iterator, Mapping, Protocol
+
+
+class MetricKind(StrEnum):
+    """声明指标采用 counter、histogram 或 gauge 语义。"""
+
+    COUNTER = "counter"
+    HISTOGRAM = "histogram"
+    GAUGE = "gauge"
+
+
+@dataclass(frozen=True, slots=True)
+class MetricSpec:
+    """声明稳定指标名称、类型与允许的低基数标签。"""
+
+    name: str
+    kind: MetricKind
+    labels: frozenset[str]
+
+
+METRIC_SPECS = {
+    spec.name: spec
+    for spec in (
+        MetricSpec("http.server.duration", MetricKind.HISTOGRAM, frozenset({"route", "method", "status"})),
+        MetricSpec("db.pool.wait", MetricKind.HISTOGRAM, frozenset({"backend", "outcome"})),
+        MetricSpec("db.pool.checked_out", MetricKind.GAUGE, frozenset({"backend"})),
+        MetricSpec("db.pool.timeout", MetricKind.COUNTER, frozenset({"backend"})),
+        MetricSpec("event.queue.depth", MetricKind.GAUGE, frozenset({"delivery"})),
+        MetricSpec("event.handler.duration", MetricKind.HISTOGRAM, frozenset({"event_type", "handler_type", "outcome"})),
+        MetricSpec("module.provider.duration", MetricKind.HISTOGRAM, frozenset({"method", "provider_type", "outcome"})),
+        MetricSpec("module.provider.timeout", MetricKind.COUNTER, frozenset({"method", "provider_type"})),
+        MetricSpec("scheduler.job.duration", MetricKind.HISTOGRAM, frozenset({"owner", "outcome"})),
+        MetricSpec("scheduler.job.overlap_skip", MetricKind.COUNTER, frozenset({"owner"})),
+        MetricSpec("scheduler.job.retry", MetricKind.COUNTER, frozenset({"owner"})),
+        MetricSpec("scheduler.job.dead_letter", MetricKind.COUNTER, frozenset({"owner"})),
+        MetricSpec("plugin.lifecycle.duration", MetricKind.HISTOGRAM, frozenset({"operation", "outcome"})),
+        MetricSpec("agent.active_tasks", MetricKind.GAUGE, frozenset({"task_type"})),
+        MetricSpec("agent.cancel", MetricKind.COUNTER, frozenset({"task_type", "outcome"})),
+        MetricSpec("agent.provider.duration", MetricKind.HISTOGRAM, frozenset({"provider_type", "outcome"})),
+        MetricSpec("agent.token_usage", MetricKind.COUNTER, frozenset({"provider_type", "direction"})),
+    )
+}
+
+
+class ObservationPort(Protocol):
+    """Application/runtime 可依赖的最小指标写入端口。"""
+
+    def record(self, spec: MetricSpec, value: float, labels: Mapping[str, str]) -> None:
+        """记录一个已经通过标签合同校验的指标值。"""
+
+
+class NoopObservationPort:
+    """未安装或未启用 exporter 时完全无副作用的默认实现。"""
+
+    def record(self, spec: MetricSpec, value: float, labels: Mapping[str, str]) -> None:
+        """接受合法指标但不分配 exporter 资源。"""
+
+
+_observation_port: ObservationPort = NoopObservationPort()
+
+
+def configure_observation(port: ObservationPort | None) -> None:
+    """由组合根替换进程级端口；None 明确恢复 no-op。"""
+    global _observation_port
+    _observation_port = port or NoopObservationPort()
+
+
+def record_metric(name: str, value: float = 1, **labels: str) -> None:
+    """校验名称、类型无关数值和标签白名单后写入当前端口。"""
+    spec = METRIC_SPECS[name]
+    unexpected = set(labels) - spec.labels
+    if unexpected:
+        raise ValueError(f"指标 {name} 包含未登记标签：{sorted(unexpected)}")
+    _observation_port.record(spec, float(value), labels)
+
+
+@contextmanager
+def observe_duration(name: str, **labels: str) -> Iterator[None]:
+    """记录代码块耗时，并把成功或失败收敛为低基数 outcome。"""
+    started_at = time.perf_counter()
+    outcome = "success"
+    try:
+        yield
+    except BaseException:
+        outcome = "error"
+        raise
+    finally:
+        duration_labels = dict(labels)
+        if "outcome" in METRIC_SPECS[name].labels:
+            duration_labels["outcome"] = outcome
+        record_metric(name, time.perf_counter() - started_at, **duration_labels)