This is an automated email from the ASF dual-hosted git repository.
Duansg pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/hertzbeat.git
The following commit(s) were added to refs/heads/master by this push:
new 42307a9928 [feat] Support etcd monitoring (#4306)
42307a9928 is described below
commit 42307a9928ebe967c31ad7840d57d55a398bd73e
Author: NekoPunch <[email protected]>
AuthorDate: Sun Aug 9 09:10:00 2026 -0700
[feat] Support etcd monitoring (#4306)
Co-authored-by: Duansg <[email protected]>
---
.../collect/basic/http/EtcdMonitorE2eTest.java | 158 ++++++++++
.../src/test/resources/http/etcd/metrics.txt | 17 ++
.../src/main/resources/define/app-etcd.yml | 328 +++++++++++++++++++++
home/docs/help/etcd.md | 65 ++++
.../current/help/etcd.md | 65 ++++
home/sidebars.json | 1 +
6 files changed, 634 insertions(+)
diff --git
a/hertzbeat-e2e/hertzbeat-collector-basic-e2e/src/test/java/org/apache/hertzbeat/collector/collect/basic/http/EtcdMonitorE2eTest.java
b/hertzbeat-e2e/hertzbeat-collector-basic-e2e/src/test/java/org/apache/hertzbeat/collector/collect/basic/http/EtcdMonitorE2eTest.java
new file mode 100644
index 0000000000..3233adf8f7
--- /dev/null
+++
b/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);
+ }
+}
diff --git
a/hertzbeat-e2e/hertzbeat-collector-basic-e2e/src/test/resources/http/etcd/metrics.txt
b/hertzbeat-e2e/hertzbeat-collector-basic-e2e/src/test/resources/http/etcd/metrics.txt
new file mode 100644
index 0000000000..45969a7b6b
--- /dev/null
+++
b/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
diff --git a/hertzbeat-manager/src/main/resources/define/app-etcd.yml
b/hertzbeat-manager/src/main/resources/define/app-etcd.yml
new file mode 100644
index 0000000000..d177dd9dc8
--- /dev/null
+++ b/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 [...]
+ 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-met [...]
+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
diff --git a/home/docs/help/etcd.md b/home/docs/help/etcd.md
new file mode 100644
index 0000000000..e9395a85eb
--- /dev/null
+++ b/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 |
diff --git
a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/etcd.md
b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/etcd.md
new file mode 100644
index 0000000000..5a672fc08c
--- /dev/null
+++ b/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 | 进程常驻内存大小 |
diff --git a/home/sidebars.json b/home/sidebars.json
index fd24405bbe..b42a8db679 100755
--- a/home/sidebars.json
+++ b/home/sidebars.json
@@ -245,6 +245,7 @@
"help/kafka_client",
"help/pulsar",
"help/nacos",
+ "help/etcd",
"help/rabbitmq",
"help/rocketmq",
"help/shenyu",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
