mirror of
https://github.com/jxxghp/MoviePilot.git
synced 2026-08-29 03:56:43 +08:00
100 lines
4.0 KiB
Python
100 lines
4.0 KiB
Python
"""低基数运行指标端口与进程级 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)
|