Prometheus 指标导出

OpenClaw 通过官方 diagnostics-prometheus 插件暴露 Prometheus 文本格式指标，端点为：

GET /api/diagnostics/prometheus

内容类型：text/plain; version=0.0.4; charset=utf-8

安全警告：该路由使用 Gateway 认证（operator scope），不要将其暴露为公开未认证的 /metrics 端点。

快速开始

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
openclaw plugins enable diagnostics-prometheus

配置：

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

抓取测试：

curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus

Prometheus 配置：

scrape_configs:
  - job_name: openclaw
    scrape_interval: 30s
    metrics_path: /api/diagnostics/prometheus
    authorization:
      credentials_file: /etc/prometheus/openclaw-gateway-token
    static_configs:
      - targets: ["openclaw-gateway:18789"]

主要指标

指标	类型	说明
openclaw_run_completed_total	counter	运行完成数
openclaw_run_duration_seconds	histogram	运行时长
openclaw_model_call_total	counter	模型调用数
openclaw_model_tokens_total	counter	token 用量
openclaw_model_cost_usd_total	counter	费用（USD）
openclaw_tool_execution_total	counter	工具执行数
openclaw_message_processed_total	counter	消息处理数
openclaw_queue_lane_size	gauge	队列深度
openclaw_session_state_total	counter	会话状态变化
openclaw_memory_bytes	gauge	内存用量
openclaw_prometheus_series_dropped_total	counter	超出上限被丢弃的序列数

标签策略

• 标签保持有界低基数，不含原始 ID（runId、sessionKey、callId 等）
• 序列上限：2048 个（counters + gauges + histograms 合计）
• 超出上限的新序列被丢弃，openclaw_prometheus_series_dropped_total 递增

PromQL 示例

# 按 provider 统计每分钟 token 数
sum by (provider) (rate(openclaw_model_tokens_total[1m]))
 
# 过去 1 小时按模型统计费用
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))
 
# 模型运行时长 P95
histogram_quantile(0.95, sum by (le, provider, model) (rate(openclaw_run_duration_seconds_bucket[5m])))
 
# 基数告警
increase(openclaw_prometheus_series_dropped_total[15m]) > 0

Prometheus vs OpenTelemetry

对比项	diagnostics-prometheus	diagnostics-otel
模式	Pull（Prometheus 抓取）	Push（OTLP/HTTP）
信号	仅 metrics	metrics + traces + logs
需要 collector	否	是
适合场景	已有 Prometheus + Grafana 栈	需要完整可观测性

相关链接

• gateway-opentelemetry — OTLP 推送（traces + metrics + logs）
• gateway-health — 健康检查与就绪探测