可观测性

Holon 让链路追踪和性能热路径保持有界：

已完成的 span 进入内存中的近期环形缓冲；
被选中的慢、失败、取消或抽样的 trace 可能保留在 diagnostics.sqlite；
可选的 OTLP 导出使用有界非阻塞队列；
OpenMetrics 暴露一组固定的、无标签的 holon_* 序列。

导出器或采集器故障不会阻塞轮次、工具、持久化或投递。关注导出器的丢弃和失败计数器，以发现遥测降级。

用 OTLP/HTTP 导出 trace

用基线配置启动 OpenTelemetry Collector：

otelcol-contrib \
  --config docs/website/assets/observability/otel-collector.yaml

该示例在 4318 端口接收 OTLP/HTTP JSON，并把收到的 trace 写入 Collector 的 debug 导出器。把 debug 换成你所用 trace 后端的导出器即可。

在 <HOLON_HOME>/config.json 中启用 Holon 导出器：

{
  "runtime": {
    "observability": {
      "otlp": {
        "enabled": true,
        "endpoint": "http://127.0.0.1:4318/v1/traces",
        "queue_capacity": 1024,
        "batch_size": 128,
        "batch_interval_ms": 1000,
        "timeout_ms": 5000
      }
    }
  }
}

改动 OTLP 设置后重启 daemon。导出器默认禁用，启用时必须显式指定 HTTP 或 HTTPS 端点。

采集器需要鉴权时，把 token 存到凭据存储中，而不是放进 config.json：

printf '%s' "$OTLP_TOKEN" \
  | holon config credentials set --kind bearer_token --stdin otlp-collector

然后在 OTLP 配置里加上 "credential_profile": "otlp-collector"。Holon 会把该配置中的材料作为 bearer 授权头加上。非机密的静态 header 可以放在 headers 对象里；不要同时配置 authorization header 和 credential_profile。

抓取受保护的 OpenMetrics

端点是：

GET /api/control/runtime/metrics

它使用与其他 /api/control/* 路由相同的控制平面 bearer 鉴权，返回：

application/openmetrics-text; version=1.0.0; charset=utf-8

本地检查：

curl --fail \
  --header "Authorization: Bearer $HOLON_CONTROL_TOKEN" \
  http://127.0.0.1:7878/api/control/runtime/metrics

响应没有标签，以 # EOF 结尾，并有固定的序列数上限。trace ID、Agent ID、模型名、URL、错误文本等高基数取值绝不会成为指标标签。

基线 Prometheus 抓取配置从挂载的 secret 文件读取 token：

prometheus \
  --config.file=docs/website/assets/observability/prometheus.yaml

把这些示例文件复制到你的部署使用的路径：

docs/website/assets/observability/prometheus.yaml
docs/website/assets/observability/holon-alerts.yaml

把控制端点放在回环或私有网络接口上。把控制 token 当作机密，不要写进 Prometheus 配置文本或仪表盘 JSON。

安装仪表盘和告警

把 docs/website/assets/observability/grafana-dashboard.json 导入 Grafana，并选择 Prometheus 数据源。基线面板覆盖：

进程运行时间；
轮次 p50/p95/p99 延迟；
投影门压力；
诊断写入队列、丢弃和失败；
OTLP 导出器队列、已导出 span、丢弃和失败批次。

把 holon-alerts.yaml 作为 Prometheus 规则文件加载。其中的阈值是保守的起点，不是通用的服务水平目标。观察有代表性的工作负载后，再调整轮次延迟和告警持续时间。

诊断遥测故障

按这个顺序排查：

检查 holon_process_uptime_seconds，区分抓取失败和子系统停滞。
检查 holon_otlp_exporter_failed_batches_total，排查采集器、凭据、TLS 或端点故障。
检查 holon_otlp_exporter_dropped_spans_total 和 holon_otlp_exporter_queue_depth，判断是否存在持续背压。
检查 holon_diagnostics_writer_dropped_traces_total 和 holon_diagnostics_writer_failures_total，排查本地诊断保留问题。

把故障与保留的 trace 关联起来：

holon debug trace --search <message-or-turn-id>
holon debug trace <trace-id>

OTLP 故障并不意味着本地 trace 搜索失败：按配置的抽样和保留策略，保留的 trace 仍留在独立的诊断数据库中。

可观测性

用 OTLP/HTTP 导出 trace

抓取受保护的 OpenMetrics

安装仪表盘和告警

诊断遥测故障

相关参考与概念