OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Chỉ số Prometheus

OpenClaw có thể cung cấp các chỉ số chẩn đoán thông qua Plugin chính thức diagnostics-prometheus. Plugin này lắng nghe dữ liệu chẩn đoán đáng tin cậy cùng các sự kiện chẩn đoán được gắn thẻ nội bộ và do bộ điều phối sở hữu (các tín hiệu về hàng đợi, bộ nhớ và khôi phục phiên), rồi hiển thị một điểm cuối văn bản Prometheus tại:

text
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 Prometheus tiêu chuẩn.

Đối với dấu vết, nhật ký, đẩy OTLP và các thuộc tính ngữ nghĩa GenAI của OpenTelemetry, hãy xem Xuất OpenTelemetry.

Bắt đầu nhanh

  • Cài đặt Plugin

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

  • Bật Plugin

    Cấu hình

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

    CLI

    bash
    openclaw plugins enable diagnostics-prometheus

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

  • 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 dành cho người vận hành của bạn sử dụng:

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

  • Kết nối Prometheus

    yaml
    # prometheus.ymlscrape_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ác chỉ số được xuất

    Chỉ số Loại Nhãn
    openclaw_run_completed_total bộ đếm channel, model, outcome, provider, trigger
    openclaw_run_duration_seconds histogram channel, model, outcome, provider, trigger
    openclaw_model_call_total bộ đếm api, error_category, model, outcome, provider, transport
    openclaw_model_call_duration_seconds histogram api, error_category, model, outcome, provider, transport
    openclaw_model_failover_total bộ đếm from_model, from_provider, lane, reason, suspended, to_model, to_provider
    openclaw_model_tokens_total bộ đếm agent, channel, model, provider, token_type
    openclaw_gen_ai_client_token_usage histogram model, provider, token_type
    openclaw_model_cost_usd_total bộ đếm agent, channel, model, provider
    openclaw_model_usage_duration_seconds histogram agent, channel, model, provider
    openclaw_skill_used_total bộ đếm activation, agent, skill, source
    openclaw_tool_execution_total bộ đếm error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_duration_seconds histogram error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_blocked_total bộ đếm denied_reason, params_kind, tool, tool_owner, tool_source
    openclaw_harness_run_total bộ đếm channel, error_category, harness, model, outcome, phase, plugin, provider
    openclaw_harness_run_duration_seconds histogram channel, error_category, harness, model, outcome, phase, plugin, provider
    openclaw_webhook_received_total bộ đếm channel, webhook
    openclaw_webhook_error_total bộ đếm channel, webhook
    openclaw_webhook_duration_seconds histogram channel, webhook
    openclaw_message_received_total bộ đếm channel, source
    openclaw_message_dispatch_started_total bộ đếm channel, source
    openclaw_message_dispatch_completed_total bộ đếm channel, outcome, reason, source
    openclaw_message_dispatch_duration_seconds histogram channel, outcome, reason, source
    openclaw_message_processed_total bộ đếm channel, outcome, reason
    openclaw_message_processed_duration_seconds histogram channel, outcome, reason
    openclaw_message_delivery_started_total bộ đếm channel, delivery_kind
    openclaw_message_delivery_total bộ đếm channel, delivery_kind, error_category, outcome
    openclaw_message_delivery_duration_seconds histogram channel, delivery_kind, error_category, outcome
    openclaw_talk_event_total bộ đếm brain, event_type, mode, provider, transport
    openclaw_talk_event_duration_seconds histogram brain, event_type, mode, provider, transport
    openclaw_talk_audio_bytes histogram brain, event_type, mode, provider, transport
    openclaw_queue_lane_size đồng hồ lane
    openclaw_queue_lane_wait_seconds histogram lane
    openclaw_session_state_total bộ đếm reason, state
    openclaw_session_queue_depth đồng hồ state
    openclaw_session_turn_created_total bộ đếm agent, channel, trigger
    openclaw_session_stuck_total bộ đếm reason, state
    openclaw_session_stuck_age_seconds histogram reason, state
    openclaw_session_recovery_total bộ đếm action, active_work_kind, state, status
    openclaw_session_recovery_age_seconds histogram action, active_work_kind, state, status
    openclaw_liveness_warning_total bộ đếm reason
    openclaw_liveness_sessions đồng hồ state
    openclaw_liveness_event_loop_delay_p99_seconds histogram reason
    openclaw_liveness_event_loop_delay_max_seconds histogram reason
    openclaw_liveness_event_loop_utilization_ratio histogram reason
    openclaw_liveness_cpu_core_ratio histogram reason
    openclaw_payload_large_total bộ đếm action, channel, plugin, reason, surface
    openclaw_payload_large_bytes histogram action, channel, plugin, reason, surface
    openclaw_memory_bytes đồng hồ kind
    openclaw_memory_rss_bytes histogram không có
    openclaw_memory_pressure_total bộ đếm level, reason
    openclaw_telemetry_exporter_total bộ đếm exporter, reason, signal, status
    openclaw_prometheus_series_dropped_total bộ đếm không có
    openclaw_diagnostic_async_queue_dropped_total bộ đếm drop_class
    openclaw_diagnostic_async_queue_length đồng hồ không có

    Chính sách nhãn

    Nhãn có giới hạn và độ phân biệt thấp

    Các nhãn Prometheus luôn có giới hạn và độ phân biệt thấp. Trình xuất không phát ra các mã định danh chẩn đoán thô như runId, sessionKey, sessionId, callId, toolCallId, mã định danh tin nhắn, mã định danh cuộc trò chuyện hoặc mã định danh yêu cầu của nhà cung cấp.

    Các giá trị nhãn được biên tập ẩn và phải tuân thủ chính sách ký tự có độ phân biệt thấp của OpenClaw. Các giá trị không đáp ứng chính sách sẽ được thay thế bằng unknown, other hoặc none, tùy theo chỉ số. Các nhãn có dạng khóa phiên tác nhân có phạm vi cũng được thay thế bằng unknown.

    Giới hạn chuỗi và thống kê phần vượt mức

    Trình xuất giới hạn số chuỗi thời gian được lưu trong bộ nhớ ở mức 2048 chuỗi, tính tổng trên các bộ đếm, đồng hồ đo và histogram. Các chuỗi mới vượt quá giới hạn này sẽ bị loại bỏ và openclaw_prometheus_series_dropped_total tăng thêm một sau mỗi lần.

    Hãy theo dõi bộ đếm này như một tín hiệu chắc chắn cho thấy một thuộc tính ở thượng nguồn đang làm rò rỉ các giá trị có lực lượng lớn. Trình xuất không bao giờ tự động nâng giới hạn; nếu bộ đếm tăng, hãy khắc phục nguồn thay vì vô hiệu hóa giới hạn.

    Những nội dung không bao giờ xuất hiện trong đầu ra Prometheus
    • văn bản lời nhắc, văn bản phản hồi, đầu vào công cụ, đầu ra công cụ, lời nhắc hệ thống
    • bản chép lời Talk, tải trọng âm thanh, mã cuộc gọi, mã phòng, token chuyển giao, mã lượt và mã phiên thô
    • mã yêu cầu thô của nhà cung cấp (chỉ có các giá trị băm hữu hạn, nếu áp dụng, trên các span — không bao giờ có trên số liệu)
    • khóa phiên và mã phiên
    • tên máy chủ, đường dẫn tệp, giá trị bí mật

    Công thức PromQL

    promql
    # Số token mỗi phút, phân tách theo nhà cung cấpsum by (provider) (rate(openclaw_model_tokens_total[1m])) # Chi phí (USD) trong giờ vừa qua, theo mô hìnhsum by (model) (increase(openclaw_model_cost_usd_total[1h])) # Phân vị thứ 95 của thời lượng chạy mô hìnhhistogram_quantile(  0.95,  sum by (le, provider, model)    (rate(openclaw_run_duration_seconds_bucket[5m]))) # SLO thời gian chờ hàng đợi (phân vị 95 dưới 2 giây)histogram_quantile(  0.95,  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))) < 2 # Mức sử dụng Skill, phân tách theo nguồn hữu hạnsum by (skill, source) (increase(openclaw_skill_used_total[24h])) # Chuỗi Prometheus bị loại bỏ (cảnh báo lực lượng)increase(openclaw_prometheus_series_dropped_total[15m]) > 0

    Lựa chọn giữa xuất Prometheus và OpenTelemetry

    OpenClaw hỗ trợ độc lập cả hai bề mặt. Bạn có thể chạy một trong hai, cả hai hoặc không chạy bề mặt nào.

    diagnostics-prometheus

    • Mô hình kéo: Prometheus thu thập dữ liệu từ /api/diagnostics/prometheus.
    • Không yêu cầu trình thu thập bên ngoài.
    • Được xác thực thông qua cơ chế xác thực Gateway thông thường.
    • Bề mặt chỉ gồm số liệu (không có dấu vết hoặc nhật ký).
    • Phù hợp nhất với các hệ thống đã chuẩn hóa trên Prometheus + Grafana.

    diagnostics-otel

    • Mô hình đẩy: OpenClaw gửi OTLP/HTTP đến một trình thu thập hoặc phần phụ trợ tương thích với OTLP.
    • Bề mặt bao gồm số liệu, dấu vết và nhật ký.
    • Kết nối với Prometheus thông qua OpenTelemetry Collector (trình xuất prometheus hoặc prometheusremotewrite) khi bạn cần cả hai.
    • Xem Xuất OpenTelemetry để biết danh mục đầy đủ.

    Khắc phục sự cố

    Nội dung phản hồi trống
    • Kiểm tra để bảo đảm diagnostics.enabled không được đặt thành false trong cấu hình (giá trị mặc định là true).
    • 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; các bộ đếm và histogram chỉ xuất dòng sau khi có ít nhất một sự kiện.
    401 / không được ủy quyền

    Điểm cuối yêu cầu phạm vi người vận hành Gateway (auth: "gateway" với gatewayRuntimeScopeSurface: "trusted-operator"). Hãy dùng cùng token hoặc mật khẩu mà Prometheus sử dụng cho bất kỳ tuyến người vận hành Gateway nào khác. Không có chế độ công khai không cần xác thực.

    `openclaw_prometheus_series_dropped_total` đang tăng

    Một thuộc tính mới đang vượt quá giới hạn 2048 chuỗi. Hãy kiểm tra các số liệu gần đây để tìm một nhãn có lực lượng cao ngoài dự kiến và khắc phục tại nguồn. Trình xuất chủ ý loại bỏ các chuỗi mới thay vì âm thầm viết lại nhãn.

    Prometheus hiển thị các chuỗi cũ sau khi khởi động lại

    Plugin chỉ lưu trạng thái trong bộ nhớ. Sau khi Gateway khởi động lại, các bộ đếm được đặt lại về không và các đồng hồ đo bắt đầu lại từ giá trị được báo cáo tiếp theo. Hãy dùng rate() và increase() của PromQL để xử lý việc đặt lại một cách chính xác.

    Liên quan

    Was this useful?
    On this page

    On this page