配置可观测性

本指南介绍如何对跨任务运行的 Holon 守护进程进行全局监控。如果你只需要了解某项具体目标的推进进度或最终成果，请先参阅观察 Agent 工作。

前置条件

• 正常运行中的 Holon 守护进程、修改其配置的权限以及控制平面访问 Token。
• 检出当前代码仓库以获取示例配置文件。
• 若打算完整使用三件套，请先安装 OpenTelemetry Collector (otelcol-contrib)、Prometheus 与 Grafana。
• 以下命令均在仓库根目录下运行。

修改守护进程配置前先安排好重启窗口。将 Token 保存在凭据存储或挂载的 Secret 文件中。示例中的 Collector 监听在 0.0.0.0:4318；若在本地测试请绑定至 Loopback，或在启动前限制其网络访问范围。

1. 启动测试 Collector

使用示例配置的副本，并根据需要调整绑定地址：

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

该示例接收端口 4318 上的 OTLP/HTTP JSON 请求，并将收到的 Trace 打印至调试输出。生产环境中应替换为真实的后端导出器。

2. 启用守护进程的 Trace 导出

在 <HOLON_HOME>/config.json 中配置导出器：

{
  "observability": {
    "traces": {
      "exporter": "otlp_http",
      "endpoint": "http://127.0.0.1:4318/v1/traces",
      "protocol": "http_json",
      "sample_ratio": 1.0
    }
  }
}

安全重启守护进程，并检查导出器启动日志：

holon daemon status
holon daemon logs | grep -i otel

3. 运行测试调用并验证 Trace

向测试 Agent 发送一个简单的请求：

holon run --agent observer "用一句话解释什么是追踪（Trace）。不要修改任何文件。"

检查 Collector 日志。你应该能看到代表该次交互轮次的 Span 以及对应的工具调用记录。Trace 的成功导出仅证明遥测链路通畅，并不等于该次业务目标的成果已经得到人工验收。

4. 抓取受保护的指标端点（Metrics）

Holon 在管理端口上暴露 OpenMetrics 指标端点。该端点需要携带 Bearer Token 认证。

在 Prometheus 中配置抓取作业：

scrape_configs:
  - job_name: "holon"
    scrape_interval: 15s
    scheme: http
    static_configs:
      - targets: ["127.0.0.1:7878"]
    metrics_path: "/metrics"
    authorization:
      type: Bearer
      credentials: "YOUR_HOLON_CONTROL_TOKEN"

启动 Prometheus 并验证指标抓取状态：

curl -H "Authorization: Bearer $HOLON_CONTROL_TOKEN" http://127.0.0.1:7878/metrics | grep holon_

输出应包含以 holon_ 为前缀的指标系列，例如请求计数器、活跃任务数与导出器状态。

5. 配置仪表盘与告警

将仓库提供的 Grafana 示例仪表盘（docs/website/assets/observability/grafana-dashboard.json）导入你的监控系统。

重点监控指标包括：

• holon_exporter_dropped_spans_total：由于网络或后端故障丢弃的 Span 总数。
• holon_active_tasks：当前处于运行或排队状态的任务数。
• 守护进程的内存与进程健康状况。

遥测链路的失败不会阻断业务交互，但应及时排查告警以防监控盲区。

另见

• 可观测性参考 — 完整的 OTLP 字段、指标项与契约说明
• 观察 Agent 工作 — 单个任务的状态查验