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

NSAmelchev pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git


The following commit(s) were added to refs/heads/master by this push:
     new 95b5af8e362 IGNITE-29218 Fix outdated statements in the metrics 
documentation (#13757)
95b5af8e362 is described below

commit 95b5af8e362a0e6c11f23d3dff313f61e1e08fe9
Author: Nikita Amelchev <[email protected]>
AuthorDate: Mon Nov 2 10:03:10 2026 +0300

    IGNITE-29218 Fix outdated statements in the metrics documentation (#13757)
---
 .../code-snippets/xml/configuring-metrics.xml      |   4 +-
 .../code-snippets/xml/persistence-metrics.xml      |   2 +-
 docs/_docs/images/jconsole.png                     | Bin 97939 -> 128291 bytes
 .../monitoring-metrics/configuring-metrics.adoc    |  17 +++--
 .../monitoring-metrics/new-metrics-system.adoc     |  76 +++++++++++++++------
 5 files changed, 66 insertions(+), 33 deletions(-)

diff --git a/docs/_docs/code-snippets/xml/configuring-metrics.xml 
b/docs/_docs/code-snippets/xml/configuring-metrics.xml
index 2199a000562..4653cb419ed 100644
--- a/docs/_docs/code-snippets/xml/configuring-metrics.xml
+++ b/docs/_docs/code-snippets/xml/configuring-metrics.xml
@@ -28,7 +28,7 @@
                 <!-- tag::data-region-metrics[] -->
                 <property name="defaultDataRegionConfiguration">
                     <bean 
class="org.apache.ignite.configuration.DataRegionConfiguration">
-                        <!-- enable mertrics for the default data region -->
+                        <!-- enable metrics for the default data region -->
                         <property name="metricsEnabled" value="true"/>
                         <!-- other properties -->
                     </bean>
@@ -40,8 +40,6 @@
                             <property name="name" value="myDataRegion"/>
                             <!-- Enable metrics for this data region  -->
                             <property name="metricsEnabled" value="true"/>
-
-                            <property name="persistenceEnabled" value="true"/>
                             <!-- other properties -->
                         </bean>
                     </list>
diff --git a/docs/_docs/code-snippets/xml/persistence-metrics.xml 
b/docs/_docs/code-snippets/xml/persistence-metrics.xml
index 52e12b94878..4cd4eb4fac8 100644
--- a/docs/_docs/code-snippets/xml/persistence-metrics.xml
+++ b/docs/_docs/code-snippets/xml/persistence-metrics.xml
@@ -28,7 +28,7 @@
                     <bean 
class="org.apache.ignite.configuration.DataRegionConfiguration">
                         <property name="persistenceEnabled" value="true"/>
 
-                        <!-- enable mertrics for the default data region -->
+                        <!-- enable metrics for the default data region -->
                         <!--property name="metricsEnabled" value="true"/-->
                         <!-- other properties -->
                     </bean>
diff --git a/docs/_docs/images/jconsole.png b/docs/_docs/images/jconsole.png
index 120a309f8e2..a93cc6ff821 100644
Binary files a/docs/_docs/images/jconsole.png and 
b/docs/_docs/images/jconsole.png differ
diff --git a/docs/_docs/monitoring-metrics/configuring-metrics.adoc 
b/docs/_docs/monitoring-metrics/configuring-metrics.adoc
index 8ccad23104d..a9b04971913 100644
--- a/docs/_docs/monitoring-metrics/configuring-metrics.adoc
+++ b/docs/_docs/monitoring-metrics/configuring-metrics.adoc
@@ -28,6 +28,8 @@ For this reason, some metrics are disabled by default.
 Cache metrics show statistics on the amount of data stored in caches, the 
total number and frequency of cache operations, etc. as well as some cache 
configuration properties for information purposes.
 
 To enable cache metrics, use one of the methods described below for each cache 
you want to monitor.
+Cache metrics can also be enabled or disabled at runtime, without restarting 
the nodes, via
+`IgniteCluster.enableStatistics(...)` or the 
link:tools/control-script#manage-cache-metrics-collection[control script].
 
 [tabs]
 --
@@ -51,12 +53,10 @@ tab:C++[unsupported]
 
 == Enabling Data Region Metrics
 Data region metrics expose information about data regions, including memory 
and storage size of the region.
-Enable data region metrics for every region you want to collect the metrics 
for.
-
-Data region metrics can be enabled in two ways:
-
-* in the link:memory-configuration/data-regions[configuration of the region]
-* via JMX Beans
+Enable data region metrics in the 
link:memory-configuration/data-regions[configuration of the region] for every 
region
+you want to collect the metrics for.
+The setting is read at node startup and cannot be changed at runtime.
+Some metrics, such as `TotalAllocatedSize`, are collected regardless of it.
 
 The following example illustrates how to enable metrics for the default data 
region and one custom data region.
 
@@ -81,7 +81,10 @@ tab:C++[unsupported]
 --
 
 == Enabling Persistence-related Metrics
-Persistence-related metrics can be enabled/disabled in the data storage 
configuration:
+The `io.datastorage` register (WAL, checkpoint and storage size metrics) is 
collected only when persistence metrics are
+enabled in the data storage configuration; otherwise its metrics report zero, 
except `LastArchivedSegment`, which
+reports `-1`.
+The property is deprecated but still required; it is read at node startup and 
cannot be changed at runtime.
 
 [tabs]
 --
diff --git a/docs/_docs/monitoring-metrics/new-metrics-system.adoc 
b/docs/_docs/monitoring-metrics/new-metrics-system.adoc
index 094400c9f5b..97e18a2d2f2 100644
--- a/docs/_docs/monitoring-metrics/new-metrics-system.adoc
+++ b/docs/_docs/monitoring-metrics/new-metrics-system.adoc
@@ -29,7 +29,7 @@ Some metrics represent <<histograms>>.
 
 And then there are different ways to export the metrics — what we call 
_exporters_.
 To put it another way, the exporter are different ways you can access the 
metrics.
-Each exporter always gives access to all available metrics.
+Unless an export filter is configured, each exporter gives access to all 
available metrics.
 
 Ignite includes the following exporters:
 
@@ -52,15 +52,17 @@ The list of all registries and the metrics they contain are 
described link:monit
 
 == Metric Exporters
 
-If you want to enable metrics, configure one or multiple metric exporters in 
the node configuration.
-This is a node-specific configuration, which means it enables metrics only on 
the node where it is specified.
+Metrics are collected regardless of the exporters configured; exporters only 
define how the metrics are exposed.
+By default, a node registers the JMX exporter and, if an SQL engine module is 
on the classpath, the `SYS.METRICS` view.
+To change the set of exporters, configure them in the node configuration.
+This is a node-specific configuration, which means it affects only the node 
where it is specified.
 
 [tabs]
 --
 tab:XML[]
 [source, xml]
 ----
-include::code-snippets/xml/metrics.xml[tags=ignite-config;!discovery, indent=0]
+include::code-snippets/xml/metrics.xml[tags=ignite-config;!discovery;!opencensus-exporter,
 indent=0]
 ----
 
 tab:Java[]
@@ -112,19 +114,18 @@ tab:C#/.NET[]
 tab:C++[unsupported]
 --
 
-==== Enabling JMX for Ignite
-
-By default, the JMX automatic configuration is disabled.
-To enable it, configure the following environment variables:
-
-* For `control.sh`, configure the `CONTROL_JVM_OPTS` variable
-* For `ignite.sh`, configure the `JVM_OPTS` variable
+==== Enabling Remote JMX Access
 
+Ignite registers its MBeans in the platform MBean server of the node process, 
so a local JMX client, such as JConsole
+running on the same host, needs no additional configuration.
+To connect from another host, enable remote JMX with the standard JVM options.
+For `ignite.sh`, add them to the `JVM_OPTS` environment variable; for a node 
embedded into an application, pass them to
+the JVM of the application.
 For example:
 
 [source,shell]
 ----
-JVM_OPTS="-Dcom.sun.management.jmxremote 
-Dcom.sun.management.jmxremote.port=${JMX_PORT} \
+export JVM_OPTS="$JVM_OPTS -Dcom.sun.management.jmxremote 
-Dcom.sun.management.jmxremote.port=<port> \
 -Dcom.sun.management.jmxremote.authenticate=false 
-Dcom.sun.management.jmxremote.ssl=false"
 ----
 
@@ -138,15 +139,24 @@ The ObjectName consists of a domain and a list of key 
properties, and can be rep
 
    domain: key1 = value1 , key2 = value2
 
-All Ignite metrics have the same domain: `org.apache.<classloaderId>` where 
the classloader ID is optional (omitted if you set 
`IGNITE_MBEAN_APPEND_CLASS_LOADER_ID=false`). In addition, each metric has two 
properties: `group` and `name`.
-For example:
+All Ignite MBeans have the same domain: `org.apache`. The key properties are:
 
-    org.apache:group=SPIs,name=TcpDiscoverySpi
+* `clsLdr` - the hash code of the class loader that loaded Ignite, as a hex 
string. Present by default; omitted if you
+set the `IGNITE_MBEAN_APPEND_CLASS_LOADER_ID` system property to `false`.
+* `jvmId` - the name of the JVM (`<pid>@<host>`). Present only if the 
`IGNITE_MBEAN_APPEND_JVM_ID` system property is
+set to `true`.
+* `igniteInstanceName` - the instance name of the node. Present only if the 
node has one.
+* `group` and `name` - for a metric register, `group` is the part of the 
register name before the first dot and `name`
+is the rest. Registers without a dot in the name, such as `tx`, have no 
`group` property.
 
-This MBean provides various metrics related to node discovery.
+For example, the `io.discovery` and `tx` registers are exposed as:
+
+    org.apache:clsLdr=5ffd2b27,group=io,name=discovery
+    org.apache:clsLdr=5ffd2b27,name=tx
 
 The MBean ObjectName can be used to identify the bean in UI tools like 
JConsole.
-For example, JConsole displays MBeans in a tree-like structure where all beans 
are first grouped by domain and then by the 'group' property:
+For example, JConsole displays MBeans in a tree-like structure where beans are 
grouped by domain and then by the key
+properties in the order listed above:
 
 image::images/jconsole.png[]
 
@@ -154,7 +164,9 @@ image::images/jconsole.png[]
 
 === SQL View
 
-`SqlViewMetricExporterSpi` is enabled by default, `SqlViewMetricExporterSpi` 
exposes metrics via the `SYS.METRICS` view.
+The `SYS.METRICS` view is registered automatically on every node that has an 
SQL engine module (`ignite-indexing` or
+`ignite-calcite`) on the classpath.
+It does not need to be configured and cannot be filtered.
 Each metric is displayed as a single record.
 You can use any supported SQL tool to view the metrics:
 
@@ -304,9 +316,19 @@ To monitor the size of the persistent storage on disk, use 
the following metrics
 
 The metrics belong to the `io.datastorage` register, see 
link:monitoring-metrics/new-metrics#data-storage[Data Storage].
 
+[NOTE]
+====
+The `io.datastorage` register is collected only when persistence metrics are 
enabled in the
+link:monitoring-metrics/configuring-metrics#enabling-persistence-related-metrics[data
 storage configuration]; otherwise
+its metrics report zero, except `LastArchivedSegment`, which reports `-1`.
+====
+
 ===== Data Region Size
 
-Metrics collection for data regions is disabled by default. You can 
link:monitoring-metrics/configuring-metrics#enabling-data-region-metrics[enable 
it in the data region configuration].
+`PagesFillFactor` requires data region metrics to be enabled in the
+link:monitoring-metrics/configuring-metrics#enabling-data-region-metrics[data 
region configuration], and so do
+`PhysicalMemoryPages` and `PhysicalMemorySize` for regions with persistence 
enabled; the other metrics listed below are
+always collected.
 
 The size of the data region on a node comprises the size of all partitions 
(including backup partitions) that this node owns for all caches in that data 
region.
 
@@ -338,7 +360,11 @@ See 
link:persistence/persistence-tuning#pages-writes-throttling[Pages Writes Thr
 * `LastCheckpointDuration` - The time in milliseconds it took to create the 
last checkpoint.
 * `CheckpointBufferSize` - The size of the checkpointing buffer.
 
-The metrics belong to the `io.datastorage` register, see 
link:monitoring-metrics/new-metrics#data-storage[Data Storage].
+The metrics belong to the `io.datastorage` register, see 
link:monitoring-metrics/new-metrics#data-storage[Data Storage];
+they require persistence metrics to be enabled in the
+link:monitoring-metrics/configuring-metrics#enabling-persistence-related-metrics[data
 storage configuration].
+`DirtyPages` and `CheckpointBufferSize` are summed over data regions, so they 
also require
+link:monitoring-metrics/configuring-metrics#enabling-data-region-metrics[data 
region metrics] to be enabled.
 
 === Monitoring Rebalancing
 link:data-rebalancing[Rebalancing] is the process of moving partitions between 
the cluster nodes so that the data is always distributed in a balanced manner. 
Rebalancing is triggered when a new node joins, or an existing node leaves the 
cluster.
@@ -355,7 +381,11 @@ Topology refers to the set of nodes in a cluster. There 
are a number of metrics
 
 * `TotalServerNodes` - The number of server nodes in the cluster.
 * `TotalClientNodes` - The number of client nodes in the cluster.
-* `TotalBaselineNodes` - The number of nodes that are registered in the 
link:clustering/baseline-topology[baseline topology]. When a node goes down, it 
remains registered in the baseline topology and you need to remove it manually.
+* `TotalBaselineNodes` - The number of nodes that are registered in the
+link:clustering/baseline-topology[baseline topology]. When a node goes down, 
it remains registered in the baseline
+topology and you need to remove it manually, unless
+link:clustering/baseline-topology#baseline-topology-autoadjustment[baseline 
topology autoadjustment] is enabled (the
+default for in-memory clusters).
 * `ActiveBaselineNodes` - The number of nodes that are currently active in the 
baseline topology.
 
 The metrics belong to the `cluster` register, see 
link:monitoring-metrics/new-metrics#cluster[Cluster].
@@ -392,7 +422,9 @@ For a more accurate estimate, use the 
`IndexRebuildKeyProcessed` cache metric:
 * Use `IndexRebuildKeyProcessed` to know the number of keys with rebuilt 
indexes. If the rebuilding is in progress, it gives a number of keys with 
indexes being rebuilt at the current moment. Otherwise, it gives a total number 
of the of keys with rebuilt indexes. The values are reset before the start of 
each rebuilding.
 
 === Monitoring Transactions
-Note that if a transaction spans multiple nodes (i.e., if the keys that are 
changed as a result of the transaction execution are located on multiple 
nodes), the counters will increase on each node. For example, the 
'TransactionsCommittedNumber' counter will increase on each node where the keys 
affected by the transaction are stored.
+The commit and rollback counters are updated only on the node that started the 
transaction, no matter how many nodes
+store the affected keys, so the sum of `txCommits` over all nodes, including 
client nodes, is the number of
+transactions committed in the cluster.
 
 * `LockedKeysNumber` - The number of keys locked on the node.
 * `TransactionsCommittedNumber` - The number of transactions that have been 
committed on the node. Exposed as `txCommits` in the `tx` register.

Reply via email to