---
read_when:
    - Bạn muốn Prometheus, Grafana, VictoriaMetrics hoặc một trình thu thập khác thu thập các chỉ số của OpenClaw Gateway
    - Bạn cần tên chỉ số Prometheus và chính sách nhãn cho bảng điều khiển hoặc cảnh báo
    - Bạn muốn có chỉ số mà không cần chạy bộ thu thập OpenTelemetry
sidebarTitle: Prometheus
summary: Cung cấp chẩn đoán OpenClaw dưới dạng chỉ số văn bản Prometheus thông qua Plugin diagnostics-prometheus
title: Chỉ số Prometheus
x-i18n:
    generated_at: "2026-05-02T20:44:23Z"
    model: gpt-5.5
    provider: openai
    source_hash: 49df17348c5b63c4b5f3c05f3378d43764e5de985135ad30c1e74ef607e0dd37
    source_path: gateway/prometheus.md
    workflow: 16
---

OpenClaw có thể phơi bày các chỉ số 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à kết xuất một endpoint 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 phơi bày Prometheus tiêu chuẩn.

<Warning>
Tuyến này sử dụng xác thực Gateway (phạm vi operator). Không phơi bày nó dưới dạng endpoint `/metrics` công khai không xác thực. Thu thập qua cùng đường dẫn xác thực mà bạn dùng cho các API operator khác.
</Warning>

Đối với trace, log, đẩy OTLP và thuộc tính ngữ nghĩa OpenTelemetry GenAI, xem [Xuất OpenTelemetry](/vi/gateway/opentelemetry).

## Bắt đầu nhanh

<Steps>
  <Step title="Cài đặt Plugin">
    ```bash
    openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
    ```
  </Step>
  <Step title="Bật Plugin">
    <Tabs>
      <Tab title="Cấu hình">
        ```json5
        {
          plugins: {
            allow: ["diagnostics-prometheus"],
            entries: {
              "diagnostics-prometheus": { enabled: true },
            },
          },
          diagnostics: {
            enabled: true,
          },
        }
        ```
      </Tab>
      <Tab title="CLI">
        ```bash
        openclaw plugins enable diagnostics-prometheus
        ```
      </Tab>
    </Tabs>
  </Step>
  <Step title="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.
  </Step>
  <Step title="Thu thập tuyến được bảo vệ">
    Gửi cùng xác thực gateway mà các client operator của bạn sử dụng:

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

  </Step>
  <Step title="Kết nối Prometheus">
    ```yaml
    # 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"]
    ```
  </Step>
</Steps>

<Note>
Bắt buộc phải 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.
</Note>

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

| Chỉ số                                        | Loại      | Nhãn                                                                                      |
| --------------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
| `openclaw_run_completed_total`                | counter   | `channel`, `model`, `outcome`, `provider`, `trigger`                                      |
| `openclaw_run_duration_seconds`               | histogram | `channel`, `model`, `outcome`, `provider`, `trigger`                                      |
| `openclaw_model_call_total`                   | counter   | `api`, `error_category`, `model`, `outcome`, `provider`, `transport`                      |
| `openclaw_model_call_duration_seconds`        | histogram | `api`, `error_category`, `model`, `outcome`, `provider`, `transport`                      |
| `openclaw_model_tokens_total`                 | counter   | `agent`, `channel`, `model`, `provider`, `token_type`                                     |
| `openclaw_gen_ai_client_token_usage`          | histogram | `model`, `provider`, `token_type`                                                         |
| `openclaw_model_cost_usd_total`               | counter   | `agent`, `channel`, `model`, `provider`                                                   |
| `openclaw_tool_execution_total`               | counter   | `error_category`, `outcome`, `params_kind`, `tool`                                        |
| `openclaw_tool_execution_duration_seconds`    | histogram | `error_category`, `outcome`, `params_kind`, `tool`                                        |
| `openclaw_harness_run_total`                  | counter   | `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_message_processed_total`            | counter   | `channel`, `outcome`, `reason`                                                            |
| `openclaw_message_processed_duration_seconds` | histogram | `channel`, `outcome`, `reason`                                                            |
| `openclaw_message_delivery_total`             | counter   | `channel`, `delivery_kind`, `error_category`, `outcome`                                   |
| `openclaw_message_delivery_duration_seconds`  | histogram | `channel`, `delivery_kind`, `error_category`, `outcome`                                   |
| `openclaw_queue_lane_size`                    | gauge     | `lane`                                                                                    |
| `openclaw_queue_lane_wait_seconds`            | histogram | `lane`                                                                                    |
| `openclaw_session_state_total`                | counter   | `reason`, `state`                                                                         |
| `openclaw_session_queue_depth`                | gauge     | `state`                                                                                   |
| `openclaw_memory_bytes`                       | gauge     | `kind`                                                                                    |
| `openclaw_memory_rss_bytes`                   | histogram | không có                                                                                  |
| `openclaw_memory_pressure_total`              | counter   | `level`, `reason`                                                                         |
| `openclaw_telemetry_exporter_total`           | counter   | `exporter`, `reason`, `signal`, `status`                                                  |
| `openclaw_prometheus_series_dropped_total`    | counter   | không có                                                                                  |

## Chính sách nhãn

<AccordionGroup>
  <Accordion title="Nhãn bị giới hạn, số lượng giá trị thấp">
    Nhãn Prometheus luôn bị 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 chat 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ự số lượng giá trị thấp của OpenClaw. Các giá trị không đạt chính sách sẽ được thay bằng `unknown`, `other` hoặc `none`, tùy theo chỉ số.

  </Accordion>
  <Accordion title="Giới hạn chuỗi và hạch toán tràn">
    Exporter giới hạn số chuỗi thời gian được giữ trong bộ nhớ ở mức **2048** chuỗi cho tổng hợp 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 cứng rằng một thuộc tính upstream đang rò rỉ 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.

  </Accordion>
  <Accordion title="Những gì không bao giờ xuất hiện trong đầu ra Prometheus">
    - văn bản prompt, văn bản phản hồi, đầu vào tool, đầu ra tool, system prompt
    - ID yêu cầu provider thô (chỉ có hash bị 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

  </Accordion>
</AccordionGroup>

## Công thức PromQL

```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
```

<Tip>
Ưu tiên `gen_ai_client_token_usage` cho dashboard nhiều provider: nó tuân theo quy ước ngữ nghĩa OpenTelemetry GenAI và nhất quán với các metric từ dịch vụ GenAI không thuộc OpenClaw.
</Tip>

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

<Tabs>
  <Tab title="diagnostics-prometheus">
    - 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 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 cho các stack đã chuẩn hóa trên Prometheus + Grafana.

  </Tab>
  <Tab title="diagnostics-otel">
    - Mô hình **push**: OpenClaw gửi OTLP/HTTP tới collector hoặc backend tương thích OTLP.
    - Bề mặt bao gồm metric, trace và log.
    - Kết nối sang Prometheus thông qua OpenTelemetry Collector (exporter `prometheus` hoặc `prometheusremotewrite`) khi bạn cần cả hai.
    - Xem [Xuất OpenTelemetry](/vi/gateway/opentelemetry) để biết danh mục đầy đủ.

  </Tab>
</Tabs>

## Khắc phục sự cố

<AccordionGroup>
  <Accordion title="Thân phản hồi trống">
    - 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.

  </Accordion>
  <Accordion title="401 / unauthorized">
    Endpoint yêu cầu phạm vi operator 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 tuyến operator Gateway khác. Không có chế độ công khai không xác thực.
  </Accordion>
  <Accordion title="`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. Kiểm tra các metric gần đây để tìm nhãn có số lượng giá trị 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.
  </Accordion>
  <Accordion title="Prometheus hiển thị chuỗi cũ sau khi khởi động lại">
    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 khởi động lại ở giá trị được báo cáo tiếp theo. Dùng PromQL `rate()` và `increase()` để xử lý reset sạch sẽ.
  </Accordion>
</AccordionGroup>

## Liên quan

- [Xuất chẩn đoán](/vi/gateway/diagnostics) — tệp zip chẩn đoán cục bộ cho gói hỗ trợ
- [Sức khỏe và mức sẵn sàng](/vi/gateway/health) — probe `/healthz` và `/readyz`
- [Ghi log](/vi/logging) — ghi log dựa trên tệp
- [Xuất OpenTelemetry](/vi/gateway/opentelemetry) — đẩy OTLP cho trace, metric và log
