> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/vi/module-9-giam-sat-and-khac-phuc-su-co/04-prometheus-grafana.md).

# Tích hợp Prometheus & Grafana

## Tại sao các chỉ số bên ngoài quan trọng

Bảng điều khiển VergeOS cung cấp tình trạng và phân tích theo thời gian thực, nhưng các chiến lược giám sát doanh nghiệp thường yêu cầu một kho lưu trữ tập trung, theo chuỗi thời gian, có thể tổng hợp số liệu trên nhiều hệ thống, lưu giữ dữ liệu vượt quá cửa sổ 45 ngày trong giao diện, và kích hoạt các quy tắc cảnh báo tinh vi. Trình **vergeos-exporter** lấp đầy khoảng trống này bằng cách hiển thị các chỉ số VergeOS ở định dạng Prometheus -- tiêu chuẩn thực tế cho giám sát cloud-native.

Khi exporter chạy, bạn có được phân tích xu hướng dài hạn, tương quan giữa các hệ thống, và tích hợp với các pipeline cảnh báo hiện có -- tất cả mà không cần sửa đổi chính hệ thống VergeOS.

```mermaid
graph LR
    subgraph vergeos["Môi trường VergeOS"]
        API["API REST VergeOS"]
    end

    subgraph monitoring["Ngăn xếp giám sát"]
        EXP["vergeos-exporter<br/>:9888/metrics"]
        PROM["Prometheus<br/>Quét & Lưu trữ"]
        GRAF["Grafana<br/>Bảng điều khiển"]
        ALERT["AlertManager<br/>Thông báo"]
    end

    API -->|"Cuộc gọi API<br/>(list/read)"| EXP
    EXP -->|"Quét<br/>dựa trên pull"| PROM
    PROM --> GRAF
    PROM --> ALERT
    ALERT -->|"Email, Slack,<br/>PagerDuty"| OPS["Nhóm Ops"]

    style vergeos fill:#f0f4ff,stroke:#336
    style monitoring fill:#f0fff4,stroke:#363
```

## Trình xuất vergeos-exporter

Tính năng **vergeos-exporter** là một công cụ mã nguồn mở do Verge duy trì trong [verge-io/vergeos-exporter](https://github.com/verge-io/vergeos-exporter) kho lưu trữ GitHub. Nó kết nối với VergeOS REST API, thu thập các chỉ số hạ tầng, và hiển thị chúng trên một điểm cuối HTTP mà Prometheus quét theo khoảng thời gian có thể cấu hình.

### Các chỉ số được hiển thị

Exporter thu thập ba nhóm chỉ số:

### Chỉ số lớp vSAN

Dung lượng, mức sử dụng, và phân bổ theo từng lớp. Số lượng giao dịch và sửa chữa. Giám sát trạng thái ổ đĩa (online, offline, repairing, initializing, verifying, noredundant, outofspace). Dữ liệu nhiệt độ và tình trạng ổ đĩa. Các thao tác đọc/ghi và IOPS.

### Chỉ số cụm

Số nút trên mỗi cụm. Mức sử dụng RAM, CPU, và đĩa. Trạng thái đồng bộ và tình trạng.

### Chỉ số nút

Mức sử dụng CPU và bộ nhớ theo từng nút. Thông lượng mạng và độ trễ. Trạng thái dịch vụ trên mỗi nút.

Một tài liệu tham chiếu đầy đủ về các chỉ số có sẵn trong `metrics.md` trong kho lưu trữ của exporter.

### Kiến trúc: Quét dựa trên pull

vergeos-exporter tuân theo mô hình pull tiêu chuẩn của Prometheus. Prometheus khởi tạo kết nối bằng cách quét `/metrics` điểm cuối trên exporter theo một khoảng thời gian đã cấu hình (thường là 15–60 giây). Cách tiếp cận này có nghĩa là:

* **Không cần quy tắc tường lửa inbound** được yêu cầu trên chính hệ thống VergeOS
* Exporter có thể chạy trên **bất kỳ máy chủ nào** có quyền truy cập mạng vào API VergeOS
* Nhiều phiên bản Prometheus có thể quét cùng một exporter để HA
* Exporter **tương thích với AlertManager** -- các quy tắc cảnh báo của Prometheus hoạt động nguyên bản với các chỉ số được hiển thị

## Cấu hình tài khoản dịch vụ

Trước khi triển khai exporter, hãy tạo một tài khoản dịch vụ chuyên dụng trong VergeOS với đặc quyền tối thiểu.

### Từng bước: Tạo tài khoản dịch vụ cho exporter

1. Đi tới **Hệ thống → Người dùng** trong giao diện VergeOS
2. Nhấp **Mới** để tạo người dùng mới
3. Điền vào **Người dùng mới** biểu mẫu:
   * **Tên người dùng:** `prometheus-exporter` (hoặc tên mô tả tương tự)
   * **Loại:** `API`
   * **Mật khẩu:** một giá trị mạnh, được tạo ngẫu nhiên
   * **Xác thực hai yếu tố:** để **bỏ chọn** -- exporter xác thực qua tên người dùng/mật khẩu API
4. Nhấp **Gửi** để lưu

Người dùng Normal/API mới mặc định sẽ nhận **list/read trên mọi thứ** theo mặc định, đúng chính xác những gì exporter cần. Để thu hẹp phạm vi hơn nữa, hãy thu gọn các quyền cấp dưới **Hệ thống → Quyền** sau khi người dùng được tạo.

{% hint style="warning" %}
**Thực hành tốt nhất về bảo mật**

Không bao giờ dùng tài khoản quản trị cho exporter. Tài khoản dịch vụ chỉ cần quyền list và read để truy vấn chỉ số, vì vậy hãy giữ các mặc định hoặc thu hẹp chúng dưới **Hệ thống → Quyền** -- và bù đắp cho thông tin xác thực máy-máy bằng cách dùng mật khẩu mạnh, tạo ngẫu nhiên và hạn chế quyền truy cập mạng tới máy chủ exporter.
{% endhint %}

## Các tùy chọn triển khai

vergeos-exporter hỗ trợ nhiều mô hình triển khai. Hãy chọn mô hình phù hợp nhất với hạ tầng giám sát của bạn.

### Tùy chọn 1: Nhị phân độc lập

Các tệp nhị phân dựng sẵn có sẵn cho Linux, Windows và macOS (amd64 và arm64) từ trang [GitHub Releases](https://github.com/verge-io/vergeos-exporter/releases) trang.

```bash
# Tải xuống và giải nén (ví dụ Linux amd64)
wget https://github.com/verge-io/vergeos-exporter/releases/latest/download/vergeos-exporter-linux-amd64.tar.gz
tar xzf vergeos-exporter-linux-amd64.tar.gz

# Chạy với các cờ bắt buộc
./vergeos-exporter \\
  -verge.url https://your-vergeos-host \\
  -verge.username prometheus-exporter \\
  -verge.password 'YourStrongPassword'
```

Exporter lắng nghe trên cổng **9888** theo mặc định. Ghi đè bằng cờ `-web.listen-address` nếu cần.

### Tùy chọn 2: Dịch vụ systemd trên Linux

Đối với triển khai Linux trong môi trường production, hãy chạy exporter như một dịch vụ systemd được quản lý:

```ini
# /etc/systemd/system/vergeos-exporter.service
[Unit]
Description=Trình xuất Prometheus cho VergeOS
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=vergeos_exporter
ExecStart=/usr/local/bin/vergeos-exporter \\
  -verge.url https://your-vergeos-host \\
  -verge.username prometheus-exporter \\
  -verge.password 'YourStrongPassword'
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
# Tạo người dùng dịch vụ, bật và khởi động
sudo useradd -r -s /usr/sbin/nologin vergeos_exporter
sudo systemctl daemon-reload
sudo systemctl enable --now vergeos-exporter
```

### Tùy chọn 3: Dịch vụ Windows (NSSM)

Trên các máy chủ giám sát Windows, hãy dùng [NSSM (Non-Sucking Service Manager)](https://nssm.cc/) để chạy exporter như một dịch vụ Windows:

1. Tải NSSM và đặt `nssm.exe` ở một vị trí cố định (ví dụ, `C:\Program Files\nssm\`)
2. Đăng ký dịch vụ:

```powershell
nssm install vergeos-exporter "C:\monitoring\vergeos-exporter.exe"
nssm set vergeos-exporter AppParameters "-verge.url https://your-vergeos-host -verge.username prometheus-exporter -verge.password YourStrongPassword"
nssm set vergeos-exporter Start SERVICE_AUTO_START
nssm start vergeos-exporter
```

### Tùy chọn 4: Docker Compose

Kho lưu trữ bao gồm một ví dụ Docker Compose sẵn có tại `examples/docker-compose/` gói exporter, Prometheus và Grafana vào một stack duy nhất -- lý tưởng cho việc đánh giá nhanh hoặc môi trường lab.

```yaml
# Cấu trúc docker-compose.yml được đơn giản hóa
services:
  vergeos-exporter:
    image: vergeos-exporter:latest
    ports:
      - "9888:9888"
    environment:
      - VERGE_URL=https://your-vergeos-host
      - VERGE_USERNAME=prometheus-exporter
      - VERGE_PASSWORD=YourStrongPassword

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
```

Ví dụ Docker Compose tự động lấy tệp nhị phân đúng theo nền tảng cho kiến trúc của bạn.

## Cấu hình Prometheus

Thêm exporter làm mục tiêu quét trong tệp `prometheus.yml`:

```yaml
scrape_configs:
  - job_name: "vergeos"
    scrape_interval: 30s
    scrape_timeout: 30s
    static_configs:
      - targets: ["exporter-host:9888"]
        labels:
          environment: "production"
          cluster: "site-a"
```

Để giám sát nhiều môi trường VergeOS, hãy triển khai một exporter cho mỗi môi trường và thêm từng môi trường như một mục tiêu riêng (hoặc dùng relabeling của Prometheus để khám phá động).

## Bảng điều khiển Grafana

vergeos-exporter đi kèm một dashboard Grafana được cấu hình sẵn (`examples/grafana-dashboard.json`) bao phủ ngay lập tức các chỉ số vSAN, cụm và nút.

### Các bảng điều khiển của dashboard bao gồm

| Danh mục               | Các bảng                                                                         |
| ---------------------- | -------------------------------------------------------------------------------- |
| **Hiệu suất vSAN**     | Đồng hồ đo dung lượng và mức sử dụng theo lớp, biểu đồ IOPS, thông lượng đọc/ghi |
| **Tình trạng cụm**     | Số nút, trạng thái đồng bộ, mức sử dụng CPU và RAM tổng hợp                      |
| **Chi tiết nút**       | CPU, bộ nhớ, thông lượng mạng và nhiệt độ theo từng nút                          |
| **Tình trạng lưu trữ** | Trạng thái ổ đĩa, trạng thái sửa chữa, bộ đếm lỗi                                |

### Nhập dashboard

1. Mở Grafana và điều hướng tới **Bảng điều khiển → Nhập**
2. Nhấp **Tải lên tệp JSON** và chọn `grafana-dashboard.json` từ kho lưu trữ exporter
3. Chọn **nguồn dữ liệu Prometheus** từ menu thả xuống
4. Nhấp **Nhập**

Dashboard sẽ hoạt động ngay khi Prometheus nhận được số liệu từ exporter.

## Xác minh

Sau khi triển khai, xác minh rằng exporter đang thu thập chỉ số:

```bash
# Kiểm tra trực tiếp điểm cuối chỉ số
curl -s http://localhost:9888/metrics | head -20

# Kết quả mong đợi bao gồm các dòng như:
# HELP vergeos_vsan_tier_capacity_bytes Tổng dung lượng cho mỗi lớp vSAN
# TYPE vergeos_vsan_tier_capacity_bytes gauge
# vergeos_vsan_tier_capacity_bytes{tier="1"} 1.234567e+12
```

Nếu điểm cuối trả về các chỉ số, Prometheus sẽ tự động quét chúng ở lần chu kỳ tiếp theo. Kiểm tra trang **Mục tiêu**  của Prometheus (`http://prometheus:9090/targets`) để xác nhận `vergeos` job hiển thị trạng thái **UP**.

### Danh sách kiểm tra khắc phục sự cố

| Triệu chứng              | Chọn                                                                             |
| ------------------------ | -------------------------------------------------------------------------------- |
| Không trả về chỉ số      | Xác minh URL, tên người dùng và mật khẩu VergeOS là chính xác                    |
| Kết nối bị từ chối       | Xác nhận tiến trình exporter đang chạy và lắng nghe trên cổng 9888               |
| Lỗi xác thực             | Xác nhận tài khoản dịch vụ là **Type = API** với **Xác thực hai yếu tố** bỏ chọn |
| Chỉ số một phần          | Xác minh tài khoản dịch vụ có **list và read** quyền                             |
| Mục tiêu Prometheus DOWN | Kiểm tra kết nối mạng giữa Prometheus và máy chủ exporter                        |
| Thời gian chờ quét       | Tăng `-scrape.timeout` (mặc định 30 giây) cho các môi trường lớn                 |

## Tích hợp với AlertManager

Vì exporter hiển thị các chỉ số tiêu chuẩn của Prometheus, bạn có thể viết các quy tắc cảnh báo sẽ kích hoạt khi vượt ngưỡng:

```yaml
# Ví dụ quy tắc cảnh báo cho chỉ số vergeos
groups:
  - name: vergeos_alerts
    rules:
      - alert: VSANTierNearCapacity
        expr: vergeos_vsan_tier_usage_bytes / vergeos_vsan_tier_capacity_bytes > 0.85
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Lớp vSAN {{ $labels.tier }} đang vượt quá 85% dung lượng"

      - alert: DriveOffline
        expr: vergeos_vsan_drive_state{state="offline"} > 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Ổ đĩa {{ $labels.drive }} đang ngoại tuyến trên nút {{ $labels.node }}"
```

AlertManager có thể định tuyến các cảnh báo này tới email, Slack, PagerDuty, OpsGenie, hoặc bất kỳ điểm cuối webhook nào -- tích hợp giám sát VergeOS vào quy trình quản lý sự cố hiện có của bạn.

## Phương án thay thế: Tích hợp trực tiếp API với Zabbix

Nếu tổ chức của bạn dùng Zabbix thay vì Prometheus, bạn có thể truy vấn trực tiếp VergeOS REST API bằng các mục Zabbix HTTP Agent:

1. Tạo mã token API qua **Hệ thống → Tài liệu API** (Swagger UI)
2. Dùng các mục Zabbix HTTP Agent để thăm dò các điểm cuối như `/api/v4/vms`, `/api/v4/nodes`, `/api/v4/vnets`
3. Xác thực bằng cách POST tới `/api/sys/tokens` và truyền session token trong header `x-yottabyte-token` header

Exporter Prometheus vẫn là phương án được khuyến nghị cho hầu hết môi trường nhờ bộ chỉ số phong phú hơn và dashboard dựng sẵn.

{% hint style="info" %}
**Bạn đang chuyển từ VMware hay Nutanix?**

VergeOS hiển thị các chỉ số nền tảng thông qua **vergeos-exporter**, nơi trình bày dữ liệu vSAN, cụm và nút ở định dạng Prometheus tiêu chuẩn. Prometheus pull-scrape exporter trên cổng **9888** và Grafana hiển thị dashboard đi kèm -- vì vậy các chỉ số VergeOS chảy vào cùng ngăn xếp Prometheus + Grafana mà nhiều nhóm đã chạy song song với các nền tảng hiện có của họ.
{% endhint %}

## Điểm chính

* Tính năng **vergeos-exporter** hiển thị các chỉ số vSAN, cụm và nút trên cổng **9888** ở định dạng Prometheus tiêu chuẩn
* Tạo một **tài khoản dịch vụ chuyên dụng kiểu API** -- list/read trên mọi thứ là mặc định đối với người dùng Normal/API mới
* Triển khai dưới dạng nhị phân độc lập, dịch vụ systemd, dịch vụ Windows (NSSM), hoặc stack Docker Compose
* Dashboard Grafana đi kèm **Grafana** cung cấp khả năng hiển thị ngay lập tức về tình trạng lưu trữ, cụm và nút
* Prometheus **AlertManager** tích hợp cho phép cảnh báo chủ động về dung lượng, tình trạng ổ đĩa, và ngưỡng hiệu năng
* Exporter sử dụng **quét dựa trên pull** -- không cần thay đổi tường lửa inbound trên hệ thống VergeOS


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/vi/module-9-giam-sat-and-khac-phuc-su-co/04-prometheus-grafana.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.