奇链 奇链
← 文章 / 科技资讯
signoz 1天前 · 2026-11-09 06:33:29 · 1 阅读

OpenClaw 基于 OpenTelemetry 的可观测性与监控

OpenClaw 是一个开源的个人 AI 助手，运行在你自己的设备上，并通过你日常使用的即时通讯应用与你交互，支持 WhatsApp、Telegram、Slack、Discord 和 Signal 等。它由一个本地 gateway 进程作为控制平面，负责管理会话、定时任务和工具执行。

由于 OpenClaw 在本地运行，且会在无人触发的情况下按计划执行任务，遥测数据往往是了解它在你不在时做了什么的唯一途径：调用了哪些模型、运行了哪些工具、一次会话花费多少。

OpenClaw 的可观测性通过 OpenTelemetry 收集 traces、logs 和 metrics，让你获得这些可见性。本指南将介绍如何为 OpenClaw 添加监控埋点，并把遥测数据发送到 SigNoz，从而监控性能、排查故障、了解模型使用情况。

在 SigNoz 中获得完整的 OpenClaw 可观测性后，你可以在同一个仪表盘中关联 traces、logs 和 metrics，针对错误率或高延迟设置告警，并分析各渠道随时间变化的使用模式。

前提条件

使用 OpenTelemetry 监控 OpenClaw

有关如何在你的环境中上手 OpenClaw 的更多信息，请参阅 OpenClaw 快速入门指南。

启用日志的临时方案

当前版本的 OpenClaw 在日志采集方面还存在一些问题。为了启用日志功能，我们在一个fork 仓库中做了修改，并提交了 PR#22478。你可以按照下面的步骤启用日志；如果只需要 traces 和 metrics，可以跳过这些步骤。

前提条件

  • 已安装 Node.js 和 pnpm。
  • npm 全局 prefix 已设置为用户级目录（如 ~/.npm-global）。

克隆仓库并切换到修复分支

Copy
git clone https://github.com/LuffySama-Dev/openclaw.git
cd openclaw
git switch logsIsolationIssueFixed

安装依赖项并构建

Copy
pnpm install
pnpm build

从本地仓库全局安装（重要：请勿使用 sudo）

Copy
npm install -g .

确保用户级 npm bin 目录位于 PATH 的最前面

Copy
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hash -r

验证 OpenClaw 是否解析到用户路径（而非 /usr/bin）

Copy
which openclaw
openclaw --version
npm ls -g openclaw --depth=0

第 1 步：启用 Diagnostic-OTel 插件

diagnostics-otel 插件随 OpenClaw 一同提供，但默认处于禁用状态。你可以通过 CLI 启用它：

Copy
openclaw plugins enable diagnostics-otel

或者直接在配置文件中添加该插件（~/.openclaw/openclaw.json）：

Copy
{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  }
}

第 2 步：配置 OTEL Exporter

你可以通过 CLI 配置导出器：

Copy
openclaw config set diagnostics.enabled true
openclaw config set diagnostics.otel.enabled true
openclaw config set diagnostics.otel.traces true
openclaw config set diagnostics.otel.metrics true
openclaw config set diagnostics.otel.logs true
openclaw config set diagnostics.otel.protocol http/protobuf
openclaw config set diagnostics.otel.endpoint "https://ingest.<region>.signoz.cloud:443"
openclaw config set diagnostics.otel.headers '{"signoz-ingestion-key":"<your-ingestion-key>"}'
openclaw config set diagnostics.otel.serviceName "<service_name>"
使用自托管 SigNoz？

大部分步骤相同。只需按照 Cloud → Self-Hosted 中的说明修改 endpoint 并移除 ingestion key 请求头即可。

配置要点

配置注意事项：

  • protocol - OpenClaw 目前仅支持 http/protobuf，设置 grpc 会被静默忽略。
  • endpoint - SigNoz Cloud 的 OTLP/HTTP 和 OTLP/gRPC 都使用 443 端口，与常见的 4317/4318 端口划分不同。如果 endpoint 中没有包含 /v1/traces 或 /v1/metrics，插件会自动追加相应路径。
  • headers - SigNoz Cloud 需要通过 signoz-ingestion-key 请求头进行身份验证。
  • flushIntervalMs - 最小值为 1000ms。默认值（60s）意味着快速任务的 trace 最多要等一分钟才能显示，建议设为 5000 以获得接近实时的可见性。
  • sampleRate - 控制 trace 采样率（0.0–1.0，仅作用于根 span）。个人使用设为 1.0 即可。

步骤 3：检查配置（可选）

可以使用以下命令快速检查配置：

Copy
openclaw config get diagnostics

输出应如下所示：

Copy
{
  "enabled": true,
  "otel": {
    "enabled": true,
    "endpoint": "https://ingest.<region>.signoz.cloud:443",
    "protocol": "http/protobuf",
    "headers": {
      "signoz-ingestion-key": "<YOUR_SIGNOZ_INGESTION_KEY>"
    },
    "serviceName": "openclaw-gateway",
    "traces": true,
    "metrics": true,
    "logs": true,
    "sampleRate": 1,
    "flushIntervalMs": 5000
  }
}

也可以直接查看 ~/.openclaw/openclaw.json 配置文件。

步骤 4：重启 OpenClaw gateway

Copy
openclaw gateway restart

在 SigNoz 中查看 OpenClaw 的 Traces 和 Metrics

配置完成后，OpenClaw 会自动为每次 LLM 请求上报 traces、logs 和 metrics。

OpenClaw 的 traces 可在 SigNoz 的 Traces 标签页中查看：

SigNoz 中的 OpenClaw 追踪，显示 LLM 应用活动
SigNoz 中的 OpenClaw 追踪：监控 LLM 应用 spans

在 SigNoz 中点击任意追踪，即可查看其详细视图，包含所有相关 spans、事件及属性。

SigNoz 中的 OpenClaw 详细追踪视图，含 spans、事件和属性
SigNoz 中的 OpenClaw 详细追踪：每个 LLM 请求的 spans、事件与属性

SigNoz 的 Metrics 标签页提供 OpenClaw 相关指标：

SigNoz 中的 OpenClaw 指标，展示 LLM 用量与性能数据
SigNoz 中的 OpenClaw 指标：追踪 LLM 用量、延迟与性能

点击 SigNoz 中的任意指标，可查看该指标的详细信息，包括其属性：

SigNoz 中的 OpenClaw 详细指标视图，含指标属性和时间序列
SigNoz 中的 OpenClaw 详细指标：指标属性与时间序列数据

AI Observability 视图

AI Observability 展示 OpenClaw agent 发起 LLM 调用时的成本、token 用量、延迟和错误。在 SigNoz 中打开 AI Observability，并通过 service_name 筛选器选择目标服务。

AI Observability Overview 仪表盘，展示 LLM 调用的成本、token 和延迟面板
AI Observability Overview 仪表盘

要查询单条 trace，打开 Explorer 标签页。Trace View 会为每条 trace 显示一行，包含 token 数、成本、调用次数等汇总数据。你可以基于这些数据进行过滤、聚合和排序，例如 trace.total_tokens > 1000。详情请参阅 AI Observability Explorer。

如果面板一直是空的，请确认你的 span 是否带有 Telemetry Requirements 中列出的属性。若要映射其他属性名，可以使用 Attribute Mapping。

OpenClaw 可观测性问题排查

如果看不到遥测数据：

  1. 检查网络连通性 —— 确保应用能够访问 SigNoz Cloud 的端点
  2. 检查 ingestion key —— 确认 SigNoz 的 ingestion key 填写正确
  3. 等待数据 —— OpenTelemetry 会先批量缓存数据再发送，因此调用 API 后需等待 10–30 秒
  4. 试试 console exporter —— 在本地启用 console exporter，确认应用在发送到 SigNoz 之前确实生成了遥测数据

OpenClaw 可观测性仪表盘

OpenClaw 可观测性仪表盘提供了专为 LLM 使用场景设计的预置图表，开箱即可监控 token 用量、请求速率和延迟。

SigNoz 中的 OpenClaw 可观测性仪表盘，为 LLM 应用提供预置图表
SigNoz 中的 OpenClaw 仪表盘模板：用于监控 LLM 使用的预置图表

配置 OpenTelemetry Collector（可选）

什么是 OpenTelemetry Collector？

可以把 OTel Collector 视为应用与 SigNoz 之间的中间层。应用不直接向 SigNoz 发送数据，而是先将其全部传至 Collector，再由 Collector 转发。

为什么需要它？

  • 数据清洗——过滤
原始来源： signoz

评论 (0)