diagnostics-metrics-cls

v1.1.7

Published

5 days ago

OpenClaw diagnostics exporter: Prometheus metrics (pull/remote-write) + Tencent Cloud CLS trace/log upload

Downloads

0High
0Medium
0Low

zhanxiangli

Diagnostics Metrics 插件

OpenClaw 诊断指标导出插件，提供两大核心能力：

Prometheus 指标：通过 /metrics HTTP 端点暴露指标（Pull 模式），或通过 Remote Write 协议主动推送到远端（Push 模式）
腾讯云 CLS 上传：将 OpenClaw 运行时的诊断 Trace 事件和运行日志实时上传到腾讯云日志服务（CLS）

快速安装（推荐）

使用 onboard CLI 工具一键完成安装和配置。

运行安装向导

npx diagnostics-metrics-cls-onboard-cli install

命令行会依次提示输入以下信息：

| 提示 | 说明 | 是否必填 | |------|------|----------| | CLS 日志主题 ID | 腾讯云 CLS 的 Topic ID | ✅ 必填 | | SecretId | 腾讯云 API 密钥 SecretId | ✅ 必填 | | SecretKey | 腾讯云 API 密钥 SecretKey（输入时不回显） | ✅ 必填 | | CLS 接入点 | 例如 ap-guangzhou.cls.tencentcs.com | ✅ 必填 | | 日志来源标识 | 写入 CLS 的 source 字段，默认 openclaw | 可选 |

安装完成后，CLI 会自动重启网关并输出确认信息：

✅ 安装完成，diagnostics-metrics-cls 已启用
   CLS 接入点: ap-guangzhou.cls.tencentcs.com
   日志主题 ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

运行以下命令验证插件状态：
   openclaw plugins list

手动安装

第一步：安装插件

openclaw plugins install diagnostics-metrics-cls

第二步：编辑配置文件

打开 ~/.openclaw/openclaw.json，在 plugins.entries 中添加插件配置：

{
  "plugins": {
    "allow": ["diagnostics-metrics-cls"],
    "entries": {
      "diagnostics-metrics-cls": {
        "enabled": true,
        "config": {
          "cls": {
            "topicId": "your-cls-topic-id",
            "secretId": "your-secret-id",
            "secretKey": "your-secret-key",
            "endpoint": "ap-guangzhou.cls.tencentcs.com"
          }
        }
      }
    }
  }
}

第三步：重启网关

openclaw gateway restart

配置说明

所有配置均位于 ~/.openclaw/openclaw.json 中 plugins.entries["diagnostics-metrics-cls"].config 下。

CLS 配置（必填）

{
  "cls": {
    "topicId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "secretId": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "secretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "endpoint": "ap-guangzhou.cls.tencentcs.com",
    "source": "openclaw",
    "enableTraceEvent": true,
    "enableLogTransport": true,
    "minLevel": "info",
    "sendTimeThreshold": 2,
    "sendCountThreshold": 1000
  }
}

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | topicId | string | — | 必填。CLS 日志主题 ID | | secretId | string | — | 必填。腾讯云 API 密钥 SecretId | | secretKey | string | — | 必填。腾讯云 API 密钥 SecretKey | | endpoint | string | — | 必填。CLS 接入点域名，例如 ap-guangzhou.cls.tencentcs.com | | source | string | "openclaw" | 写入 CLS 日志的来源标识字段 | | enableTraceEvent | boolean | true | 是否上传诊断 Trace 事件（model.usage / message.processed 等） | | enableLogTransport | boolean | true | 是否同时上传运行日志（info/warn/error 等） | | minLevel | string | "info" | 运行日志最低上传级别，可选值：trace debug info warn error fatal | | sendTimeThreshold | number | 2 | 异步发送时间阈值（秒），达到后触发批量上传 | | sendCountThreshold | number | 1000 | 异步发送条数阈值，达到后触发批量上传 |

获取腾讯云密钥：登录腾讯云控制台 → 访问管理 → API 密钥管理。
获取 CLS Topic ID：登录日志服务控制台 → 日志主题 → 复制主题 ID。
CLS 接入点列表：参考 CLS 可用地域，格式为 <region>.cls.tencentcs.com（内网）或 <region>.cls.tencentyun.com（外网）。

Prometheus 配置（可选）

Prometheus 功能通过插件自身的 config.prometheus 配置项控制，与 CLS 配置并列放在 plugins.entries["diagnostics-metrics-cls"].config 下。

在 ~/.openclaw/openclaw.json 中添加：

{
  "plugins": {
    "allow": ["diagnostics-metrics-cls"],
    "entries": {
      "diagnostics-metrics-cls": {
        "enabled": true,
        "config": {
          "prometheus": {
            "enabled": true,
            "metric_prefix": "openclaw",
            "pull": true,
            "default_metrics": true,
            "external_labels": {
              "instance": "my-openclaw-instance",
              "env": "production"
            },
            "remote_write": [
              {
                "url": "http://prometheus:9090/api/v1/write"
              }
            ],
            "push_interval_ms": 15000
          }
        }
      }
    }
  }
}

Prometheus 基础配置

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | false | 是否启用 Prometheus 功能 | | metric_prefix | string | "openclaw" | 所有指标名称的前缀 | | pull | boolean | true | 是否启用 /metrics HTTP Pull 端点 | | default_metrics | boolean | true | 是否采集 Node.js 默认指标（GC、事件循环等） | | external_labels | object | {} | 附加到所有指标的自定义标签 | | push_interval_ms | number | 15000 | Remote Write 推送间隔（毫秒） |

Remote Write 配置

remote_write 为数组，支持同时配置多个推送目标：

{
  "remote_write": [
    {
      "url": "http://prometheus:9090/api/v1/write",
      "headers": {
        "Authorization": "Bearer <token>"
      },
      "queue_config": {
        "capacity": 2500,
        "max_samples_per_send": 500,
        "batch_send_deadline_ms": 5000,
        "max_retries": 3
      },
      "tls_config": {
        "insecure_skip_verify": false
      }
    }
  ]
}

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | url | string | — | 必填。Remote Write 端点 URL | | headers | object | — | 自定义 HTTP 请求头（可用于传入 Authorization 等认证头） | | tls_config.ca_file | string | — | CA 证书文件路径 | | tls_config.cert_file | string | — | 客户端证书文件路径 | | tls_config.key_file | string | — | 客户端私钥文件路径 | | tls_config.insecure_skip_verify | boolean | false | 跳过 TLS 证书验证 | | queue_config.capacity | number | 2500 | 队列容量（超出后丢弃最旧数据） | | queue_config.max_samples_per_send | number | 500 | 每批最大发送样本数 | | queue_config.batch_send_deadline_ms | number | 5000 | 批次最大等待时间（毫秒） | | queue_config.max_retries | number | 3 | 5xx/429 错误最大重试次数 | | queue_config.min_backoff_ms | number | 30 | 重试最小退避时间（毫秒） | | queue_config.max_backoff_ms | number | 5000 | 重试最大退避时间（毫秒） |

认证说明：如需 HTTP 认证，请通过 headers 字段传入自定义请求头，例如 { "Authorization": "Bearer <token>" } 或 { "X-Scope-OrgID": "tenant-id" }。

功能说明

Prometheus 指标列表

所有指标名称均以 metric_prefix（默认 openclaw）为前缀。

模型调用指标

| 指标名 | 类型 | 标签 | 说明 | |--------|------|------|------| | openclaw_tokens_total | Counter | type, provider, model, channel | 累计 Token 消耗（type: input/output/cache_read/cache_write/total） | | openclaw_cost_usd_total | Counter | provider, model | 累计模型调用费用（USD） | | openclaw_run_duration_ms | Histogram | provider, model | Agent 运行耗时（毫秒） | | openclaw_context_tokens | Histogram | provider, model, type | 上下文窗口 Token 数（type: limit/used） |

Webhook 指标

| 指标名 | 类型 | 标签 | 说明 | |--------|------|------|------| | openclaw_webhook_received_total | Counter | channel, update_type | 收到的 Webhook 请求数 | | openclaw_webhook_error_total | Counter | channel, update_type | Webhook 处理错误数 | | openclaw_webhook_duration_ms | Histogram | channel, update_type | Webhook 处理耗时（毫秒） |

消息处理指标

| 指标名 | 类型 | 标签 | 说明 | |--------|------|------|------| | openclaw_message_queued_total | Counter | channel, source | 入队消息数 | | openclaw_message_processed_total | Counter | channel, outcome | 处理完成消息数（outcome: success/error 等） | | openclaw_message_duration_ms | Histogram | channel, outcome | 消息处理耗时（毫秒） |

队列指标

| 指标名 | 类型 | 标签 | 说明 | |--------|------|------|------| | openclaw_queue_depth | Gauge | lane | 当前队列深度 | | openclaw_queue_wait_ms | Histogram | lane | 消息在队列中的等待时间（毫秒） | | openclaw_queue_lane_enqueue_total | Counter | lane | 队列入队事件数 | | openclaw_queue_lane_dequeue_total | Counter | lane | 队列出队事件数 |

会话指标

| 指标名 | 类型 | 标签 | 说明 | |--------|------|------|------| | openclaw_session_state_total | Counter | state, reason | 会话状态转换次数 | | openclaw_session_stuck_total | Counter | state | 检测到卡死的会话数 | | openclaw_session_stuck_age_ms | Histogram | state | 卡死会话的存活时长（毫秒） | | openclaw_active_sessions | Gauge | — | 当前活跃会话数 | | openclaw_waiting_sessions | Gauge | — | 当前等待中的会话数 | | openclaw_queued_messages | Gauge | — | 当前队列中的消息总数 |

其他指标

| 指标名 | 类型 | 标签 | 说明 | |--------|------|------|------| | openclaw_run_attempt_total | Counter | attempt | Agent 运行尝试次数 | | openclaw_tool_loop_total | Counter | tool, detector, level, action | 工具循环检测次数 | | openclaw_node_* | 多种 | — | Node.js 运行时指标（GC、事件循环、内存等，default_metrics: true 时启用） |

CLS Trace 事件

当 enableTraceEvent: true（默认）时，以下诊断事件会以 Span 形式上传到 CLS：

| 事件类型 | Span 名称 | 说明 | |----------|-----------|------| | model.usage | openclaw.model.usage | 模型调用完成，包含 Token 用量、费用、耗时、上下文大小 | | webhook.processed | openclaw.webhook.processed | Webhook 处理完成，包含渠道、类型、耗时 | | webhook.error | openclaw.webhook.error | Webhook 处理失败，包含错误信息（已脱敏） | | message.processed | openclaw.message.processed | 消息处理完成，包含结果、耗时、会话信息 | | session.stuck | openclaw.session.stuck | 检测到会话卡死，包含状态、存活时长 |

每条 Span 包含以下公共字段：

| CLS 字段 | 说明 | |----------|------| | name | Span 名称 | | eventType | 原始事件类型 | | startTime | 事件开始时间（ISO 8601） | | endTime | 事件结束时间（ISO 8601） | | status | ok 或 error | | durationMs | 耗时（毫秒，如有） | | errorMessage | 错误信息（仅 status=error 时，已脱敏） | | seq | 事件序列号 | | openclaw.* | 事件特有属性（渠道、模型、Token 等） |

CLS 运行日志

当 enableLogTransport: true（默认）时，OpenClaw 的运行日志会实时上传到 CLS。

每条日志包含以下字段：

| CLS 字段 | 说明 | |----------|------| | level | 日志级别（trace/debug/info/warn/error/fatal） | | message | 日志消息内容 | | source | 来源标识（由 cls.source 配置，默认 openclaw） | | subsystem | 子系统名称（如有） | | logger | Logger 名称（如有） | | args | 额外参数（JSON 序列化，如有） |

通过 minLevel 可过滤低级别日志，例如设置 "minLevel": "warn" 则只上传 warn 及以上级别的日志。

验证插件状态

查看插件列表

openclaw plugins list

输出示例：

Name                  Status    Version
Diagnostics Metrics   loaded    2026.3.2

Status 为 loaded 表示插件已成功加载。

验证 Prometheus 指标端点

curl http://localhost:<openclaw-port>/metrics

正常响应示例：

# HELP openclaw_tokens_total Total tokens consumed
# TYPE openclaw_tokens_total counter
openclaw_tokens_total{type="input",provider="anthropic",model="claude-3-5-sonnet",channel="telegram"} 1234
...

验证 CLS 日志上传

登录腾讯云日志服务控制台，进入对应日志主题，在检索分析页面执行查询：

source: "openclaw"

或查询 Trace 事件：

eventType: "model.usage"

常见问题

Q：插件状态显示 error 而非 loaded？

检查 OpenClaw 日志中是否有 diagnostics-metrics-cls 相关错误。常见原因：

依赖未安装：在插件目录执行 pnpm install（需在 monorepo 根目录执行）
配置缺失：确认 cls.topicId、cls.secretId、cls.secretKey、cls.endpoint 均已填写

Q：CLS 日志上传失败，日志中出现 日志上传失败 警告？

检查 secretId / secretKey 是否正确，且对应账号有 CLS 写入权限
检查 endpoint 是否与日志主题所在地域匹配
检查网络连通性：curl https://<endpoint>

Q：Prometheus /metrics 端点返回 503？

确认插件配置中 prometheus.enabled: true 已设置，即 plugins.entries["diagnostics-metrics-cls"].config.prometheus.enabled 为 true。

Q：如何只启用 Prometheus，不上传 CLS？

不配置 cls 节点（或不填写必填字段），插件会自动跳过 CLS 功能，仅启用 Prometheus 指标。

Q：如何只上传 CLS，不暴露 Prometheus 端点？

不配置 prometheus 节点，或设置 "prometheus": { "enabled": false }。

Q：如何更新 CLS 配置（如更换密钥）？

重新运行 onboard CLI：

npx diagnostics-metrics-cls-onboard-cli install

CLI 会读取已有配置作为默认值，只需修改需要更新的字段。

完整配置示例

{
  "plugins": {
    "allow": ["diagnostics-metrics-cls"],
    "entries": {
      "diagnostics-metrics-cls": {
        "enabled": true,
        "config": {
          "prometheus": {
            "enabled": true,
            "metric_prefix": "openclaw",
            "pull": true,
            "default_metrics": true,
            "external_labels": {
              "instance": "prod-01",
              "env": "production"
            },
            "remote_write": [
              {
                "url": "http://prometheus:9090/api/v1/write",
                "queue_config": {
                  "max_samples_per_send": 500,
                  "batch_send_deadline_ms": 5000
                }
              }
            ],
            "push_interval_ms": 15000
          },
          "cls": {
            "topicId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "secretId": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "secretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "endpoint": "ap-guangzhou.cls.tencentcs.com",
            "source": "openclaw",
            "enableTraceEvent": true,
            "enableLogTransport": true,
            "minLevel": "info",
            "sendTimeThreshold": 2,
            "sendCountThreshold": 1000
          }
        }
      }
    }
  }
}