From 289372a9fe36f1e23932da12c3ec47141eb0254e Mon Sep 17 00:00:00 2001 From: Hana <115437281+Hana-Hasa@users.noreply.github.com> Date: Wed, 5 Aug 2026 16:57:53 +0700 Subject: [PATCH 1/2] =?UTF-8?q?[docs]=20AgentBase=20MCP=20=E2=80=94=20poin?= =?UTF-8?q?t=20repo=20link=20at=20GreenNodeHub=20org=20=E2=80=94=20VI=20+?= =?UTF-8?q?=20EN?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 (1M context) --- .../agent-base/manage-agentbase-with-the-greennode-mcp.md | 4 ++-- .../agent-base/su-dung-greennode-mcp-de-quan-ly-agentbase.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/English/ai-stack/agent-base/manage-agentbase-with-the-greennode-mcp.md b/English/ai-stack/agent-base/manage-agentbase-with-the-greennode-mcp.md index 9202ef77..b38041a8 100644 --- a/English/ai-stack/agent-base/manage-agentbase-with-the-greennode-mcp.md +++ b/English/ai-stack/agent-base/manage-agentbase-with-the-greennode-mcp.md @@ -4,7 +4,7 @@ **AgentBase MCP** lets AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP-compatible client) operate **GreenNode AgentBase** directly through natural language — list Runtimes, create an MCP Gateway, look up a Policy, inspect Memory — without memorizing command syntax or clicking through the Portal. -AgentBase MCP is a server built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard. Repo: [https://github.com/vngcloud/greennode-agentbase-mcp](https://github.com/vngcloud/greennode-agentbase-mcp) +AgentBase MCP is a server built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard. Repo: [https://github.com/GreenNodeHub/greennode-agentbase-mcp](https://github.com/GreenNodeHub/greennode-agentbase-mcp) What sets it apart from a conventional MCP server: instead of exposing hundreds of tools — one per API — AgentBase MCP exposes only **3 meta-tools**: `list_servers`, `search_tools`, `execute`. The AI assistant discovers the operation it needs and then runs it, so your client's context stays small no matter how many APIs AgentBase has. @@ -55,7 +55,7 @@ Choose **local stdio** when you control the machine and want to experiment quick ### 3. Install the server for the local stdio path ```bash -git clone https://github.com/vngcloud/greennode-agentbase-mcp.git +git clone https://github.com/GreenNodeHub/greennode-agentbase-mcp.git cd greennode-agentbase-mcp npm install diff --git a/Vietnamese/ai-stack/agent-base/su-dung-greennode-mcp-de-quan-ly-agentbase.md b/Vietnamese/ai-stack/agent-base/su-dung-greennode-mcp-de-quan-ly-agentbase.md index 36ab6fe2..92708c05 100644 --- a/Vietnamese/ai-stack/agent-base/su-dung-greennode-mcp-de-quan-ly-agentbase.md +++ b/Vietnamese/ai-stack/agent-base/su-dung-greennode-mcp-de-quan-ly-agentbase.md @@ -4,7 +4,7 @@ **AgentBase MCP** giúp AI assistant (Claude Desktop, Claude Code, Cursor, Windsurf, hoặc bất kỳ MCP client nào) thao tác trực tiếp với **GreenNode AgentBase** bằng ngôn ngữ tự nhiên — liệt kê Runtime, tạo MCP Gateway, tra Policy, xem Memory — mà không cần nhớ cú pháp lệnh hay click qua Portal. -AgentBase MCP là máy chủ triển khai theo chuẩn [Model Context Protocol](https://modelcontextprotocol.io/). Repo: [https://github.com/vngcloud/greennode-agentbase-mcp](https://github.com/vngcloud/greennode-agentbase-mcp) +AgentBase MCP là máy chủ triển khai theo chuẩn [Model Context Protocol](https://modelcontextprotocol.io/). Repo: [https://github.com/GreenNodeHub/greennode-agentbase-mcp](https://github.com/GreenNodeHub/greennode-agentbase-mcp) Điểm khác biệt so với một MCP server thông thường: thay vì expose hàng trăm tool tương ứng từng API, AgentBase MCP chỉ expose **3 meta-tool** — `list_servers`, `search_tools`, `execute`. AI assistant tự tìm operation cần dùng rồi gọi, nên context của client luôn gọn dù AgentBase có bao nhiêu API. @@ -55,7 +55,7 @@ Chọn **local stdio** khi bạn kiểm soát được máy chạy và muốn th ### 3. Cài đặt server cho cách local stdio ```bash -git clone https://github.com/vngcloud/greennode-agentbase-mcp.git +git clone https://github.com/GreenNodeHub/greennode-agentbase-mcp.git cd greennode-agentbase-mcp npm install From 4eaab17c28586f5f6f0e726c70046d6e6cdfaaf1 Mon Sep 17 00:00:00 2001 From: congtt2 Date: Mon, 10 Aug 2026 13:11:10 +0700 Subject: [PATCH 2/2] =?UTF-8?q?[docs]=20vMonitor=20=E2=80=94=20vMonitor=20?= =?UTF-8?q?Datasource=20Plugin=20for=20Grafana=20=E2=80=94=20VI=20+=20EN?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit How-to guide (VI + EN) for installing and using the vMonitor Datasource plugin for Grafana (v1.0.0): IAM Service Account key, unsigned-plugin allowlist, data source setup, metric/log queries, Grafana alerting & notifications, troubleshooting. Plus Aug 2026 release-note entries in both global 2026.md files and SUMMARY.md nav entries. Co-Authored-By: Claude --- English/SUMMARY.md | 1 + English/overview/product-updates-all/2026.md | 10 + .../install-vmonitor-grafana-plugin.md | 254 ++++++++++++++++++ Vietnamese/SUMMARY.md | 1 + .../thong-bao-va-cap-nhat/2026.md | 10 + .../cai-dat-vmonitor-grafana-plugin.md | 254 ++++++++++++++++++ 6 files changed, 530 insertions(+) create mode 100644 English/vmonitor/install-vmonitor-grafana-plugin.md create mode 100644 Vietnamese/vmonitor/cai-dat-vmonitor-grafana-plugin.md diff --git a/English/SUMMARY.md b/English/SUMMARY.md index 2be181f3..e1f56978 100644 --- a/English/SUMMARY.md +++ b/English/SUMMARY.md @@ -538,6 +538,7 @@ * [Getting Start with Metrics](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-metrics.md) * [Getting Start with Logs](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-logs.md) * [Getting Start with Synthetic](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-synthetic.md) + * [Install and use the vMonitor Datasource plugin for Grafana](vmonitor/install-vmonitor-grafana-plugin.md) * [Features of vMonitor Platform](vmonitor/dashboards.md) * [Dashboard](vmonitor-platform/cach-tinh-nang-cua-vmonitor-platform/dashboard/README.md) * [Widget](vmonitor-platform/cach-tinh-nang-cua-vmonitor-platform/dashboard/widget/README.md) diff --git a/English/overview/product-updates-all/2026.md b/English/overview/product-updates-all/2026.md index 8a59e93a..f10fac0d 100644 --- a/English/overview/product-updates-all/2026.md +++ b/English/overview/product-updates-all/2026.md @@ -165,6 +165,16 @@ For more details about the updated renewal mechanism and policy, please refer [h **Aug 2026** +**vMonitor — vMonitor Datasource Plugin for Grafana** + +The vMonitor Datasource Plugin connects Grafana to the vMonitor Platform so you can query metrics and logs, build dashboards, and drive Grafana alerting directly from vMonitor data. + +* Queries metrics and logs from vMonitor, with metric statistics, dimension filters, group by, and functions including Rank, Rollup, Rate, Timeshift, and Reduce. +* Supports **Expression mode** for arithmetic across queries (e.g. `A / B * 100`) and **Grafana alerting and notifications** on vMonitor metrics and logs. +* Ships **bundled dashboards** for Host, vServer, vLB, vDB, vStorage, and vBackup, plus template variables for metrics, dimensions, and infrastructure resources. +* Requires Grafana **12.3.0+** and a GreenNode IAM Service Account key pair; unsigned builds must be allowlisted — download from [GitHub releases](https://github.com/GreenNodeHub/vmonitor-grafana-plugin/releases). +* Learn more at [Install and use the vMonitor Datasource plugin for Grafana](../../vmonitor/install-vmonitor-grafana-plugin.md). + **GreenNode AgentBase — CLI & MCP** AgentBase adds two ways to work alongside the Portal — the command line and AI assistants: diff --git a/English/vmonitor/install-vmonitor-grafana-plugin.md b/English/vmonitor/install-vmonitor-grafana-plugin.md new file mode 100644 index 00000000..f3e8dc79 --- /dev/null +++ b/English/vmonitor/install-vmonitor-grafana-plugin.md @@ -0,0 +1,254 @@ +# Install and use the vMonitor Datasource plugin for Grafana + +> This guide helps you install the vMonitor Datasource Plugin on a self-hosted Grafana server, add a data source connecting to vMonitor, then query metrics/logs, build dashboards, and set up alerting. + +--- + +## Prerequisites + +- Grafana server version **12.3.0** or later. +- `sudo` access on the Grafana host. +- A GreenNode IAM **Service Account** key pair (`Client ID` + `Client Secret`) with vMonitor read access (created in the first step below). + +--- + +## Create a Service Account key pair + +The plugin authenticates with vMonitor using a Service Account key pair, not a username/password. + +**Step 1: Create the Service Account** + +1. Open the GreenNode IAM console. +2. Go to **Service Accounts** → **Create service account**. +3. Name and create the Service Account. + +**Step 2: Attach policies** + +1. Attach the **vMonitorMetricReadOnlyAccess** policy to the Service Account (required to query metrics). +2. If you need to query logs, also attach **vMonitorLogReadOnlyAccess**. + +**Step 3: Generate the key pair** + +1. In the Service Account you just created, choose to generate a key pair. +2. Note the **Access Key ID** — this is your `Client ID`. +3. Note the **Secret Access Key** — this is your `Client Secret`. + +{% hint style="warning" %} +The Secret Access Key is shown only **once**. If you lose it, you must create a new key pair. +{% endhint %} + +--- + +## Install the plugin on the Grafana server + +The plugin is an unsigned backend build, so Grafana must be allowed to load unsigned plugins. + +**Step 1: Download the plugin** + +1. Download the latest ZIP (v1.0.0) from the **[Releases](https://github.com/GreenNodeHub/vmonitor-grafana-plugin/releases)** page of the `GreenNodeHub/vmonitor-grafana-plugin` repo. + +**Step 2: Unpack** + +1. Create the plugin directory if it does not exist (default `/var/lib/grafana/plugins`). +2. Unzip the archive into a subdirectory named `greennode-vmonitor-datasource`. + +{% hint style="info" %} +Find your plugins path by checking the `plugins` key under `[paths]` in `/etc/grafana/grafana.ini`. When upgrading, remove the old plugin directory before unpacking the new build. +{% endhint %} + +**Step 3: Set ownership** + +1. Grafana runs as the `grafana` user. Grant ownership of the entire plugins directory: + +```bash +sudo chown -R grafana:grafana /var/lib/grafana/plugins +``` + +**Step 4: Allow the unsigned plugin** + +1. Open `/etc/grafana/grafana.ini`. +2. Add the plugin ID to the `[plugins]` section: + +```ini +[plugins] +allow_loading_unsigned_plugins = greennode-vmonitor-datasource +``` + +The plugin ID is in `plugin.json` inside the plugin directory. Multiple unsigned plugins are comma-separated. + +**Step 5: Restart and verify** + +1. Restart the Grafana server. +2. Check the logs: success shows a "Plugin registered" message. Two warnings about the unsigned plugin are expected. +3. Go to **Administration → Plugins and data → Plugins**; the **GreenNode vMonitor** plugin appears in the list. + +{% hint style="warning" %} +Restarting Grafana interrupts the current session. Perform this outside peak hours if needed. +{% endhint %} + +--- + +## Add the data source and import dashboards + +**Step 1: Add the data source** + +1. Go to **Administration → Plugins and data → Plugins**. +2. Search for "GreenNode vMonitor" and add a new data source. + +**Step 2: Fill in the fields** + +| Field | Required | Description | +|---|---|---| +| API URL | No | vMonitor API base URL; leave blank for the default | +| Client ID | Yes | Access Key ID of the Service Account key | +| Client Secret | Yes | Secret Access Key; stored encrypted, read only by the backend | +| Token URL | No | IAM token-exchange endpoint; leave blank for the default | + +**Step 3: Save and test** + +1. Click **Save & test**. +2. The backend exchanges the key pair for a **Bearer token**, which is cached until expiry. + +{% hint style="info" %} +The Client Secret never reaches the browser; only the backend holds it and uses it to exchange tokens. +{% endhint %} + +**Step 4: Import dashboards** + +1. Go to **Connections → Data sources** and open the data source you just created. +2. Switch to the **Dashboards** tab and import each desired dashboard. + +--- + +## Query metrics + +**Step 1: Select the mode** + +1. Select the GreenNode vMonitor data source. +2. Select **Metric** mode. + +**Step 2: Configure the query** + +| Field | Description | +|---|---| +| Metric | The metric name, e.g. `net.if.in.bytes_sec` | +| Statistic | Aggregation function: `avg`, `min`, `max`, `sum`, `count`, `rate_1s`, `rate_1m`, `rate_5m` | +| Filter by | Dimension filters combined with AND | +| Group by | Split into separate series by dimension value | +| Alias | Display name template using `{{dimension}}` syntax | + +**Step 3: Add functions (if needed)** + +Click **Add Function** to add: + +| Function | Description | Limitation | +|---|---|---| +| Rollup | Aggregate over a fixed time window (avg/min/max/sum/count) | Not for `rate_*` | +| Rate | Convert a cumulative counter to a rate (per_second/per_minute/per_hour) | Not for `rate_*` | +| Timeshift | Overlay the same metric from an earlier period | Not for `rate_*` | +| Rank | Keep top N (topk) or bottom N (bottomk) series at each point | Excluded series have gaps | +| Reduce | Collapse a series to a single value (last/avg/min/max/sum) for Stat/Top List panels | — | + +{% hint style="info" %} +The `rate_1s`, `rate_1m`, `rate_5m` statistics do not support the Rollup, Rate, or Timeshift functions. In an alert rule that uses Rank, add **Resample** before **Reduce** to handle gaps. +{% endhint %} + +**Step 4: Examples** + +- **Top 5 vServers by CPU:** Metric `cpu.usage_user`, statistic `avg`, filter `product = vserver`, group by `resource_id`, Rank topk 5, alias `{{resource_id}}`. +- **Network throughput vs. last week:** Query A with the metric and `avg` statistic; Query B with the same metric plus Timeshift 1 week. + +--- + +## Query logs + +**Step 1: Select the Log project** + +1. Select the data source and switch to **Logs** mode. +2. Choose a **Log project** (only ACTIVE projects are listed). + +**Step 2: Choose the output format** + +| Format | Used for | Display | +|---|---|---| +| logs | Explore, Logs panel | Log lines with a count histogram, each line expandable | +| table | Table panel | One row per entry, one column per field | +| timeseries | Graph panel, Alerting | Log count over time | + +In Alert mode, the format is automatically set to `timeseries`. + +**Step 3: Filter logs** + +| Operator | Input | Meaning | +|---|---|---| +| is | 1 value | Exact match | +| is not | 1 value | Does not match | +| is one of | Multiple | Matches any | +| is not one of | Multiple | Matches none | +| is between | from, to | In range [from, to) | +| is not between | from, to | Outside range | +| exists | — | Field present | +| does not exist | — | Field absent | + +Grafana variables are supported in filter values, e.g. `$selected_host`. + +**Step 4: Group by (timeseries only)** + +1. Select an aggregatable (keyword) field to split the log count into separate series. +2. Each unique combination of values becomes a series; maximum 20 values per field. + +--- + +## Set up alerting and notifications + +Alerting and notifications are handled by **Grafana**: you build a Grafana alert rule on vMonitor metric/log queries, then Grafana delivers alerts through its own notification policies and contact points (email, Slack, Webhook...). The plugin does not use vMonitor Alarm or Notification. + +**Alert on metrics:** Build a metric query, then add **Reduce** + **Threshold** in the alert rule. If you use Rank, add **Resample** before **Reduce** to handle gaps. + +**Alert on log count:** Use a log query with the `timeseries` format, add filters, then attach **Reduce** + **Threshold** to fire when the log count exceeds the threshold. + +{% hint style="info" %} +During quiet periods, the log count reports `0` instead of missing data, so the rule can also fire when logs stop appearing. +{% endhint %} + +**Log group by in alerts:** Each group value creates a separate Grafana alert instance. A group with no matching logs during evaluation does not produce an instance. + +--- + +## Template variables + +| Function | Returns | +|---|---| +| `metrics()` | All metric names | +| `dimensions(metricName)` | Dimension keys for a metric | +| `dimensionValues(metricName, key)` | Values for a dimension key | +| `infrastructure(product[, region])` | Resources for a product type | +| `regions(product)` | Available regions for region-aware products | + +Products supported by `infrastructure()`: `host`, `vserver`, `vlb`, `vstorage`, `vstorage-bucket`, `vdb`, `vdb-kafka`, `vdb-cluster`, `vbackup`. + +--- + +## Troubleshooting + +| Symptom | Cause & fix | +|---|---| +| Plugin missing from the Plugins list | Unsigned build not allowed; check the unsigned-plugin step and inspect the logs for signature errors | +| Plugin directory skipped | Ownership issue; rerun `chown` from the ownership step | +| Plugin unavailable when querying | Backend binary failed to start; ensure `plugin.json` is directly in the plugin directory, not nested | +| Version error | Plugin requires Grafana **12.3.0+** | +| 401 Unauthorized on **Save & test** | Wrong Client ID or Client Secret | +| Connection refused on **Save & test** | Wrong API URL or network issue | +| Query returns no data | Check the time range, dimension filters, and IAM read permissions | +| Log project dropdown empty | IAM key lacks log read permission, or the project is not in ACTIVE billing status | + +--- + +## Result + +Once complete, you have a GreenNode vMonitor data source in Grafana that can query metrics and logs, use the bundled dashboards, and drive alerting from vMonitor data. + +| I want to... | Go to | +|---|---| +| See vMonitor updates | [Announcements and Updates](../overview/product-updates-all/) | +| Learn about vMonitor Platform | [vMonitor Platform](README.md) | diff --git a/Vietnamese/SUMMARY.md b/Vietnamese/SUMMARY.md index 41b4b9e6..bbbe959c 100644 --- a/Vietnamese/SUMMARY.md +++ b/Vietnamese/SUMMARY.md @@ -619,6 +619,7 @@ * [Bắt đầu với Metrics](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-metrics.md) * [Bắt đầu với Logs](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-logs.md) * [Bắt đầu với Synthetic](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-synthetic.md) + * [Cài đặt và sử dụng vMonitor Datasource Plugin cho Grafana](vmonitor/cai-dat-vmonitor-grafana-plugin.md) * [Các tính năng của vMonitor Platform](vmonitor/dashboards.md) * [Dashboard](vmonitor-platform/cach-tinh-nang-cua-vmonitor-platform/dashboard/README.md) * [Widget](vmonitor-platform/cach-tinh-nang-cua-vmonitor-platform/dashboard/widget/README.md) diff --git a/Vietnamese/gioi-thieu-chung/thong-bao-va-cap-nhat/2026.md b/Vietnamese/gioi-thieu-chung/thong-bao-va-cap-nhat/2026.md index 916dc888..df7c9755 100644 --- a/Vietnamese/gioi-thieu-chung/thong-bao-va-cap-nhat/2026.md +++ b/Vietnamese/gioi-thieu-chung/thong-bao-va-cap-nhat/2026.md @@ -158,6 +158,16 @@ Chính sách gia hạn tài nguyên này áp dụng từ ngày 8/1/2026 và áp **Tháng 8, 2026** +**vMonitor — vMonitor Datasource Plugin cho Grafana** + +vMonitor Datasource Plugin kết nối Grafana với vMonitor Platform, cho phép query metric và log, dựng dashboard và thiết lập alerting trực tiếp từ dữ liệu vMonitor. + +* Query metric và log từ vMonitor, hỗ trợ metric statistic, dimension filter, group by và các function bao gồm Rank, Rollup, Rate, Timeshift, Reduce. +* Hỗ trợ **Expression mode** cho phép tính toán giữa các query (ví dụ `A / B * 100`) và **alerting/notification qua Grafana** trên metric và log của vMonitor. +* Kèm **dashboard dựng sẵn** cho Host, vServer, vLB, vDB, vStorage, vBackup, cùng template variable cho metric, dimension và infrastructure resource. +* Yêu cầu Grafana **12.3.0+** và cặp key Service Account GreenNode IAM; bản chưa ký cần được cho phép tải (allowlist) — tải tại [GitHub releases](https://github.com/GreenNodeHub/vmonitor-grafana-plugin/releases). +* Tìm hiểu thêm tại [Cài đặt và sử dụng vMonitor Datasource Plugin cho Grafana](../../vmonitor/cai-dat-vmonitor-grafana-plugin.md). + **GreenNode AgentBase — CLI & MCP** AgentBase bổ sung 2 cách làm việc bên cạnh Portal — dòng lệnh và AI assistant: diff --git a/Vietnamese/vmonitor/cai-dat-vmonitor-grafana-plugin.md b/Vietnamese/vmonitor/cai-dat-vmonitor-grafana-plugin.md new file mode 100644 index 00000000..7d4f689a --- /dev/null +++ b/Vietnamese/vmonitor/cai-dat-vmonitor-grafana-plugin.md @@ -0,0 +1,254 @@ +# Cài đặt và sử dụng vMonitor Datasource Plugin cho Grafana + +> Hướng dẫn này giúp bạn cài đặt vMonitor Datasource Plugin lên máy chủ Grafana self-hosted, thêm data source kết nối tới vMonitor, rồi query metric/log, dựng dashboard và thiết lập alerting. + +--- + +## Điều kiện cần (Prerequisites) + +- Máy chủ Grafana phiên bản **12.3.0** trở lên. +- Quyền `sudo` trên máy chủ Grafana. +- Một cặp **Service Account** key GreenNode IAM (`Client ID` + `Client Secret`) có quyền đọc vMonitor (tạo ở bước đầu tiên bên dưới). + +--- + +## Tạo Service Account key pair + +Plugin xác thực với vMonitor bằng cặp key của Service Account, không dùng username/password. + +**Bước 1: Tạo Service Account** + +1. Mở GreenNode IAM console. +2. Vào **Service Accounts** → **Create service account**. +3. Đặt tên và tạo Service Account. + +**Bước 2: Gắn policy** + +1. Gắn policy **vMonitorMetricReadOnlyAccess** cho Service Account (bắt buộc để query metric). +2. Nếu cần query log, gắn thêm policy **vMonitorLogReadOnlyAccess**. + +**Bước 3: Tạo cặp key** + +1. Trong Service Account vừa tạo, chọn tạo key pair. +2. Ghi lại **Access Key ID** — đây là `Client ID`. +3. Ghi lại **Secret Access Key** — đây là `Client Secret`. + +{% hint style="warning" %} +Secret Access Key chỉ hiển thị **một lần**. Nếu mất, bạn phải tạo key pair mới. +{% endhint %} + +--- + +## Cài đặt plugin trên máy chủ Grafana + +Plugin là backend plugin chưa ký (unsigned build), nên Grafana cần được cho phép tải unsigned plugin. + +**Bước 1: Tải plugin** + +1. Tải file ZIP mới nhất (v1.0.0) từ trang **[Releases](https://github.com/GreenNodeHub/vmonitor-grafana-plugin/releases)** của repo `GreenNodeHub/vmonitor-grafana-plugin`. + +**Bước 2: Giải nén** + +1. Tạo thư mục plugin nếu chưa có (mặc định `/var/lib/grafana/plugins`). +2. Giải nén archive vào thư mục con tên `greennode-vmonitor-datasource`. + +{% hint style="info" %} +Tìm đường dẫn plugin bằng cách xem khoá `plugins` dưới `[paths]` trong `/etc/grafana/grafana.ini`. Khi nâng cấp, xoá thư mục plugin cũ trước khi giải nén bản mới. +{% endhint %} + +**Bước 3: Phân quyền** + +1. Grafana chạy với user `grafana`. Cấp ownership cho toàn bộ thư mục plugin: + +```bash +sudo chown -R grafana:grafana /var/lib/grafana/plugins +``` + +**Bước 4: Cho phép unsigned plugin** + +1. Mở `/etc/grafana/grafana.ini`. +2. Thêm ID plugin vào section `[plugins]`: + +```ini +[plugins] +allow_loading_unsigned_plugins = greennode-vmonitor-datasource +``` + +ID plugin nằm trong `plugin.json` của thư mục plugin. Nhiều unsigned plugin phân tách bằng dấu phẩy. + +**Bước 5: Khởi động lại và kiểm tra** + +1. Khởi động lại Grafana server. +2. Kiểm tra log: thành công sẽ có dòng "Plugin registered". Hai cảnh báo về unsigned plugin là bình thường. +3. Vào **Administration → Plugins and data → Plugins**, plugin **GreenNode vMonitor** xuất hiện trong danh sách. + +{% hint style="warning" %} +Khởi động lại Grafana sẽ gián đoạn phiên làm việc hiện tại. Thực hiện ngoài giờ cao điểm nếu cần. +{% endhint %} + +--- + +## Thêm data source và import dashboard + +**Bước 1: Thêm data source** + +1. Vào **Administration → Plugins and data → Plugins**. +2. Tìm "GreenNode vMonitor" và thêm data source mới. + +**Bước 2: Điền thông tin** + +| Trường | Bắt buộc | Mô tả | +|---|---|---| +| API URL | Không | vMonitor API base URL; để trống dùng mặc định | +| Client ID | Có | Access Key ID của Service Account key | +| Client Secret | Có | Secret Access Key; lưu mã hoá, chỉ backend đọc | +| Token URL | Không | IAM token-exchange endpoint; để trống dùng mặc định | + +**Bước 3: Lưu và kiểm tra** + +1. Nhấn **Save & test**. +2. Backend đổi cặp key lấy **Bearer token** và cache đến khi hết hạn. + +{% hint style="info" %} +Client Secret không bao giờ gửi lên browser; chỉ backend giữ và dùng để đổi token. +{% endhint %} + +**Bước 4: Import dashboard** + +1. Vào **Connections → Data sources**, mở data source vừa tạo. +2. Chuyển sang tab **Dashboards** và import từng dashboard mong muốn. + +--- + +## Truy vấn Metric + +**Bước 1: Chọn mode** + +1. Chọn data source GreenNode vMonitor. +2. Chọn **Metric** mode. + +**Bước 2: Cấu hình query** + +| Trường | Mô tả | +|---|---| +| Metric | Tên metric, ví dụ `net.if.in.bytes_sec` | +| Statistic | Hàm tổng hợp: `avg`, `min`, `max`, `sum`, `count`, `rate_1s`, `rate_1m`, `rate_5m` | +| Filter by | Dimension filter, kết hợp bằng AND | +| Group by | Tách thành nhiều series theo giá trị dimension | +| Alias | Tên hiển thị, dùng cú pháp `{{dimension}}` | + +**Bước 3: Thêm function (nếu cần)** + +Nhấn **Add Function** để thêm: + +| Function | Mô tả | Giới hạn | +|---|---|---| +| Rollup | Tổng hợp trên cửa sổ thời gian cố định (avg/min/max/sum/count) | Không dùng với `rate_*` | +| Rate | Chuyển counter tích lũy thành rate (per_second/per_minute/per_hour) | Không dùng với `rate_*` | +| Timeshift | Chồng cùng metric từ khoảng thời gian trước đó | Không dùng với `rate_*` | +| Rank | Giữ top N (topk) hoặc bottom N (bottomk) series tại mỗi điểm | Series bị loại có gap | +| Reduce | Rút gọn series về 1 giá trị (last/avg/min/max/sum) cho Stat/Top List panel | — | + +{% hint style="info" %} +Các statistic `rate_1s`, `rate_1m`, `rate_5m` không hỗ trợ function Rollup, Rate, Timeshift. Trong alert rule dùng Rank, hãy thêm **Resample** trước **Reduce** để xử lý gap. +{% endhint %} + +**Bước 4: Ví dụ** + +- **Top 5 vServer theo CPU:** Metric `cpu.usage_user`, statistic `avg`, filter `product = vserver`, group by `resource_id`, Rank topk 5, alias `{{resource_id}}`. +- **Network throughput so với tuần trước:** Query A với metric và statistic `avg`; Query B cùng metric kèm Timeshift 1 tuần. + +--- + +## Truy vấn Log + +**Bước 1: Chọn Log project** + +1. Chọn data source, chuyển sang **Logs** mode. +2. Chọn **Log project** (chỉ liệt kê project ở trạng thái ACTIVE). + +**Bước 2: Chọn định dạng xuất** + +| Định dạng | Dùng cho | Hiển thị | +|---|---|---| +| logs | Explore, Logs panel | Dòng log kèm histogram số lượng, mỗi dòng mở rộng được | +| table | Table panel | 1 dòng mỗi entry, 1 cột mỗi field | +| timeseries | Graph panel, Alerting | Số lượng log theo thời gian | + +Trong Alert mode, định dạng tự đặt thành `timeseries`. + +**Bước 3: Lọc log** + +| Operator | Input | Ý nghĩa | +|---|---|---| +| is | 1 giá trị | Khớp chính xác | +| is not | 1 giá trị | Không khớp | +| is one of | Nhiều giá trị | Khớp bất kỳ | +| is not one of | Nhiều giá trị | Không khớp giá trị nào | +| is between | from, to | Trong khoảng [from, to) | +| is not between | from, to | Ngoài khoảng | +| exists | — | Field có mặt | +| does not exist | — | Field vắng mặt | + +Grafana variable được hỗ trợ trong giá trị filter, ví dụ `$selected_host`. + +**Bước 4: Group by (chỉ timeseries)** + +1. Chọn field keyword aggregatable để tách số lượng log thành nhiều series. +2. Mỗi tổ hợp giá trị duy nhất thành 1 series; tối đa 20 giá trị cho mỗi field. + +--- + +## Thiết lập Alert và Notification + +Alerting và notification do **Grafana** xử lý: bạn dựng Grafana alert rule trên các query metric/log của vMonitor, rồi Grafana gửi cảnh báo qua notification policy và contact point của chính Grafana (email, Slack, Webhook...). Plugin không dùng Alarm hay Notification của vMonitor. + +**Alert trên metric:** Dựng metric query, rồi trong alert rule thêm **Reduce** + **Threshold**. Nếu dùng Rank, thêm **Resample** trước **Reduce** để xử lý gap. + +**Alert trên số lượng log:** Dùng log query định dạng `timeseries`, thêm filter, rồi gắn **Reduce** + **Threshold** để kích hoạt khi số lượng log vượt ngưỡng. + +{% hint style="info" %} +Trong thời gian yên tĩnh, số lượng log báo về `0` thay vì thiếu dữ liệu, nên rule cũng có thể kích hoạt khi log ngừng xuất hiện. +{% endhint %} + +**Group by trong alert log:** Mỗi giá trị group tạo một alert instance Grafana riêng. Group không có log trong kỳ đánh giá sẽ không sinh instance. + +--- + +## Template variables + +| Function | Trả về | +|---|---| +| `metrics()` | Tất cả tên metric | +| `dimensions(metricName)` | Các dimension key của metric | +| `dimensionValues(metricName, key)` | Giá trị của dimension key | +| `infrastructure(product[, region])` | Resource của một loại product | +| `regions(product)` | Các region khả dụng cho product nhận region | + +Product hỗ trợ bởi `infrastructure()`: `host`, `vserver`, `vlb`, `vstorage`, `vstorage-bucket`, `vdb`, `vdb-kafka`, `vdb-cluster`, `vbackup`. + +--- + +## Khắc phục sự cố + +| Triệu chứng | Nguyên nhân & khắc phục | +|---|---| +| Plugin không có trong danh sách Plugins | Build chưa ký; kiểm tra bước cho phép unsigned, xem log lỗi chữ ký | +| Thư mục plugin bị bỏ qua | Lỗi ownership; chạy lại `chown` ở bước phân quyền | +| Plugin unavailable khi query | Backend binary không khởi động; đảm bảo `plugin.json` nằm trực tiếp trong thư mục plugin, không lồng | +| Lỗi version | Plugin yêu cầu Grafana **12.3.0+** | +| 401 Unauthorized khi **Save & test** | Sai Client ID hoặc Client Secret | +| Connection refused khi **Save & test** | Sai API URL hoặc vấn đề mạng | +| Query không trả data | Kiểm tra time range, dimension filter và quyền đọc IAM | +| Dropdown Log project rỗng | IAM key thiếu quyền đọc log, hoặc project không ở trạng thái ACTIVE | + +--- + +## Kết quả + +Sau khi hoàn tất, bạn có một data source GreenNode vMonitor trong Grafana, có thể query metric/log, dùng các dashboard dựng sẵn và thiết lập alerting từ dữ liệu vMonitor. + +| Tôi muốn tiếp theo... | Đi đến | +|---|---| +| Xem các bản cập nhật vMonitor | [Announcements and Updates](../overview/product-updates-all/) | +| Tìm hiểu về vMonitor Platform | [vMonitor Platform](README.md) |