You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dubbo.apache.org by al...@apache.org on 2026/05/18 03:00:11 UTC
(dubbo-website) branch master updated: fix(golang): update metrics doc to latest version (#3192)

This is an automated email from the ASF dual-hosted git repository.

AlexStocks pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git


The following commit(s) were added to refs/heads/master by this push:
     new 4a6cec9a8f1 fix(golang): update metrics doc to latest version (#3192)
4a6cec9a8f1 is described below

commit 4a6cec9a8f1e39974b2e5c6bf19bec6656ee3b7e
Author: Xuetao Li <m1...@163.com>
AuthorDate: Mon May 18 11:00:05 2026 +0800

    fix(golang): update metrics doc to latest version (#3192)
    
    * fix(golang): update metrics doc to latest version
    
    * update
---
 .../tutorial/observability/rpc_metrics.md          | 344 ++++++++++++++++----
 .../tutorial/observability/rpc_metrics.md          | 352 +++++++++++++++++----
 2 files changed, 559 insertions(+), 137 deletions(-)

diff --git a/content/en/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md b/content/en/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md
index 98a5851ff52..b2261b58c1f 100644
--- a/content/en/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md
+++ b/content/en/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md
@@ -2,106 +2,271 @@
 aliases:
     - /en/docs3-v2/golang-sdk/tutorial/governance/monitor/rpc_metrics/
     - /en/docs3-v2/golang-sdk/tutorial/governance/monitor/rpc_metrics/
-description: "Collect runtime Metrics indicators and integrate with Prometheus and Grafana systems"
+description: "Dubbo-Go Metrics Monitoring: Prometheus Pull mode and Pushgateway Push mode with Grafana visualization"
 title: Metrics Monitoring
 type: docs
 weight: 2
 ---
 
-Dubbo supports the collection of runtime Metrics indicators and their integration with Prometheus and Grafana systems to achieve visual monitoring of microservice clusters. Below is a specific usage example. You can view the [complete source code of the example](https://github.com/apache/dubbo-go-samples/tree/main/metrics).
+# Dubbo-Go Metrics Monitoring
 
-## Contents
+Dubbo-Go supports runtime metrics collection and integration with **Prometheus + Grafana** to build observability for microservices.
 
-- server/main.go - is the main definition of the service, handler and rpc server
-- client/main.go - is the rpc client
-- proto - contains the protobuf definition of the API
+This example covers two monitoring modes:
 
-## How to run
+* **Pull Mode**: Prometheus scrapes metrics from Dubbo-Go applications. Recommended for long-running services.
+* **Push Mode**: Dubbo-Go applications push metrics to Pushgateway. Recommended only for short-lived jobs.
 
-### Run server
-```shell
-go run ./go-server/cmd/main.go
+Example source code:
+
+> [https://github.com/apache/dubbo-go-samples/tree/main/metrics](https://github.com/apache/dubbo-go-samples/tree/main/metrics)
+
+## 1. Monitoring Architecture
+
+### 1.1 Pull Mode (Recommended for production)
+
+```
+Dubbo-Go Application  --->  Prometheus  --->  Grafana
+        (exposes /metrics or /prometheus endpoint)
+```
+
+Prometheus actively scrapes metrics from Dubbo-Go applications.
+
+### 1.2 Push Mode (For short-lived jobs)
+
+```
+Dubbo-Go Application  --->  Pushgateway  --->  Prometheus  --->  Grafana
+```
+
+Applications push metrics to Pushgateway. Prometheus scrapes Pushgateway.
+
+Pushgateway is designed for **short-lived jobs (batch / cron)** and is not recommended for long-running services.
+
+## 2. Components Overview
+
+| Component   | Port | Description                      |
+| ----------- | ---- | -------------------------------- |
+| Grafana     | 3000 | Metrics visualization dashboard  |
+| Prometheus  | 9090 | Metrics storage and query engine |
+| Pushgateway | 9091 | Receives pushed metrics          |
+| go-server metrics endpoint | 9099 in this sample | Provider metrics in Pull mode |
+| go-client metrics endpoint | 9097 in this sample | Consumer metrics in Pull mode |
+
+If you use Dubbo-Go defaults instead of this sample, the default metrics endpoint is `http://localhost:9090/metrics`. This sample overrides the metrics path to `/prometheus`.
+
+## 3. Quick Start
+
+### 3.1 Start the Monitoring Stack
+
+Navigate to:
+
+```bash
+cd metrics/prometheus_grafana
+```
+
+Start services:
+
+```bash
+docker-compose up -d
+```
+
+Access:
+
+* Grafana: [http://localhost:3000](http://localhost:3000)
+* Prometheus: [http://localhost:9090](http://localhost:9090)
+* Pushgateway: [http://localhost:9091](http://localhost:9091)
+
+### 3.2 Configure Environment Variables
+
+Both client and server share the same configuration:
+
+```bash
+export ZK_ADDRESS="127.0.0.1:2181"
+
+# Required for Push mode
+export PUSHGATEWAY_URL="127.0.0.1:9091"
+export JOB_NAME="dubbo-service"
+
+# Optional
+export PUSHGATEWAY_USER="username"
+export PUSHGATEWAY_PASS="1234"
 ```
 
-test server work as expected:
-```shell
-curl \
-    --header "Content-Type: application/json" \
-    --data '{"name": "Dubbo"}' \
-    http://localhost:20000/greet.GreetService/Greet
+### 3.3 Start Dubbo-Go Server
+
+```bash
+go run ./go-server/cmd/main.go
 ```
 
-### Run client
-```shell
+### 3.4 Start Dubbo-Go Client
+
+#### Default (Push Mode)
+
+```bash
 go run ./go-client/cmd/main.go
 ```
 
-## deploy to local
-install prometheus and open prometheus config file `prometheus.yml`, write the config like this
+#### Pull Mode
 
-```yaml
-global:
-  evaluation_interval: 15s
-  scrape_interval: 15s
-scrape_configs:
-- job_name: dubbo-provider
-  scrape_interval: 15s
-  scrape_timeout: 5s
-  metrics_path: /prometheus
-  static_configs:
-    - targets: ['localhost:9099']
-- job_name: dubbo-consumer
-  scrape_interval: 15s
-  scrape_timeout: 5s
-  metrics_path: /prometheus
-  static_configs:
-    - targets: ['localhost:9097']
+```bash
+go run ./go-client/cmd/main.go --push=false
+go run ./go-server/cmd/main.go --push=false
 ```
 
-install grafana and open grafana web page like `localhost:3000`
+### 3.5 Verify Metrics
+
+#### Push Mode
+
+Open:
+
+```
+http://localhost:9091/metrics
+```
+
+#### Pull Mode
+
+`<app_port>` means the HTTP metrics port exposed by the Dubbo-Go application itself, not the Prometheus or Pushgateway port.
 
-open: 【Home / Connections / Data sources】
+In this sample:
 
-click 【Add new data source】
+* Provider: `http://localhost:9099/prometheus`
+* Consumer: `http://localhost:9097/prometheus`
 
-select Prometheus
+These ports are defined in [`metrics/prometheus_grafana/prometheus_pull.yml`](https://github.com/apache/dubbo-go-samples/blob/main/metrics/prometheus_grafana/prometheus_pull.yml).
 
-enter 【Prometheus server URL】 like `http://localhost:9090` and click 【Save & test】
+If you use your own Dubbo-Go application instead of this sample, replace the port with your application's metrics port.
 
-![datasource.png](/imgs/golang/metrics/dashboard.png)
+## 4. Grafana Configuration
 
-open 【Home / Dashboards 】click 【New】【import】and enter 19294 click Load
+### 4.1 Add Prometheus Data Source
 
-![import](/imgs/golang/metrics/import.png)
+1. Open [http://localhost:3000](http://localhost:3000)
+2. Default credentials: `admin / admin`
+3. Navigate to:
+
+```
+Home → Connections → Data sources
+```
+
+4. Click **Add new data source**
+5. Select **Prometheus**
+6. Enter:
+
+```
+http://host.docker.internal:9090
+```
+
+> Note: `host.docker.internal` allows Docker containers to access the host network. Replace with your actual IP if necessary.
+
+7. Click **Save & Test**
+
+### 4.2 Import Dubbo Dashboard
+
+1. Navigate to:
+
+```
+Home → Dashboards → New → Import
+```
 
-if your grafana can't access internet you can open `https://grafana.com/grafana/dashboards/19294-dubbo-observability/` and click 【Download JSON】
+2. Import the dashboard with one of these methods:
 
-paste the JSON
+* Upload [`grafana.json`](https://github.com/apache/dubbo-go-samples/blob/main/metrics/prometheus_grafana/grafana.json) from the sample directory
+* Enter Grafana dashboard ID `19294` (`Dubbo Observability`) and click **Load**
+* Or download the JSON from [Grafana Labs](https://grafana.com/grafana/dashboards/19294-dubbo-observability/) and upload it
 
-![json.png](/imgs/golang/metrics/import-json.png)
+3. The sample repository already includes the dashboard file at `metrics/prometheus_grafana/grafana.json`, so uploading that file is the most direct option.
 
-![datasource.png](/imgs/golang/metrics/import-datasource.png)
+4. Select the Prometheus data source
 
-click 【Import】button and you will see the Dubbo Observability dashboard, enjoy it
+5. Click **Import**
 
-![databoard](/imgs/golang/metrics/dashboard.png)
+### 4.3 View Dashboard
 
-## Deploy to Kubernetes
+You will see:
 
-#### kube-prometheus
+* QPS
+* Success rate
+* Latency (P99)
+* Consumer / Provider request statistics
+* Error rate
 
-install prometheus in k8s [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus)
+Metrics update dynamically as the client continuously calls the server.
 
-Set `prometheus-service.yaml` type to NodePort
+## 5. Pushgateway Zombie Metrics Problem
 
-1. add `dubboPodMoitor.yaml` to `kube-prometheus` `manifests` dir, The content is as follows
- ```yaml
+### 5.1 Problem Description
+
+Pushgateway **does not automatically delete old metrics**.
+
+If a job stops:
+
+* Its metrics remain stored
+* This may pollute monitoring data
+
+### 5.2 Solution 1: Application-side Cleanup (Implemented)
+
+Mechanism:
+
+* Register `job_pushed_at_seconds`
+* Periodically update timestamp
+* Automatically call DELETE API on graceful shutdown
+
+### 5.3 Solution 2: Production-grade Cleaner (Recommended)
+
+Tool repository:
+
+> [apache/dubbo-go-samples/tree/main/tools/pgw-cleaner](https://github.com/apache/dubbo-go-samples/tree/main/tools/pgw-cleaner)
+
+Detailed documentation:
+
+* [README.md](https://github.com/apache/dubbo-go-samples/blob/main/tools/pgw-cleaner/README.md)
+
+This tool lives in the `apache/dubbo-go-samples` repository, not in the `apache/dubbo-go` core repository.
+
+Purpose:
+
+* Detect expired jobs
+* Automatically clean zombie metrics
+
+## 6. Troubleshooting
+
+### 6.1 Grafana Shows "No Data"
+
+Check:
+
+* Prometheus data source connection is successful
+* Prometheus → Status → Targets → pushgateway is **UP**
+* Query:
+
+```
+dubbo_consumer_requests_succeed_total
+```
+
+returns results
+
+### 6.2 host.docker.internal Not Reachable
+
+Replace it with your actual host IP:
+
+* Update `metrics/prometheus_grafana/prometheus_pull.yml`
+* Update Grafana data source URL
+
+## 7. Kubernetes Deployment
+
+Recommended:
+
+> kube-prometheus
+> [https://github.com/prometheus-operator/kube-prometheus](https://github.com/prometheus-operator/kube-prometheus)
+
+### 7.1 Create PodMonitor
+
+Create `dubboPodMonitor.yaml`:
+
+```yaml
 apiVersion: monitoring.coreos.com/v1
 kind: PodMonitor
 metadata:
-  name: podmonitor
-  labels:
-    app: podmonitor
+  name: dubbo-pod-monitor
   namespace: monitoring
 spec:
   namespaceSelector:
@@ -111,10 +276,15 @@ spec:
     matchLabels:
       app-type: dubbo
   podMetricsEndpoints:
-    - port: metrics # ref to dubbo-app port name metrics
+    - port: metrics
       path: /prometheus
----
-# rbac
+```
+
+### 7.2 Optional: Add RBAC Permissions When RBAC Is Enabled
+
+If your cluster enforces RBAC, grant Prometheus permission to read Pods in `dubbo-system`:
+
+```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: Role
 metadata:
@@ -124,9 +294,7 @@ rules:
   - apiGroups: [""]
     resources: ["pods"]
     verbs: ["get", "list", "watch"]
-
 ---
-# rbac
 apiVersion: rbac.authorization.k8s.io/v1
 kind: RoleBinding
 metadata:
@@ -141,7 +309,47 @@ subjects:
     name: prometheus-k8s
     namespace: monitoring
 ```
-2. `kubectl apply -f Deployment.yaml`
-3. open prometheus web page such as http://localhost:9090/targets
-   ![podmonitor.png](/imgs/golang/metrics/podmonitor.png)
 
+If your Prometheus installation uses a different service account, replace the `subjects` section accordingly.
+
+### 7.3 Deploy Application
+
+```bash
+kubectl apply -f Deployment.yaml
+```
+
+### 7.4 Verify
+
+Visit:
+
+```
+http://<prometheus-nodeport>/targets
+```
+
+Ensure your pods show:
+
+```
+UP
+```
+
+## 8. Production Recommendations
+
+| Scenario              | Recommended Mode  |
+| --------------------- | ----------------- |
+| Long-running services | Pull              |
+| Short-lived jobs      | Push              |
+| Kubernetes            | Pull + PodMonitor |
+| Pushgateway usage     | Use pgw-cleaner   |
+
+## 9. Summary
+
+Dubbo-Go provides:
+
+* Pull-based Prometheus integration
+* Push-based Pushgateway integration
+* Docker quick-start stack
+* Kubernetes PodMonitor support
+* Grafana dashboards
+* Zombie metric cleanup support
+
+With this setup, you can build a complete Dubbo-Go observability system.
diff --git a/content/zh-cn/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md b/content/zh-cn/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md
index 79f58b00ddb..61a0da8d7f6 100644
--- a/content/zh-cn/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md
+++ b/content/zh-cn/overview/mannual/golang-sdk/tutorial/observability/rpc_metrics.md
@@ -2,106 +2,277 @@
 aliases:
     - /zh/docs3-v2/golang-sdk/tutorial/governance/monitor/rpc_metrics/
     - /zh-cn/docs3-v2/golang-sdk/tutorial/governance/monitor/rpc_metrics/
-description: "采集运行态 Metrics 指标并接入 Prometheus、Grafana 系统"
-title: metrics监控
+description: "Dubbo-Go 指标监控：支持 Prometheus Pull 模式与 Pushgateway Push 模式，并接入 Grafana 可视化"
+title: 指标监控 (Metrics)
 type: docs
 weight: 2
 ---
 
-Dubbo 支持采集运行态 Metrics 指标并接入 Prometheus、Grafana 系统，实现对微服务集群的可视化监控，以下是一个具体的使用示例，可查看 [示例完整源码](https://github.com/apache/dubbo-go-samples/tree/main/metrics)。
 
-## Contents
+# Dubbo-Go 指标监控
 
-- server/main.go - is the main definition of the service, handler and rpc server
-- client/main.go - is the rpc client
-- proto - contains the protobuf definition of the API
+Dubbo-Go 支持采集运行态 Metrics 指标，并接入 **Prometheus + Grafana** 实现微服务可观测性。
 
-## How to run
+当前示例支持两种监控模式：
 
-### Run server
-```shell
-go run ./go-server/cmd/main.go
+* **Pull 模式**：Prometheus 主动抓取 Dubbo-Go 应用暴露的指标，适合长期运行的服务。
+* **Push 模式**：Dubbo-Go 应用主动将指标推送到 Pushgateway，仅建议用于短生命周期任务。
+
+示例源码：
+
+> [https://github.com/apache/dubbo-go-samples/tree/main/metrics](https://github.com/apache/dubbo-go-samples/tree/main/metrics)
+
+## 1. 监控架构说明
+
+### 1.1 Pull 模式（推荐生产模式）
+
+```
+Dubbo-Go 应用  --->  Prometheus  --->  Grafana
+        (暴露 /metrics 或 /prometheus 接口)
+```
+
+Prometheus 主动抓取 Dubbo-Go 应用指标。
+
+### 1.2 Push 模式（适用于短生命周期任务）
+
+```
+Dubbo-Go 应用  --->  Pushgateway  --->  Prometheus  --->  Grafana
+```
+
+应用主动推送指标到 Pushgateway，Prometheus 再拉取。
+
+Pushgateway 适用于 **短生命周期任务（如 batch / cron job）**，不推荐用于长期运行的服务。
+
+## 2. 示例组件说明
+
+| 组件          | 端口   | 说明                   |
+| ----------- | ---- | -------------------- |
+| Grafana     | 3000 | 指标可视化                |
+| Prometheus  | 9090 | 指标存储与查询              |
+| Pushgateway | 9091 | 接收应用推送指标             |
+| go-server 指标端口 | 本示例中为 9099 | Pull 模式下 Provider 指标暴露端口 |
+| go-client 指标端口 | 本示例中为 9097 | Pull 模式下 Consumer 指标暴露端口 |
+
+如果不使用本示例，而是直接使用 Dubbo-Go 默认配置，则默认指标端点为 `http://localhost:9090/metrics`。当前 sample 将指标路径改成了 `/prometheus`。
+
+## 3. 快速开始
+
+### 3.1 启动监控服务栈
+
+进入目录：
+
+```bash
+cd metrics/prometheus_grafana
+```
+
+启动监控组件：
+
+```bash
+docker-compose up -d
+```
+
+访问地址：
+
+* Grafana: [http://localhost:3000](http://localhost:3000)
+* Prometheus: [http://localhost:9090](http://localhost:9090)
+* Pushgateway: [http://localhost:9091](http://localhost:9091)
+
+### 3.2 配置环境变量
+
+客户端与服务端使用相同环境变量：
+
+```bash
+export ZK_ADDRESS="127.0.0.1:2181"
+
+# Push 模式必需
+export PUSHGATEWAY_URL="127.0.0.1:9091"
+export JOB_NAME="dubbo-service"
+
+# 可选
+export PUSHGATEWAY_USER="username"
+export PUSHGATEWAY_PASS="1234"
 ```
 
-test server work as expected:
-```shell
-curl \
-    --header "Content-Type: application/json" \
-    --data '{"name": "Dubbo"}' \
-    http://localhost:20000/greet.GreetService/Greet
+### 3.3 启动 Dubbo-Go 服务端
+
+```bash
+go run ./go-server/cmd/main.go
 ```
 
-### Run client
-```shell
+### 3.4 启动 Dubbo-Go 客户端
+
+#### 默认 Push 模式
+
+```bash
 go run ./go-client/cmd/main.go
 ```
 
-## deploy to local
-install prometheus and open prometheus config file `prometheus.yml`, write the config like this
+#### 使用 Pull 模式
+
+```bash
+go run ./go-client/cmd/main.go --push=false
+go run ./go-server/cmd/main.go --push=false
+```
+
+### 3.5 验证指标
+
+#### Push 模式
+
+访问：
+
+```
+http://localhost:9091/metrics
+```
+
+#### Pull 模式
+
+`<应用端口>` 指的是 Dubbo-Go 应用自身暴露 Prometheus 指标的 HTTP 端口，不是 Prometheus 或 Pushgateway 的端口。
+
+在当前 sample 中：
+
+* Provider：`http://localhost:9099/prometheus`
+* Consumer：`http://localhost:9097/prometheus`
+
+这两个端口定义在 [`metrics/prometheus_grafana/prometheus_pull.yml`](https://github.com/apache/dubbo-go-samples/blob/main/metrics/prometheus_grafana/prometheus_pull.yml) 中。
+
+如果你使用的是自己的 Dubbo-Go 应用，请将端口替换成应用实际配置的指标端口。
+
+## 4. Grafana 配置
+
+### 4.1 添加 Prometheus 数据源
+
+1. 打开 [http://localhost:3000](http://localhost:3000)
+2. 默认账号：admin / admin
+3. 进入：
 
-```yaml
-global:
-  evaluation_interval: 15s
-  scrape_interval: 15s
-scrape_configs:
-- job_name: dubbo-provider
-  scrape_interval: 15s
-  scrape_timeout: 5s
-  metrics_path: /prometheus
-  static_configs:
-    - targets: ['localhost:9099']
-- job_name: dubbo-consumer
-  scrape_interval: 15s
-  scrape_timeout: 5s
-  metrics_path: /prometheus
-  static_configs:
-    - targets: ['localhost:9097']
+```
+Home → Connections → Data sources
 ```
 
-install grafana and open grafana web page like `localhost:3000`
+4. 点击 **Add new data source**
+5. 选择 Prometheus
+6. 填写：
 
-open: 【Home / Connections / Data sources】
+```
+http://host.docker.internal:9090
+```
 
-click 【Add new data source】
+> 说明：`host.docker.internal` 用于让 Docker 容器访问宿主机网络。如果该地址不可用，请替换为宿主机实际 IP。
 
-select Prometheus
+7. 点击 Save & Test
 
-enter 【Prometheus server URL】 like `http://localhost:9090` and click 【Save & test】
+### 4.2 导入 Dubbo 监控大盘
 
-![datasource.png](/imgs/golang/metrics/dashboard.png)
+1. 进入：
 
-open 【Home / Dashboards 】click 【New】【import】and enter 19294 click Load
+```
+Home → Dashboards → New → Import
+```
 
-![import](/imgs/golang/metrics/import.png)
+2. 使用以下任一方式导入：
 
-if your grafana can't access internet you can open `https://grafana.com/grafana/dashboards/19294-dubbo-observability/` and click 【Download JSON】
+* 直接上传 sample 目录中的 [`grafana.json`](https://github.com/apache/dubbo-go-samples/blob/main/metrics/prometheus_grafana/grafana.json)
+* 输入 Grafana dashboard ID `19294`（`Dubbo Observability`）后点击 **Load**
+* 或从 [Grafana Labs](https://grafana.com/grafana/dashboards/19294-dubbo-observability/) 下载 JSON 文件再上传
 
-paste the JSON
+3. sample 仓库已经直接提供 `metrics/prometheus_grafana/grafana.json`，因此优先上传这个文件即可。
 
-![json.png](/imgs/golang/metrics/import-json.png)
+4. 选择 Prometheus 数据源
+5. 点击 Import
 
-![datasource.png](/imgs/golang/metrics/import-datasource.png)
+### 4.3 查看效果
 
-click 【Import】button and you will see the Dubbo Observability dashboard,enjoy it
+你将看到：
 
-![databoard](/imgs/golang/metrics/dashboard.png)
+* QPS
+* 成功率
+* 请求延迟 P99
+* Consumer / Provider 调用统计
+* 错误率
 
-## Deploy to Kubernetes
+## 5. Pushgateway 僵尸指标问题
 
-#### kube-prometheus
+### 5.1 问题说明
 
-install prometheus in k8s [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus)
+Pushgateway 默认：
 
-Set `prometheus-service.yaml` type to NodePort
+> 不会自动删除旧指标
 
-1. add `dubboPodMoitor.yaml` to  `kube-prometheus` `manifests` dir, The content is as follows
- ```yaml
+任务停止后：
+
+* 指标仍然保留
+* 会导致数据污染
+
+### 5.2 方案一：应用侧自动清理（已实现）
+
+机制：
+
+* 注册 `job_pushed_at_seconds`
+* 定期更新时间戳
+* 优雅退出时自动 DELETE
+
+### 5.3 方案二：运维清理器（推荐生产使用）
+
+工具仓库位置：
+
+> [apache/dubbo-go-samples/tree/main/tools/pgw-cleaner](https://github.com/apache/dubbo-go-samples/tree/main/tools/pgw-cleaner)
+
+详细说明：
+
+* [README_CN.md](https://github.com/apache/dubbo-go-samples/blob/main/tools/pgw-cleaner/README_CN.md)
+
+该工具位于 `apache/dubbo-go-samples` 仓库中，不在 `apache/dubbo-go` 主仓库内。
+
+用于：
+
+* 自动扫描过期指标
+* 定期清理僵尸 job
+
+## 6. 常见问题
+
+### 6.1 Grafana 显示 No Data
+
+请检查：
+
+* Prometheus 数据源是否测试成功
+* Prometheus → Status → Targets 是否为 UP
+* 查询：
+
+```
+dubbo_consumer_requests_succeed_total
+```
+
+是否有数据
+
+### 6.2 host.docker.internal 无法访问
+
+请改为实际 IP 地址：
+
+* 修改 `metrics/prometheus_grafana/prometheus_pull.yml`
+* 修改 Grafana 数据源 URL
+
+## 7. Kubernetes 部署
+
+推荐使用：
+
+> kube-prometheus
+> [https://github.com/prometheus-operator/kube-prometheus](https://github.com/prometheus-operator/kube-prometheus)
+
+### 7.1 添加 PodMonitor
+
+创建：
+
+```
+dubboPodMonitor.yaml
+```
+
+内容：
+
+```yaml
 apiVersion: monitoring.coreos.com/v1
 kind: PodMonitor
 metadata:
-  name: podmonitor
-  labels:
-    app: podmonitor
+  name: dubbo-pod-monitor
   namespace: monitoring
 spec:
   namespaceSelector:
@@ -111,10 +282,15 @@ spec:
     matchLabels:
       app-type: dubbo
   podMetricsEndpoints:
-    - port: metrics # ref to dubbo-app port name metrics
+    - port: metrics
       path: /prometheus
----
-# rbac
+```
+
+### 7.2 可选：集群启用 RBAC 时补充权限配置
+
+如果集群开启了 RBAC，建议为 Prometheus 增加对 `dubbo-system` 命名空间内 Pod 的读取权限：
+
+```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: Role
 metadata:
@@ -124,9 +300,7 @@ rules:
   - apiGroups: [""]
     resources: ["pods"]
     verbs: ["get", "list", "watch"]
-
 ---
-# rbac
 apiVersion: rbac.authorization.k8s.io/v1
 kind: RoleBinding
 metadata:
@@ -141,7 +315,47 @@ subjects:
     name: prometheus-k8s
     namespace: monitoring
 ```
-2. `kubectl apply -f Deployment.yaml`
-3. open prometheus web page such as http://localhost:9090/targets
-   ![podmonitor.png](/imgs/golang/metrics/podmonitor.png)
 
+如果你的 Prometheus 安装使用的 ServiceAccount 不是 `prometheus-k8s`，请按实际名称修改 `subjects`。
+
+### 7.3 部署应用
+
+```bash
+kubectl apply -f Deployment.yaml
+```
+
+### 7.4 验证
+
+访问：
+
+```
+http://<prometheus-nodeport>/targets
+```
+
+确认 Pod 状态为：
+
+```
+UP
+```
+
+## 8. 生产建议
+
+| 场景      | 推荐模式              |
+| ------- | ----------------- |
+| 长期运行服务  | Pull              |
+| 短生命周期任务 | Push              |
+| K8s 环境  | Pull + PodMonitor |
+| 需要清理能力  | 配合 pgw-cleaner    |
+
+## 9. 总结
+
+Dubbo-Go 当前支持：
+
+* Pull 模式（标准 Prometheus 模式）
+* Push 模式（Pushgateway）
+* Docker 快速部署
+* Kubernetes PodMonitor
+* Grafana 大盘
+* 僵尸指标自动治理
+
+通过以上配置，可以实现完整的 Dubbo-Go 可观测性体系。