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

Documentation Index

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

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

OpenClaw có thể công bố số liệu chẩn đoán thông qua Plugin diagnostics-prometheus chính thức. Plugin này lắng nghe chẩn đoán nội bộ đáng tin cậy và hiển thị một điểm cuối văn bản Prometheus tại: 
GET /api/diagnostics/prometheus
Loại 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.
Tuyến dùng xác thực Gateway (phạm vi người vận hành). Không công bố tuyến này như một điểm cuối /metrics công khai không cần xác thực. Hãy thu thập dữ liệu 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 dấu vết, nhật ký, đẩy OTLP và 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

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

Thu thập dữ liệu từ tuyến đượ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 dùng:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

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"]
diagnostics.enabled: true là bắt buộc. 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 đi vào trình xuất, vì vậy phản hồi sẽ trống.

​
Số liệu được xuất

Số liệuLoạiNhãn
openclaw_run_completed_totalbộ đếmchannel, model, outcome, provider, trigger
openclaw_run_duration_secondsbiểu đồchannel, model, outcome, provider, trigger
openclaw_model_call_totalbộ đếmapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondsbiểu đồapi, error_category, model, outcome, provider, transport
openclaw_model_tokens_totalbộ đếmagent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagebiểu đồmodel, provider, token_type
openclaw_model_cost_usd_totalbộ đếmagent, channel, model, provider
openclaw_tool_execution_totalbộ đếmerror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondsbiểu đồerror_category, outcome, params_kind, tool
openclaw_harness_run_totalbộ đếmchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondsbiểu đồchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_message_processed_totalbộ đếmchannel, outcome, reason
openclaw_message_processed_duration_secondsbiểu đồchannel, outcome, reason
openclaw_message_delivery_started_totalbộ đếmchannel, delivery_kind
openclaw_message_delivery_totalbộ đếmchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondsbiểu đồchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalbộ đếmbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondsbiểu đồbrain, event_type, mode, provider, transport
openclaw_talk_audio_bytesbiểu đồbrain, event_type, mode, provider, transport
openclaw_queue_lane_sizethước đolane
openclaw_queue_lane_wait_secondsbiểu đồlane
openclaw_session_state_totalbộ đếmreason, state
openclaw_session_queue_depththước đostate
openclaw_session_recovery_totalbộ đếmaction, active_work_kind, state, status
openclaw_session_recovery_age_secondsbiểu đồaction, active_work_kind, state, status
openclaw_memory_bytesthước đokind
openclaw_memory_rss_bytesbiểu đồkhô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à số lượng giá trị thấp. Trình xuất 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 trò chuyện hoặc ID yêu cầu của nhà cung cấp.Giá trị nhãn được biên tập lại và phải khớp với chính sách ký tự có số lượng giá trị thấp của OpenClaw. Các giá trị không đáp ứng chính sách sẽ được thay bằng unknown, other hoặc none, tùy theo số liệu.
Trình xuất giới hạn số chuỗi thời gian được giữ trong bộ nhớ ở mức 2048 chuỗi, tính gộp cho counter, gauge và histogram. Các 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 rõ ràng rằng một thuộc tính ở thượng nguồn đang rò rỉ các giá trị có độ đa dạng cao. Trình xuất không bao giờ tự động nâng giới hạn; nếu chỉ số này 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
  • Bản ghi cuộc trò chuyện Talk, 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ỉ dùng hash có giới hạn, khi áp dụng, trên span — không bao giờ trên metric)
  • 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 trên nhiều nhà cung cấp: metric này tuân theo các quy ước ngữ nghĩa OpenTelemetry GenAI và nhất quán với metric 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 lập cả hai bề mặt này. 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 kéo: Prometheus scrape /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ỉ có metric (không có trace hoặc log).
  • Phù hợp nhất với 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 khi có ít nhất một sự kiện.
Endpoint yêu cầu phạm vi điều hành Gateway (auth: "gateway" với gatewayRuntimeScopeSurface: "trusted-operator"). Dùng cùng token hoặc mật khẩu mà Prometheus dùng cho mọi route điều hành Gateway 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 metric gần đây để tìm một nhãn có độ đa dạng cao bất thường và sửa tại nguồn. Trình xuất cố ý loại bỏ các 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ề 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ý các lần đặt lại một cách gọn gàng.

​
Liên quan