Skip to content

[Doc] update ReadMe doc in metric module #17388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SpriCoder merged 2 commits into from
Mar 29, 2026
Merged

[Doc] update ReadMe doc in metric module #17388

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
df3ff26
update ReadMe doc in metric module
SpriCoder Mar 29, 2026
33794ae
update note number
SpriCoder Mar 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 39 additions & 77 deletions iotdb-core/metrics/ReadMe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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` |

Copilot AI Mar 29, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the configuration table, the example column for dn(cn)_metric_level lists all possible values rather than an example value. Consider moving the allowed values into the meaning column (or an Options: note) and using a single representative example (e.g., IMPORTANT).

Suggested change
| `dn(cn)_metric_level` | Initial metric level. | `OFF`, `CORE`, `IMPORTANT`, `NORMAL`, `ALL` |
| `dn(cn)_metric_level` | Initial metric level. Options: `OFF`, `CORE`, `IMPORTANT`, `NORMAL`, `ALL`. | `IMPORTANT` |

Copilot uses AI. Check for mistakes.
| `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.

Copilot AI Mar 29, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This README says the reporter list supports IOTDB and then points readers to iotdb-system.properties.template for more details, but the current template only documents [JMX, PROMETHEUS] and doesn’t list the IoTDB reporter config keys. Either adjust the wording here (so it’s clear the template is incomplete/outdated) or update the template in a follow-up to avoid confusing users.

Suggested change
More details, see the User Guide and the `iotdb-system.properties.template` file.
For more details, see the User Guide. Note that the `iotdb-system.properties.template` file currently documents configuration for JMX and Prometheus reporters; IoTDB reporter configuration keys may not yet be listed there.

Copilot uses AI. Check for mistakes.

## 2.4. Test Result
![](https://cwiki.apache.org/confluence/download/attachments/184617400/image2021-7-14_16-32-55.png?version=1&modificationDate=1626403814000&api=v2)

# 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`.

Copilot AI Mar 29, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dn(cn)_enable_metric is documented as the switch to enable MetricService, but the server starts and registers MetricService unconditionally (e.g., DataNode/ConfigNode setUpMetricService()), and there’s no corresponding config key in MetricConfigDescriptor/iotdb-system.properties.template. Please update this section to reflect the real way to disable metrics (e.g., set dn/cn_metric_level=OFF and/or leave *_metric_reporter_list empty) or document the actual controlling config if it exists elsewhere.

Suggested change
1. `MetricService` is registered as an `IService` in both DataNode and ConfigNode modules. Enable it with `dn(cn)_enable_metric=true`.
1. `MetricService` is registered as an `IService` in both DataNode and ConfigNode modules and is started unconditionally. To effectively disable metrics output, set `dn(cn)_metric_level=OFF` and/or leave `dn(cn)_metric_reporter_list` empty.

Copilot uses AI. Check for mistakes.
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>
2. <a href = "https://iotdb.apache.org/zh/UserGuide/latest/Tools-System/Monitor-Tool.html">Metric Tool(zh)</a>
Loading