Chuyển đến nội dung chính

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw có thể hiển thị các chỉ số chẩn đoán thông qua Plugin diagnostics-prometheus được đi kèm. Plugin này lắng nghe các chẩn đoán nội bộ đáng tin cậy và hiển thị một endpoint 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 hiển thị tiêu chuẩn của Prometheus.
Route này dùng xác thực Gateway (phạm vi operator). Không để lộ route này như một endpoint /metrics công khai không xác thực. Hãy scrape route này qua cùng đường dẫn xác thực mà bạn dùng cho các API operator khác.
Đối với trace, log, OTLP push và thuộc tính ngữ nghĩa OpenTelemetry GenAI, xem Xuất OpenTelemetry.

​
Bắt đầu nhanh

1

Bật Plugin

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

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.
3

Scrape route được bảo vệ

Gửi cùng xác thực gateway mà các client operator của bạn dùng:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
4

Kết nối 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"]
Cần có diagnostics.enabled: true. Nếu không, Plugin vẫn đăng ký route 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.

​
Chỉ số được xuất

Chỉ sốLoạiNhãn
openclaw_run_completed_totalcounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalcounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_tokens_totalcounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalcounteragent, channel, model, provider
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool
openclaw_harness_run_totalcounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramkhông có
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounterkhông có

​
Chính sách nhãn

Nhãn Prometheus luôn có giới hạn và cardinality thấp. Exporter không phát ra mã đị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 provider.Giá trị nhãn được biên tập lại và phải khớp với chính sách ký tự cardinality 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 chỉ số.
Exporter giới hạn số chuỗi thời gian được giữ trong bộ nhớ ở mức 2048 chuỗi tổng cộng trên counter, gauge và histogram. Chuỗi mới vượt quá giới hạn đó sẽ bị loại bỏ, và openclaw_prometheus_series_dropped_total tăng thêm một mỗi lần.Theo dõi counter này như một tín hiệu chắc chắn rằng một thuộc tính phía upstream đang rò rỉ giá trị cardinality cao. Exporter không bao giờ tự động nâng giới hạn; nếu giá trị 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ụ, system prompt
  • ID yêu cầu provider thô (chỉ có hash có giới hạn, khi áp dụng, trên span — không bao giờ trên chỉ số)
  • khóa phiên và ID phiên
  • hostname, đườ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

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Ưu tiên gen_ai_client_token_usage cho dashboard xuyên provider: chỉ số này tuân theo quy ước ngữ nghĩa OpenTelemetry GenAI và nhất quán với chỉ số 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 cái nào.
  • Mô hình pull: Prometheus scrape /api/diagnostics/prometheus.
  • Không cần collector bên ngoài.
  • Được xác thực qua xác thực Gateway thông thường.
  • Bề mặt chỉ là chỉ số (không có trace hoặc log).
  • Phù hợp nhất cho stack đã tiêu 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 khi có ít nhất một sự kiện.
Endpoint yêu cầu phạm vi operator của 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ỳ route operator 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 các chỉ số gần đây để tìm nhãn có cardinality cao bất thường và sửa tại nguồn. Exporter cố ý loại bỏ chuỗi mới thay vì âm thầm viết 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ề không 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ý reset gọn gàng.

​
Liên quan