This is an automated email from the ASF dual-hosted git repository.
spricoder pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new d19de74be04 [Doc] update ReadMe doc in metric module (#17388)
d19de74be04 is described below
commit d19de74be04ac4760516dd3e3aaa14f3cea9edeb
Author: ZhangHongYin <[email protected]>
AuthorDate: Sun Mar 29 21:31:16 2026 +0800
[Doc] update ReadMe doc in metric module (#17388)
* update ReadMe doc in metric module
* update note number
---
iotdb-core/metrics/ReadMe.md | 116 +++++++++++++++----------------------------
1 file changed, 39 insertions(+), 77 deletions(-)
diff --git a/iotdb-core/metrics/ReadMe.md b/iotdb-core/metrics/ReadMe.md
index ef07bd37524..f0eb361f0a2 100644
--- a/iotdb-core/metrics/ReadMe.md
+++ b/iotdb-core/metrics/ReadMe.md
@@ -20,30 +20,25 @@
-->
Metric Module
-- In this project, we provide interface and its implementation
+- In this project, we provide the metrics interface and its default
implementation
- metrics-interface
- metrics-core
-- In each implementation, you can use several types of reporter to report
metric
- - Jmx Reporter
+- The built-in implementation supports the following reporters
+ - JMX Reporter
- Prometheus Reporter
- IoTDB Reporter
- [1. Design](#1-design)
-- [2. Test Report](#2-test-report)
- - [2.1. Test Environment](#21-test-environment)
- - [2.2. Test Metrics](#22-test-metrics)
- - [2.3. Test parameters](#23-test-parameters)
- - [2.4. Test Result](#24-test-result)
-- [3. How to use?](#3-how-to-use)
- - [3.1. Configuration](#31-configuration)
- - [3.2. Use Guide in IoTDB Server
Module](#32-use-guide-in-iotdb-server-module)
-- [4. How to implement your own metric
framework?](#4-how-to-implement-your-own-metric-framework)
-- [5. Some docs](#5-some-docs)
+- [2. How to use?](#2-how-to-use)
+ - [2.1. Configuration](#21-configuration)
+ - [2.2. Use Guide in IoTDB Server
Module](#22-use-guide-in-iotdb-server-module)
+- [3. How to implement your own metric
framework?](#3-how-to-implement-your-own-metric-framework)
+- [4. Some docs](#4-some-docs)
# 1. Design
> The acquisition system consists of following four parts.
-1. Metrics：Provide tools for collecting metric in different scenarios,
including Counter, Gauge, Histogram, Timer and Rate, each with tags.
+1. Metrics: Provide tools for collecting metrics in different scenarios,
including Counter, AutoGauge, Gauge, Histogram, Timer and Rate, each with tags.
2. MetricManager
1. Provide functions such as create, query, update and remove metrics.
2. Provide its own start and stop methods.
@@ -57,76 +52,43 @@ Metric Module
3. Provide the ability to load metric sets.
4. Provide the access of metricManager and CompositeReporter.
-# 2. Test Report
-We implemented the monitoring framework mainly based on Micrometer, and tested
the results as follows:
+# 2. How to use?
-## 2.1. Test Environment
-1. Processor：Inter(R) Core(TM) i7-1065G7 CPU
-2. RAM: 32G
+## 2.1. Configuration
+Configure the metrics module through `iotdb-system.properties`. The main
options supported by the current code are listed below.
-## 2.2. Test Metrics
-1. We use a single thread to create counter and run the test cases. The test
metrics as follows:
- 1. memory : Memory usage in MB.
- 2. create : The time required to create, in ms.
- 3. searchInorder : The time required for the sequential query, in ms.
- 4. searchDisorder : The time required for random queries in ms.
+| properties | meaning | example |
+| --- | --- | --- |
+| `dn(cn)_metric_reporter_list` | Reporter list. The current implementation
supports `JMX`, `PROMETHEUS` and `IOTDB`. | `JMX,PROMETHEUS` |
+| `dn(cn)_metric_level` | Initial metric level. | `OFF`, `CORE`, `IMPORTANT`,
`NORMAL`, `ALL` |
+| `cn_metric_prometheus_reporter_port` | Prometheus HTTP port for ConfigNode.
| `9091` |
+| `dn_metric_prometheus_reporter_port` | Prometheus HTTP port for DataNode. |
`9092` |
-## 2.3. Test parameters
-1. metric : test metric
-2. name : The name of the test metric, unify to one length.
-3. tag : The tag of the test metric, unify to one length.
-4. metricNumberTotal：The number of metrics tested.
-5. tagSingleNumber：Number of tags of the test metric.
-6. tagTotalNumber：The number of tag pools, the default is 1000, all
-7. tags are taken out of the tag pool.
-8. searchNumber：The number of queries, the default is 1000000.
-9. loop：The number of query loops, the default is 10.
+More details, see the User Guide and the `iotdb-system.properties.template`
file.
-## 2.4. Test Result
-
-
-# 3. How to use?
-
-## 3.1. Configuration
-1. firstly, you need to set up some system property, for example:
-
-```
-System.setProperty("line.separator", "\n");
-System.setProperty("IOTDB_CONF", "metrics/core/src/test/resources");
-```
-
-2. Then, you can modify
`iotdb-datanode.properties(iotdb-confignode.properties)` as you like, some
details:
-
-| properties | meaning
| example
|
-|----------------------------------------|
--------------------------------------------------------------------------------------
| ----------------------------------- |
-| dn(cn)_enable_metric | whether enable the module
| true
|
-| dn(cn)_enable_performance_stat | Is stat performance of operation
latency | true
|
-| dn(cn)_metric_reporter_list | the list of reporter
| JMX, PROMETHEUS, IOTDB
|
-| dn(cn)_metric_level | the init level of metrics
| ALL, NORMAL, IMPORTANT,
CORE |
-| dn(cn)_metric_async_collect_period | The period of the collection of
some metrics in asynchronous way, such as tsfile size. | 5
|
-
-3. More details, see User Doc.
-
-## 3.2. Use Guide in IoTDB Server Module
-1. Now, MetricService is registered as IService in server and confignode
module, you can simple set properties: `dn(cn)_enable_metric=true` to use
metric service.
-2. In server module you can easily use these metric by
`MetricService.getInstance()`, for example:
+## 2.2. Use Guide in IoTDB Server Module
+1. `MetricService` is registered as an `IService` in both DataNode and
ConfigNode modules. Enable it with `dn(cn)_enable_metric=true`.
+2. In server-side code you can use metrics through
`MetricService.getInstance()`, for example:
```java
MetricService.getInstance().count(1, "operation_count", MetricLevel.IMPORTANT,
"name", operation.getName());
```
-# 4. How to implement your own metric framework?
-1. implement your MetricService
- 1. You need to implement `reloadProperties` to reload properties when
running.
-2. implement your MetricManager
- 1. You need to implement your metric manager to manage the creation and
deletion of your metrics
-3. implement your reporter
- 1. You need to implement jmx reporter and prometheus reporter, notice that
your jmx bean name should be unified as `org.apache.iotdb.metrics`
- 2. You need to create
`src/main/resources/META-INF/services/org.apache.iotdb.metrics.Reporter`，and
record your MetricManager class name in this file, such as
`org.apache.iotdb.metrics.core.reporter.IoTDBJmxReporter`
-4. implement your specific metric
- 1. They are counter, gauge, histogram, histogramSnapshot, rate and timer.
- 2. These metrics will be managed by your MetricManager, and reported by
your reporter.
-
-# 5. Some docs
+3. If you want to bind or remove a metric set, use `addMetricSet(IMetricSet)`
and `removeMetricSet(IMetricSet)`.
+
+# 3. How to implement your own metric framework?
+1. Implement your metric types and an `AbstractMetricManager`.
+ 1. The built-in implementation provides Counter, AutoGauge, Gauge,
Histogram, Rate and Timer.
+2. Implement your reporters.
+ 1. Implement `Reporter` for a general reporter.
+ 2. Implement `JmxReporter` if you need JMX registration. The built-in JMX
domain is `org.apache.iotdb.metrics`.
+3. Wire your implementation into the server-side metric service.
+ 1. The current `MetricService` directly loads `IoTDBMetricManager`,
`IoTDBJmxReporter`, `PrometheusReporter` and `IoTDBSessionReporter` in
`loadManager()` and `loadReporter()`.
+ 2. If you replace the default framework, update the corresponding loading
logic there.
+4. Keep service descriptor files consistent if your packaging depends on them.
+ 1.
`src/main/resources/META-INF/services/org.apache.iotdb.metrics.AbstractMetricManager`
+ 2.
`src/main/resources/META-INF/services/org.apache.iotdb.metrics.reporter.JmxReporter`
+
+# 4. Some docs
1. <a href =
"https://iotdb.apache.org/UserGuide/latest/Tools-System/Monitor-Tool.html";>Metric
Tool</a>
-2. <a href =
"https://iotdb.apache.org/zh/UserGuide/latest/Tools-System/Monitor-Tool.html";>Metric
Tool(zh)</a>
\ No newline at end of file
+2. <a href =
"https://iotdb.apache.org/zh/UserGuide/latest/Tools-System/Monitor-Tool.html";>Metric
Tool(zh)</a>
