> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Prometheus

> Kết nối Prometheus, Thanos, VictoriaMetrics hoặc Grafana Cloud để truy vấn PromQL chỉ đọc, khám phá metric, kiểm tra sức khỏe target và xem xét alert

Kết nối backend giám sát tương thích Prometheus của bạn để cho phép các agent CloudThinker chạy truy vấn PromQL, khám phá metric và label, kiểm tra sức khỏe scrape-target và tương quan các alert đang hoạt động — tất cả đều chỉ đọc.

<Info>
  Connector hoạt động với bất kỳ backend nào tuân theo Prometheus HTTP API tiêu chuẩn: self-hosted **Prometheus**, **Thanos**, **VictoriaMetrics** và **Grafana Cloud**. Xác thực hỗ trợ **None**, **Bearer Token** và **Basic Auth**.
</Info>

***

## Nền tảng hỗ trợ

| Nền tảng            | Hỗ trợ                                | Xác thực thông thường    |
| ------------------- | ------------------------------------- | ------------------------ |
| **Prometheus**      | Self-hosted, tất cả phiên bản gần đây | None hoặc Bearer         |
| **Thanos**          | Querier phía sau auth proxy           | None, Bearer, hoặc Basic |
| **VictoriaMetrics** | Single-node và cluster                | None hoặc Basic          |
| **Grafana Cloud**   | Endpoint Prometheus / Mimir           | Basic                    |

<Note>
  Với các endpoint managed, được Mimir hỗ trợ (Grafana Cloud), các đường dẫn `/api/v1/targets`, `/rules` và `/alerts` không được expose và trả về 404. Điều này là bình thường — query API (truy vấn tức thời, truy vấn phạm vi, label và metadata) hoạt động bình thường.
</Note>

***

## Điều kiện tiên quyết

* Một **endpoint tương thích Prometheus** có thể truy cập từ CloudThinker qua HTTPS — Prometheus tự lưu trữ, Thanos, VictoriaMetrics hoặc Grafana Cloud.
* Thông tin xác thực nếu endpoint yêu cầu: bearer token (chế độ Bearer Token) hoặc tên người dùng và mật khẩu (chế độ Basic Auth).
* Với **Grafana Cloud**, cần numeric instance ID và access-policy token có phạm vi **metrics:read**.

***

## Chọn chế độ xác thực

Chọn chế độ phù hợp với cách endpoint của bạn được expose:

| Chế độ           | Khi nào dùng                                                                          | Trường                    |
| ---------------- | ------------------------------------------------------------------------------------- | ------------------------- |
| **None**         | Endpoint mở hoặc hạn chế mạng (Prometheus tự lưu trữ trong mạng nội bộ)               | Chỉ URL                   |
| **Bearer Token** | Endpoint phía sau proxy hoặc gateway yêu cầu `Authorization: Bearer <token>`          | URL + token               |
| **Basic Auth**   | Grafana Cloud, Thanos phía sau auth proxy, hoặc VictoriaMetrics với username/password | URL + username + password |

<Tip>
  Với **Grafana Cloud**, username là numeric instance ID của bạn và password là access-policy token có phạm vi đọc metric.
</Tip>

***

## Thiết lập

<Steps>
  <Step title="Tìm URL Prometheus của bạn">
    Xác định URL cơ sở của Prometheus HTTP API, ví dụ: `https://prometheus.your-domain.com` hoặc endpoint Prometheus query của Grafana Cloud. CloudThinker sẽ thêm các đường dẫn `/api/v1/...` tiêu chuẩn.
  </Step>

  <Step title="Chuẩn bị thông tin xác thực (nếu cần)">
    * **None** — không cần chuẩn bị gì; endpoint có thể truy cập mà không cần xác thực.
    * **Bearer Token** — lấy bearer token mà proxy hoặc gateway của bạn yêu cầu.
    * **Basic Auth** — lấy username và password (với Grafana Cloud, cần numeric instance ID và access-policy token).
  </Step>

  <Step title="Thêm kết nối trong CloudThinker">
    Điều hướng đến **Connections → Prometheus** và nhập:

    * **PROMETHEUS\_URL**: endpoint của bạn, ví dụ: `https://prometheus.your-domain.com`
    * **PROMETHEUS\_AUTH\_TYPE**: chọn **None**, **Bearer Token** hoặc **Basic Auth**

    Các trường thông tin xác thực xuất hiện dựa trên lựa chọn của bạn:

    * **Bearer Token** → **PROMETHEUS\_TOKEN**
    * **Basic Auth** → **PROMETHEUS\_USERNAME** và **PROMETHEUS\_PASSWORD**

    Nhấn **Connect**. CloudThinker xác minh endpoint và hiển thị trạng thái **Connected**.
  </Step>
</Steps>

***

## Chi tiết kết nối

| Trường                     | Mô tả                                                                 | Ví dụ                                |
| -------------------------- | --------------------------------------------------------------------- | ------------------------------------ |
| **PROMETHEUS\_URL**        | URL cơ sở của Prometheus HTTP API                                     | `https://prometheus.your-domain.com` |
| **PROMETHEUS\_AUTH\_TYPE** | Chế độ xác thực: `none`, `bearer` hoặc `basic`                        | `basic`                              |
| **PROMETHEUS\_TOKEN**      | Bearer token (chỉ chế độ Bearer Token)                                | `eyJhbGci...`                        |
| **PROMETHEUS\_USERNAME**   | Username, hoặc numeric instance ID cho Grafana Cloud (chỉ Basic Auth) | `1234567`                            |
| **PROMETHEUS\_PASSWORD**   | Password hoặc access-policy token (chỉ Basic Auth)                    | `glc_xxxxx...`                       |

***

## Quyền yêu cầu

Connector Prometheus **chỉ đọc** — agent truy vấn và kiểm tra nhưng không bao giờ ghi vào backend giám sát.

* Với **Grafana Cloud**, tạo access-policy token chỉ với phạm vi **metrics:read**.
* Với endpoint được bảo vệ, đảm bảo thông tin xác thực có thể truy cập các đường dẫn API query, label, target, rule và alert.

<Tip>
  Trên Grafana Cloud, giới hạn access-policy token chỉ với `metrics:read` — không cần phạm vi nào khác cho CloudThinker.
</Tip>

***

## Khả năng của agent

Connector Prometheus chỉ đọc — agent truy vấn và kiểm tra, nhưng không bao giờ sửa đổi backend giám sát.

| Khả năng              | Những gì agent có thể làm                                                           |
| --------------------- | ----------------------------------------------------------------------------------- |
| **Truy vấn tức thời** | Chạy biểu thức PromQL tại một thời điểm cụ thể                                      |
| **Truy vấn phạm vi**  | Chạy biểu thức PromQL trong khoảng thời gian với bước interval                      |
| **Khám phá metric**   | Liệt kê tên metric có sẵn, tùy chọn lọc theo prefix                                 |
| **Liệt kê label**     | Liệt kê tên label và kiểm tra các dimension mà metric được phân chia                |
| **Sức khỏe target**   | Kiểm tra các scrape target và phát hiện những target đang down hoặc không lành mạnh |
| **Kiểm tra alert**    | Liệt kê các alert đang hoạt động và xem lại quy tắc alert đã cấu hình               |
| **Health probe**      | Chạy truy vấn `up` chung để xác nhận backend và các target của nó có thể truy cập   |

### Xác minh kết nối

```text theme={null}
@alex run the Prometheus health probe and confirm all scrape targets are reachable
```

### Ví dụ prompt

```text theme={null}
@alex query node_cpu utilization across the cluster for the last hour and #report anything sustained above 85%
@kai list scrape targets that are currently down and #report which jobs they belong to
@alex show all active alerts and #recommend which to investigate first
```

<Note>
  Prometheus không expose công cụ nào cho **giá trị** label — liệt kê label chỉ trả về **tên** label. Hãy chỉ rõ metric và các label bạn quan tâm để agent có thể xây dựng PromQL selector chính xác.
</Note>

***

## Xử lý sự cố

<Accordion title="Kết nối hoặc truy vấn thất bại với 401 Unauthorized">
  * Xác nhận **PROMETHEUS\_AUTH\_TYPE** khớp với những gì endpoint yêu cầu.
  * Với **Bearer**, xác minh token còn hiện hành và chưa bị thu hồi.
  * Với **Basic**, xác minh username/password — trên Grafana Cloud, username là numeric instance ID và password là access-policy token.
</Accordion>

<Accordion title="Target, rule hoặc alert trả về 404">
  * Được kỳ vọng trên các endpoint managed, được Mimir hỗ trợ (Grafana Cloud) — các đường dẫn này không được expose.
  * Query API (tức thời, phạm vi, label, metadata) vẫn hoạt động; dùng truy vấn thay vì kiểm tra target/rule.
</Accordion>

<Accordion title="Kết nối không thể đến endpoint">
  * Xác minh **PROMETHEUS\_URL** có thể truy cập từ CloudThinker qua HTTPS.
  * Với endpoint tự lưu trữ hoặc hạn chế mạng, xác nhận có đường dẫn mạng từ CloudThinker.
  * Bỏ bất kỳ `/api/v1` đuôi nào khỏi URL — chỉ nhập URL cơ sở.
</Accordion>

<Accordion title="Truy vấn trả về kết quả rỗng">
  * Xác nhận metric tồn tại bằng truy vấn khám phá trước khi lọc theo label.
  * Mở rộng cửa sổ thời gian — series có thể không có sample trong phạm vi được yêu cầu.
</Accordion>

***

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Thiết kế chỉ đọc** — connector không bao giờ ghi vào backend giám sát; không cần quyền ghi
- **Thông tin xác thực quyền tối thiểu** — trên Grafana Cloud, giới hạn access-policy token chỉ cho phạm vi đọc metric

***

## Liên quan

<CardGroup cols={2}>
  <Card title="Kết nối Grafana" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/grafana.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c1329049025cd3c3a0909b400baef7be" href="/vi/guide/connections/grafana" width="24" height="24" data-path="images/icons/grafana.svg">
    Dashboard và quan sát hợp nhất
  </Card>

  <Card title="Kết nối Datadog" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/datadog.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=e8382167f2a1eb1e00971b5f4d703d48" href="/vi/guide/connections/datadog" width="24" height="24" data-path="images/icons/datadog.svg">
    Tìm kiếm log, metric và giám sát hạ tầng
  </Card>
</CardGroup>