Chuyển đến nội dung chính
OpenClaw có thể hiển thị các chỉ số chẩn đoán thông qua Plugin chính thức diagnostics-prometheus. Plugin này lắng nghe các chẩn đoán đáng tin cậy cùng các sự kiện ổn định Gateway do lõi phát ra, rồi kết xuất một điểm cuối văn bản Prometheus tại: 
GET /api/diagnostics/prometheus
Kiểu nội dung là text/plain; version=0.0.4; charset=utf-8, định dạng trình bày tiêu chuẩn của Prometheus.
Route này sử dụng xác thực Gateway (phạm vi người vận hành). Không hiển thị nó dưới dạng điểm cuối /metrics công khai không cần xác thực. Hãy scrape nó thông qua cùng đường dẫn xác thực mà bạn dùng cho các API người vận hành khác.
Đối với trace, log, OTLP push và các thuộc tính ngữ nghĩa OpenTelemetry GenAI, xem Xuất OpenTelemetry.

​
Bắt đầu nhanh

1

Cài đặt Plugin

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

Bật Plugin

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

Khởi động lại Gateway

Route HTTP được đăng ký khi Plugin khởi động, vì vậy hãy tải lại sau khi bật.
4

Scrape route được bảo vệ

Gửi cùng thông tin xác thực Gateway mà các máy khách người vận hành của bạn sử dụng:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Wire Prometheus

# prometheus.yml
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"]
Bắt buộc có diagnostics.enabled: true. Nếu không có, Plugin vẫn đăng ký tuyến HTTP nhưng không có sự kiện chẩn đoán nào chảy vào exporter, nên phản hồi sẽ trống.

​
Các metric được xuất

MetricLoạiNhãn
openclaw_run_completed_totalbộ đếmchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalbộ đếmapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalbộ đếmfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalbộ đếmagent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalbộ đếmagent, channel, model, provider
openclaw_skill_used_totalbộ đếmactivation, agent, skill, source
openclaw_tool_execution_totalbộ đếmerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalbộ đếmdenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalbộ đếmchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalbộ đếmchannel, webhook
openclaw_webhook_error_totalbộ đếmchannel, webhook
openclaw_webhook_duration_secondshistogramchannel, webhook
openclaw_message_received_totalbộ đếmchannel, source
openclaw_message_dispatch_started_totalbộ đếmchannel, source
openclaw_message_dispatch_completed_totalbộ đếmchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramchannel, outcome, reason, source
openclaw_message_processed_totalbộ đếmchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_started_totalbộ đếmchannel, delivery_kind
openclaw_message_delivery_totalbộ đếmchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalbộ đếmbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrambrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrambrain, event_type, mode, provider, transport
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalbộ đếmreason, state
openclaw_session_queue_depthgaugestate
openclaw_session_turn_created_totalbộ đếmagent, channel, trigger
openclaw_session_stuck_totalbộ đếmreason, state
openclaw_session_stuck_age_secondshistogramreason, state
openclaw_session_recovery_totalbộ đếmaction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_liveness_warning_totalbộ đếmreason
openclaw_liveness_sessionsgaugestate
openclaw_liveness_event_loop_delay_p99_secondshistogramreason
openclaw_liveness_event_loop_delay_max_secondshistogramreason
openclaw_liveness_event_loop_utilization_ratiohistogramreason
openclaw_liveness_cpu_core_ratiohistogramreason
openclaw_payload_large_totalbộ đếmaction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaction, channel, plugin, reason, surface
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramkhông có
openclaw_memory_pressure_totalbộ đếmlevel, reason
openclaw_telemetry_exporter_totalbộ đếmexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalbộ đếmkhông có

​
Chính sách nhãn

Nhãn Prometheus luôn có giới hạn và có số lượng giá trị thấp. Exporter không phát ra các định danh chẩn đoán thô như runId, sessionKey, sessionId, callId, toolCallId, ID tin nhắn, ID cuộc trò chuyện, hoặc ID yêu cầu của provider.Giá trị nhãn được biên tập ẩn và phải khớp với chính sách ký tự số lượng giá trị thấp của OpenClaw. Các giá trị không đạt chính sách được thay bằng unknown, other, hoặc none, tùy theo metric. Các nhãn trông giống khóa phiên agent có phạm vi cũng được thay bằng unknown.
Exporter giới hạn các chuỗi thời gian được giữ trong bộ nhớ ở mức 2048 chuỗi, tính gộp trên bộ đếm, gauge và histogram. Các chuỗi mới vượt quá giới hạn đó sẽ bị bỏ, và openclaw_prometheus_series_dropped_total tăng thêm một mỗi lần.Theo dõi bộ đếm này như một tín hiệu chắc chắn rằng một thuộc tính thượng nguồn đang rò rỉ các giá trị có số lượng giá trị cao. Exporter không bao giờ tự động nâng giới hạn; nếu nó tăng, hãy sửa nguồn thay vì tắt giới hạn.
  • văn bản prompt, văn bản phản hồi, đầu vào công cụ, đầu ra công cụ, prompt hệ thống
  • bản chép lời cuộc trò chuyện, tải trọng âm thanh, id cuộc gọi, id phòng, token chuyển giao, id lượt và id phiên thô
  • ID yêu cầu nhà cung cấp thô (chỉ các hàm băm giới hạn, khi áp dụng, trên các span — không bao giờ trên metrics)
  • khóa phiên và ID phiên
  • tên máy chủ, đường dẫn tệp, giá trị bí mật

​
Công thức PromQL

# Tokens per minute, split by provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Spend (USD) over the last hour, by model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95th percentile model run duration
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# Queue wait time SLO (95p under 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Skill usage, split by bounded source
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Ưu tiên gen_ai_client_token_usage cho dashboard đa nhà cung cấp: metric này tuân theo quy ước ngữ nghĩa OpenTelemetry GenAI và nhất quán với metrics từ các dịch vụ GenAI không thuộc OpenClaw.

​
Chọn giữa xuất Prometheus và OpenTelemetry

OpenClaw hỗ trợ cả hai bề mặt một cách độc lập. Bạn có thể chạy một trong hai, cả hai hoặc không chạy cái nào.
  • Mô hình pull: Prometheus thu thập /api/diagnostics/prometheus.
  • Không cần collector bên ngoài.
  • Được xác thực qua cơ chế xác thực Gateway thông thường.
  • Bề mặt chỉ gồm metrics (không có trace hoặc log).
  • Phù hợp nhất cho các stack đã chuẩn hóa trên Prometheus + Grafana.

​
Khắc phục sự cố

  • Kiểm tra diagnostics.enabled: true trong cấu hình.
  • Xác nhận Plugin đã được bật và tải bằng openclaw plugins list --enabled.
  • Tạo một ít lưu lượng; counter và histogram chỉ phát ra dòng sau ít nhất một sự kiện.
Endpoint yêu cầu phạm vi toán tử Gateway (auth: "gateway" với gatewayRuntimeScopeSurface: "trusted-operator"). Dùng cùng token hoặc mật khẩu mà Prometheus dùng cho bất kỳ tuyến toán tử Gateway nào khác. Không có chế độ công khai không xác thực.
Một thuộc tính mới đang vượt quá giới hạn 2048 chuỗi. Kiểm tra metrics gần đây để tìm nhãn có cardinality cao bất thường và khắc phục tại nguồn. Exporter cố ý bỏ các chuỗi mới thay vì âm thầm ghi lại nhãn.
Plugin chỉ giữ trạng thái trong bộ nhớ. Sau khi Gateway khởi động lại, counter đặt lại về 0 và gauge bắt đầu lại ở giá trị được báo cáo tiếp theo. Dùng PromQL rate() và increase() để xử lý việc đặt lại một cách gọn gàng.

​
Liên quan