[feat] Support etcd monitoring (#4306)

Co-authored-by: Duansg <siguoduan@gmail.com>

hertzbeat-e2e/hertzbeat-collector-basic-e2e/src/test/java/org/apache/hertzbeat/collector/collect/basic/http/EtcdMonitorE2eTest.java

@@ -0,0 +1,158 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hertzbeat.collector.collect.basic.http;
+
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.hertzbeat.collector.collect.AbstractCollectE2eTest;
+import org.apache.hertzbeat.collector.collect.http.HttpCollectImpl;
+import org.apache.hertzbeat.collector.dispatch.CollectDataDispatch;
+import org.apache.hertzbeat.collector.dispatch.MetricsCollect;
+import org.apache.hertzbeat.collector.dispatch.unit.impl.DataSizeConvert;
+import org.apache.hertzbeat.collector.timer.WheelTimerTask;
+import org.apache.hertzbeat.collector.util.CollectUtil;
+import org.apache.hertzbeat.common.entity.job.Configmap;
+import org.apache.hertzbeat.common.entity.job.Job;
+import org.apache.hertzbeat.common.entity.job.Metrics;
+import org.apache.hertzbeat.common.entity.job.protocol.HttpProtocol;
+import org.apache.hertzbeat.common.entity.job.protocol.Protocol;
+import org.apache.hertzbeat.common.entity.message.CollectRep;
+import org.apache.hertzbeat.common.timer.Timeout;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.util.ResourceUtils;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.HashMap;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Integration test for etcd monitoring functionality.
+ * Fixture at src/test/resources/http/etcd/metrics.txt is a real capture from a live
+ * etcd v3.5.17 /metrics endpoint (see app-etcd.yml for the corresponding template).
+ */
+@Slf4j
+@ExtendWith(MockitoExtension.class)
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+public class EtcdMonitorE2eTest extends AbstractCollectE2eTest {
+
+    private static final int MOCK_SERVER_PORT = 52379;
+    private static final String LOCALHOST = "127.0.0.1";
+    private static HttpServer mockServer;
+
+    @AfterAll
+    public static void tearDown() {
+        if (mockServer != null) {
+            mockServer.stop(0);
+        }
+    }
+
+    @BeforeEach
+    public void setUp() throws Exception {
+        super.setUp();
+        collect = new HttpCollectImpl();
+
+        // the shared harness wires MetricsCollect with an empty unit-convert list,
+        // but this template relies on B->MB conversion
+        Timeout convertTimeout = mock(Timeout.class);
+        WheelTimerTask convertTimerJob = mock(WheelTimerTask.class);
+        when(convertTimeout.task()).thenReturn(convertTimerJob);
+        when(convertTimerJob.getJob()).thenReturn(mock(Job.class));
+        metricsCollect = new MetricsCollect(mock(Metrics.class), convertTimeout,
+                mock(CollectDataDispatch.class), null, List.of(new DataSizeConvert()));
+
+        String metricsResponse = loadResponseFromFile("classpath:http/etcd/metrics.txt");
+
+        mockServer = HttpServer.create(new InetSocketAddress(MOCK_SERVER_PORT), 0);
+        mockServer.setExecutor(null);
+        mockServer.start();
+        mockServer.createContext("/metrics", exchange -> sendTextResponse(exchange, metricsResponse));
+    }
+
+    private String loadResponseFromFile(String resourcePath) throws Exception {
+        return new String(Files.readAllBytes(ResourceUtils.getFile(resourcePath).toPath()));
+    }
+
+    private void sendTextResponse(HttpExchange exchange, String response) throws IOException {
+        exchange.getResponseHeaders().set("Content-Type", "text/plain");
+        final byte[] array = response.getBytes(StandardCharsets.UTF_8);
+        exchange.sendResponseHeaders(200, array.length);
+        try (OutputStream os = exchange.getResponseBody()) {
+            os.write(array);
+        }
+    }
+
+    private static final Map<String, String> EXPECTED_VALUES = Map.of(
+            "etcd_server_has_leader", "1",
+            "etcd_mvcc_db_total_size_in_bytes", "0.0195",
+            "etcd_server_leader_changes_seen_total", "1",
+            "process_cpu_seconds_total", "42.41",
+            "process_resident_memory_bytes", "29.9844");
+
+    @Test
+    public void testEtcdMonitor() {
+        Job etcdJob = appService.getAppDefine("etcd");
+        List<Map<String, Configmap>> configmapFromPreCollectData = new LinkedList<>();
+        for (Metrics metricsDef : etcdJob.getMetrics()) {
+            metricsDef = CollectUtil.replaceCryPlaceholderToMetrics(metricsDef,
+                    !configmapFromPreCollectData.isEmpty() ? configmapFromPreCollectData.get(0) : new HashMap<>());
+            CollectRep.MetricsData metricsData = validateMetricsCollection(metricsDef, metricsDef.getName());
+            Assertions.assertEquals(EXPECTED_VALUES.get(metricsDef.getName()),
+                    metricsData.getValues().get(0).getColumns(0),
+                    metricsDef.getName() + " collected value mismatch");
+            configmapFromPreCollectData = CollectUtil.getConfigmapFromPreCollectData(metricsData);
+        }
+    }
+
+    @Override
+    protected Protocol buildProtocol(Metrics metricsDef) {
+        HttpProtocol protocol = new HttpProtocol();
+        protocol.setHost(LOCALHOST);
+        protocol.setPort(String.valueOf(MOCK_SERVER_PORT));
+        protocol.setMethod(metricsDef.getHttp().getMethod());
+        protocol.setParseType(metricsDef.getHttp().getParseType());
+        protocol.setParseScript(metricsDef.getHttp().getParseScript());
+        protocol.setUrl(metricsDef.getHttp().getUrl());
+        return protocol;
+    }
+
+    @Override
+    protected CollectRep.MetricsData.Builder collectMetrics(Metrics metricsDef) {
+        HttpProtocol protocol = (HttpProtocol) buildProtocol(metricsDef);
+        metrics.setHttp(protocol);
+        // prometheus parseType filters by builder.getMetrics(); production sets it in
+        // MetricsCollect.run() but this test harness does not, so set it here
+        CollectRep.MetricsData.Builder metricsData = CollectRep.MetricsData.newBuilder()
+                .setMetrics(metricsDef.getName());
+        return collectMetricsData(metrics, metricsDef, metricsData);
+    }
+}

hertzbeat-e2e/hertzbeat-collector-basic-e2e/src/test/resources/http/etcd/metrics.txt

@@ -0,0 +1,17 @@
+# Captured from a live etcd v3.5.17 /metrics endpoint, trimmed to the metric
+# families used by app-etcd.yml.
+# HELP etcd_mvcc_db_total_size_in_bytes Total size of the underlying database physically allocated in bytes.
+# TYPE etcd_mvcc_db_total_size_in_bytes gauge
+etcd_mvcc_db_total_size_in_bytes 20480
+# HELP etcd_server_has_leader Whether or not a leader exists. 1 is existence, 0 is not.
+# TYPE etcd_server_has_leader gauge
+etcd_server_has_leader 1
+# HELP etcd_server_leader_changes_seen_total The number of leader changes seen.
+# TYPE etcd_server_leader_changes_seen_total counter
+etcd_server_leader_changes_seen_total 1
+# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
+# TYPE process_cpu_seconds_total counter
+process_cpu_seconds_total 42.41
+# HELP process_resident_memory_bytes Resident memory size in bytes.
+# TYPE process_resident_memory_bytes gauge
+process_resident_memory_bytes 3.1440896e+07

hertzbeat-manager/src/main/resources/define/app-etcd.yml

@@ -0,0 +1,328 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The monitoring type category：service-application service monitoring db-database monitoring custom-custom monitoring os-operating system monitoring mid-middleware
+category: mid
+# The monitoring type eg: linux windows tomcat mysql aws...
+app: etcd
+# The monitoring i18n name
+name:
+  zh-CN: etcd
+  en-US: etcd
+  ja-JP: etcd
+# The description and help of this monitoring type
+help:
+  zh-CN: HertzBeat 通过调用 <a href='https://etcd.io/docs/latest/metrics/' class='help_module_content'>etcd Prometheus Metrics 接口</a>（默认在客户端端口 <i>2379</i> 的 <i>/metrics</i> 路径）对 etcd 键值存储（3.4+）的领导者状态、数据库大小、进程资源等指标进行采集监控。<br>您可以点击“<i>新建 etcd</i>”并配置 HOST 端口等相关参数进行添加。<br><span class='help_module_span'>⚠️注意：请确保 HertzBeat 能访问 etcd 的 /metrics 接口。该接口默认由 client listener 提供；若 etcd 仅监听 localhost 或客户端启用了双向 TLS，请通过 --listen-metrics-urls 配置独立的 metrics 地址。</span>
+  en-US: HertzBeat monitors the etcd key-value store's (3.4+) leader status, database size and process resource usage by calling the <a href='https://etcd.io/docs/latest/metrics/' class='help_module_content'>etcd Prometheus Metrics endpoint</a> (default at the <i>/metrics</i> path on the client port <i>2379</i>).<br>You can click "<i>New etcd</i>" and configure the host, port and other related params to add it.<br><span class='help_module_span'>Note - make sure HertzBeat can reach etcd's /metrics endpoint. It is served on the client listener by default; if etcd only listens on localhost or client mutual TLS is enabled, configure a dedicated metrics address via --listen-metrics-urls.</span>
+  zh-TW: HertzBeat 透過調用 <a href='https://etcd.io/docs/latest/metrics/' class='help_module_content'>etcd Prometheus Metrics 介面</a>（預設在客戶端連接埠 <i>2379</i> 的 <i>/metrics</i> 路徑）對 etcd 鍵值儲存（3.4+）的領導者狀態、資料庫大小、程序資源等指標進行採集監控。<br>您可以點擊“<i>新建 etcd</i>”並配置 HOST 連接埠等相關參數進行添加。<br><span class='help_module_span'>⚠️注意：請確保 HertzBeat 能訪問 etcd 的 /metrics 介面。該介面預設由 client listener 提供；若 etcd 僅監聽 localhost 或客戶端啟用了雙向 TLS，請透過 --listen-metrics-urls 配置獨立的 metrics 地址。</span>
+  ja-JP: HertzBeat は etcd（3.4+）が公開する <a href='https://etcd.io/docs/latest/metrics/' class='help_module_content'>Prometheus metrics エンドポイント</a>（デフォルトではクライアントポート <i>2379</i> の <i>/metrics</i> パス）から、リーダー状態・データベースサイズ・プロセスリソース等の指標を収集し、etcd キーバリューストアを監視します。<br>「<i>新規 etcd</i>」をクリックしてホストやポートなどのパラメータを設定して追加できます。<br><span class='help_module_span'>⚠️注意：HertzBeat が etcd の /metrics エンドポイントへ到達できることを確認してください。デフォルトでは client listener が提供しますが、etcd が localhost のみを監視している場合やクライアント相互 TLS が有効な場合は、--listen-metrics-urls で専用の metrics アドレスを設定してください。</span>
+helpLink:
+  zh-CN: https://hertzbeat.apache.org/zh-cn/docs/help/etcd/
+  en-US: https://hertzbeat.apache.org/docs/help/etcd/
+# Input params define for monitoring(render web ui by the definition)
+params:
+  # field-param field key
+  - field: host
+    # name-param field display i18n name
+    name:
+      zh-CN: 目标Host
+      en-US: Target Host
+      ja-JP: 目標ホスト
+    # type-param field type(most mapping the html input type)
+    type: host
+    # required-true or false
+    required: true
+  - field: port
+    name:
+      zh-CN: 端口
+      en-US: Port
+      ja-JP: ポート
+    # type-param field type(most mapping the html input type)
+    type: number
+    # when type is number, range is required
+    range: '[0,65535]'
+    # default value: etcd client port that serves /metrics
+    defaultValue: 2379
+    required: true
+  - field: timeout
+    name:
+      zh-CN: 查询超时时间
+      en-US: Query Timeout
+      ja-JP: クエリタイムアウト
+    type: number
+    required: false
+    # hide param-true or false
+    hide: true
+    defaultValue: 6000
+  # field-param field key
+  - field: ssl
+    # name-param field display i18n name
+    name:
+      zh-CN: 启用HTTPS
+      en-US: HTTPS
+      ja-JP: HTTPS
+    # type-param field type(most mapping the html input type)
+    type: boolean
+    hide: true
+    # field-param field key
+  - field: headers
+    # name-param field display i18n name
+    name:
+      zh-CN: 请求Headers
+      en-US: Headers
+      ja-JP: ヘッダ
+    # type-param field type(most mapping the html input type)
+    type: key-value
+    # required-true or false
+    required: false
+    hide: true
+    # when type is key-value, use keyAlias to config key alias name
+    keyAlias: Header Name
+    # when type is key-value, use valueAlias to config value alias name
+    valueAlias: Header Value
+    # field-param field key
+  - field: authType
+    # name-param field display i18n name
+    name:
+      zh-CN: 认证方式
+      en-US: Auth Type
+      ja-JP: 認証方法
+    # type-param field type(most mapping the html input type)
+    type: radio
+    # required-true or false
+    required: false
+    # hide param-true or false
+    hide: true
+    # when type is radio checkbox, use option to show optional values {name1:value1,name2:value2}
+    options:
+      - label: Basic Auth
+        value: Basic Auth
+      - label: Digest Auth
+        value: Digest Auth
+    # field-param field key
+  - field: username
+    # name-param field display i18n name
+    name:
+      zh-CN: 用户名
+      en-US: Username
+      ja-JP: ユーザー名
+    # type-param field type(most mapping the html input type)
+    type: text
+    # when type is text, use limit to limit string length
+    limit: 50
+    # required-true or false
+    required: false
+    # hide param-true or false
+    hide: true
+    # field-param field key
+  - field: password
+    # name-param field display i18n name
+    name:
+      zh-CN: 密码
+      en-US: Password
+      ja-JP: パスワード
+    # type-param field type(most mapping the html input type)
+    type: password
+    # required-true or false
+    required: false
+    # hide param-true or false
+    hide: true
+# collect metrics config list
+# each metrics group name must exactly match a Prometheus metric family name exposed by etcd /metrics
+metrics:
+  # metrics - etcd_server_has_leader (availability: whether this etcd member has a raft leader)
+  - name: etcd_server_has_leader
+    i18n:
+      zh-CN: 领导者状态
+      en-US: Leader Status
+      ja-JP: リーダー状態
+    # metrics scheduling priority(0->127)->(high->low), metrics with the same priority will be scheduled in parallel
+    # priority 0's metrics is availability metrics, it will be scheduled first, only availability metrics collect success will the scheduling continue
+    priority: 0
+    fields:
+      - field: hasLeader
+        type: 0
+        i18n:
+          zh-CN: 是否存在领导者(1有0无)
+          en-US: Has Leader(1=yes 0=no)
+          ja-JP: リーダー有無(1=有 0=無)
+    aliasFields:
+      - value
+    calculates:
+      - hasLeader=value
+    protocol: http
+    http:
+      host: ^_^host^_^
+      port: ^_^port^_^
+      url: /metrics
+      timeout: ^_^timeout^_^
+      ssl: ^_^ssl^_^
+      method: GET
+      headers:
+        ^_^headers^_^: ^_^headers^_^
+      authorization:
+        type: ^_^authType^_^
+        basicAuthUsername: ^_^username^_^
+        basicAuthPassword: ^_^password^_^
+        digestAuthUsername: ^_^username^_^
+        digestAuthPassword: ^_^password^_^
+      parseType: prometheus
+  # metrics - etcd_mvcc_db_total_size_in_bytes
+  - name: etcd_mvcc_db_total_size_in_bytes
+    i18n:
+      zh-CN: 数据库大小
+      en-US: Database Size
+      ja-JP: データベースサイズ
+    priority: 1
+    fields:
+      - field: dbSize
+        type: 0
+        unit: MB
+        i18n:
+          zh-CN: 物理分配的数据库大小
+          en-US: Physically Allocated DB Size
+          ja-JP: 物理割当済みDBサイズ
+    aliasFields:
+      - value
+    calculates:
+      - dbSize=value
+    units:
+      - dbSize=B->MB
+    protocol: http
+    http:
+      host: ^_^host^_^
+      port: ^_^port^_^
+      url: /metrics
+      timeout: ^_^timeout^_^
+      ssl: ^_^ssl^_^
+      method: GET
+      headers:
+        ^_^headers^_^: ^_^headers^_^
+      authorization:
+        type: ^_^authType^_^
+        basicAuthUsername: ^_^username^_^
+        basicAuthPassword: ^_^password^_^
+        digestAuthUsername: ^_^username^_^
+        digestAuthPassword: ^_^password^_^
+      parseType: prometheus
+  # metrics - etcd_server_leader_changes_seen_total
+  - name: etcd_server_leader_changes_seen_total
+    i18n:
+      zh-CN: 领导者变更次数
+      en-US: Leader Changes
+      ja-JP: リーダー変更回数
+    priority: 1
+    fields:
+      - field: leaderChanges
+        type: 0
+        i18n:
+          zh-CN: 已观测到的领导者变更总次数
+          en-US: Total Leader Changes Seen
+          ja-JP: 観測されたリーダー変更総数
+    aliasFields:
+      - value
+    calculates:
+      - leaderChanges=value
+    protocol: http
+    http:
+      host: ^_^host^_^
+      port: ^_^port^_^
+      url: /metrics
+      timeout: ^_^timeout^_^
+      ssl: ^_^ssl^_^
+      method: GET
+      headers:
+        ^_^headers^_^: ^_^headers^_^
+      authorization:
+        type: ^_^authType^_^
+        basicAuthUsername: ^_^username^_^
+        basicAuthPassword: ^_^password^_^
+        digestAuthUsername: ^_^username^_^
+        digestAuthPassword: ^_^password^_^
+      parseType: prometheus
+  # metrics - process_cpu_seconds_total (standard Go/Prometheus client process collector, always present)
+  - name: process_cpu_seconds_total
+    i18n:
+      zh-CN: 进程CPU时间
+      en-US: Process CPU Time
+      ja-JP: プロセスCPU時間
+    priority: 1
+    fields:
+      - field: cpuSeconds
+        type: 0
+        unit: s
+        i18n:
+          zh-CN: 累计用户与系统CPU时间
+          en-US: Total User+System CPU Time
+          ja-JP: 累計ユーザー+システムCPU時間
+    aliasFields:
+      - value
+    calculates:
+      - cpuSeconds=value
+    protocol: http
+    http:
+      host: ^_^host^_^
+      port: ^_^port^_^
+      url: /metrics
+      timeout: ^_^timeout^_^
+      ssl: ^_^ssl^_^
+      method: GET
+      headers:
+        ^_^headers^_^: ^_^headers^_^
+      authorization:
+        type: ^_^authType^_^
+        basicAuthUsername: ^_^username^_^
+        basicAuthPassword: ^_^password^_^
+        digestAuthUsername: ^_^username^_^
+        digestAuthPassword: ^_^password^_^
+      parseType: prometheus
+  # metrics - process_resident_memory_bytes
+  - name: process_resident_memory_bytes
+    i18n:
+      zh-CN: 进程内存占用
+      en-US: Process Resident Memory
+      ja-JP: プロセス常駐メモリ
+    priority: 1
+    fields:
+      - field: memory
+        type: 0
+        unit: MB
+        i18n:
+          zh-CN: 常驻内存大小
+          en-US: Resident Memory Size
+          ja-JP: 常駐メモリサイズ
+    aliasFields:
+      - value
+    calculates:
+      - memory=value
+    units:
+      - memory=B->MB
+    protocol: http
+    http:
+      host: ^_^host^_^
+      port: ^_^port^_^
+      url: /metrics
+      timeout: ^_^timeout^_^
+      ssl: ^_^ssl^_^
+      method: GET
+      headers:
+        ^_^headers^_^: ^_^headers^_^
+      authorization:
+        type: ^_^authType^_^
+        basicAuthUsername: ^_^username^_^
+        basicAuthPassword: ^_^password^_^
+        digestAuthUsername: ^_^username^_^
+        digestAuthPassword: ^_^password^_^
+      parseType: prometheus

home/docs/help/etcd.md

@@ -0,0 +1,65 @@
+---
+id: etcd
+title: Monitoring：etcd monitoring
+sidebar_label: etcd
+keywords: [open source monitoring tool, open source middleware monitoring tool, monitoring etcd metrics]
+---
+
+> HertzBeat monitors the etcd key-value store by collecting metrics from the Prometheus metrics endpoint that etcd exposes.
+>
+> etcd 3.4+ is supported (the database size metric `etcd_mvcc_db_total_size_in_bytes` replaced the old `etcd_debugging_*` name in 3.4).
+
+## PreRequisites
+
+### Make sure HertzBeat can reach etcd's metrics endpoint
+
+etcd exposes Prometheus-format metrics on its client port (default `2379`) at the `/metrics` path. Make sure this address is reachable from HertzBeat:
+
+1. If etcd only listens on localhost, or client mutual TLS is enabled on the client port, configure a dedicated metrics listener via [`--listen-metrics-urls`](https://etcd.io/docs/latest/op-guide/configuration/). It serves the metrics and health-check endpoints; if exposed without TLS, restrict it to a trusted network.
+2. Access `{metrics-host}:{metrics-port}/metrics` (the client port `2379` by default) from the HertzBeat host to confirm metrics data can be fetched.
+
+More information see [etcd monitoring documentation](https://etcd.io/docs/latest/op-guide/monitoring/).
+
+### Configuration parameter
+
+| Parameter name      | Parameter help description                                                                |
+|----------------------|---------------------------------------------------------------------------------------------|
+| Target Host          | Monitored IPV4, IPV6 or domain name. Note⚠️Without protocol header (eg: https://, http://) |
+| Port                 | Port of the etcd metrics endpoint, default 2379 when using the client listener             |
+| Query Timeout        | HTTP request timeout in milliseconds, default 6000                                          |
+| HTTPS                | Whether to use HTTPS to request the metrics endpoint                                        |
+| Headers              | Optional extra HTTP request headers                                                         |
+| Auth Type            | Optional Basic/Digest auth if the metrics endpoint sits behind an auth proxy                |
+| Username / Password  | Credentials used when Auth Type is set                                                      |
+
+### Collection Metric
+
+#### Metric set：etcd_server_has_leader
+
+| Metric name | Metric unit | Metric help description                                     |
+|-------------|-------------|---------------------------------------------------------------|
+| hasLeader   | none        | Whether this etcd member has a raft leader (1=yes, 0=no)       |
+
+#### Metric set：etcd_mvcc_db_total_size_in_bytes
+
+| Metric name | Metric unit | Metric help description                              |
+|-------------|-------------|--------------------------------------------------------|
+| dbSize      | MB          | Total size of the underlying database physically allocated |
+
+#### Metric set：etcd_server_leader_changes_seen_total
+
+| Metric name    | Metric unit | Metric help description                |
+|-----------------|-------------|-------------------------------------------|
+| leaderChanges   | none        | Total number of leader changes observed  |
+
+#### Metric set：process_cpu_seconds_total
+
+| Metric name | Metric unit | Metric help description                        |
+|-------------|-------------|---------------------------------------------------|
+| cpuSeconds  | second      | Cumulative user and system CPU time consumed      |
+
+#### Metric set：process_resident_memory_bytes
+
+| Metric name | Metric unit | Metric help description        |
+|-------------|-------------|-----------------------------------|
+| memory      | MB          | Resident memory size of the process |

home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/etcd.md

@@ -0,0 +1,65 @@
+---
+id: etcd
+title: 监控：etcd 监控
+sidebar_label: etcd
+keywords: [开源监控系统, 中间件监控, etcd监控]
+---
+
+> HertzBeat 通过采集 etcd 暴露的 Prometheus metrics 接口数据，对 etcd 键值存储进行监控。
+>
+> 支持 etcd 3.4 及以上版本（数据库大小指标 `etcd_mvcc_db_total_size_in_bytes` 自 3.4 起替代旧的 `etcd_debugging_*` 命名）。
+
+## 监控前操作
+
+### 确认 HertzBeat 能访问 etcd 的 metrics 接口
+
+etcd 会在客户端端口（默认 `2379`）的 `/metrics` 路径暴露 Prometheus 格式的指标。请确保 HertzBeat 能访问该地址：
+
+1. 若 etcd 仅监听 localhost，或客户端端口启用了双向 TLS，请通过 [`--listen-metrics-urls`](https://etcd.io/docs/latest/op-guide/configuration/) 配置独立的 metrics 监听地址。该地址提供 metrics 与健康检查端点；若不加 TLS 暴露，请仅限受信任网络访问。
+2. 从 HertzBeat 所在机器访问 `{metrics-host}:{metrics-port}/metrics`（默认为客户端端口 `2379`），确认能获取到 metrics 数据。
+
+更多信息请参考 [etcd 监控文档](https://etcd.io/docs/latest/op-guide/monitoring/)。
+
+### 配置参数
+
+| 参数名称   | 参数帮助描述                                       |
+|--------|-----------------------------------------------|
+| 目标Host | 被监控的对端IPV4，IPV6或域名。注意⚠️不带协议头(eg: https://, http://)。 |
+| 端口     | metrics 接口端口，使用客户端 listener 时默认为 2379        |
+| 查询超时时间 | HTTP请求超时时间，单位毫秒，默认6000                        |
+| 启用HTTPS | 是否使用 HTTPS 请求 metrics 接口                      |
+| 请求Headers | 可选的额外 HTTP 请求头                                |
+| 认证方式   | 若 metrics 接口在认证代理后面，可选 Basic/Digest 认证        |
+| 用户名/密码 | 配置认证方式后使用的凭据                                  |
+
+### 采集指标
+
+#### 指标集合：etcd_server_has_leader
+
+| 指标名称      | 指标单位 | 指标帮助描述                       |
+|-----------|------|------------------------------|
+| hasLeader | 无    | 该 etcd 成员是否存在 raft 领导者(1有0无) |
+
+#### 指标集合：etcd_mvcc_db_total_size_in_bytes
+
+| 指标名称   | 指标单位 | 指标帮助描述          |
+|--------|------|-----------------|
+| dbSize | MB   | 物理分配的数据库总大小     |
+
+#### 指标集合：etcd_server_leader_changes_seen_total
+
+| 指标名称           | 指标单位 | 指标帮助描述       |
+|----------------|------|--------------|
+| leaderChanges  | 无    | 已观测到的领导者变更总次数 |
+
+#### 指标集合：process_cpu_seconds_total
+
+| 指标名称       | 指标单位 | 指标帮助描述           |
+|------------|------|------------------|
+| cpuSeconds | 秒    | 累计用户与系统CPU使用时间   |
+
+#### 指标集合：process_resident_memory_bytes
+
+| 指标名称   | 指标单位 | 指标帮助描述  |
+|--------|------|---------|
+| memory | MB   | 进程常驻内存大小 |

home/sidebars.json

@@ -245,6 +245,7 @@
             "help/kafka_client",
             "help/pulsar",
             "help/nacos",
+            "help/etcd",
             "help/rabbitmq",
             "help/rocketmq",
             "help/shenyu",