指标与健康检查

Kestrel 暴露三个运维端点。两个匿名可达，一个需要 bearer token。

存活探针 —— /healthz

只要进程在跑就返回 200 ok，不管 DB 是否可达。用作"二进制还活着吗"（Docker HEALTHCHECK、k8s livenessProbe）。

curl http://localhost:8080/healthz
# ok

就绪探针 —— /healthz/ready

进程在跑且 SQLite 在 2 秒内能回应 SELECT 1 时返回 200 ready，否则 503 not ready。用作负载均衡 health check 和 k8s readinessProbe。

curl http://localhost:8080/healthz/ready
# ready

指标 —— /metrics

Prometheus 文本格式。默认关闭 —— 通过环境变量或配置文件设置 bearer token 来开启：

KESTREL_METRICS_TOKEN=$(openssl rand -hex 32)

或在 kestrel.toml 里：

[metrics]
token = "..."

Token 未设置时 /metrics 返回 404。设置之后，scraper 必须带上 token：

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/metrics

暴露的指标

指标	类型	含义
kestrel_info	gauge	永远是 1；标签 version、commit 标识构建身份。
kestrel_uptime_seconds	gauge	进程启动至今的秒数。
kestrel_projects_total	gauge	项目数量。
kestrel_issues_total	gauge	Issue 数量，按 status 标签拆分。
kestrel_events_total	gauge	已存事件总数（受 retention 影响）。
kestrel_events_24h	gauge	过去 24 小时收到的事件数。

Prometheus 抓取配置

scrape_configs:
  - job_name: kestrel
    metrics_path: /metrics
    authorization:
      type: Bearer
      credentials: "<your-token>"
    static_configs:
      - targets: ["kestrel.example.com:8080"]

为什么默认关闭？

如果允许匿名 /metrics，任何互联网访客都能枚举出"这个 Kestrel 实例有 4.7 万事件、12 个项目"。Kestrel 假设服务部署在公网上，所以默认必须是缺省即安全。

如果 scraper 跟 Kestrel 在同一私网，bearer token 只是运维卫生；如果在别处，token 就在做实事。两种情况下，事先开启都比事后堵漏轻松得多。

不会有的指标

告警规则、异常检测、错误预算、SLO 燃烧率 —— 都不在范围里。/metrics 是心电图，不是寻呼机。Kestrel 的立场是 挂在 MCP 后面的 AI agent 才是告警通道 —— 它能看到新错误进来并决定要不要叫醒你。在那基础上加一条 kestrel_events_24h > 1000 的 Prometheus 告警规则，是在做重复工作。