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 c5f8a52c59b IGNITE-29035 Fixed metrics documentation: broken tables,
dead links, time units, typos (#13548)
c5f8a52c59b is described below
commit c5f8a52c59bdffebff8752ff61b65177055c8808
Author: Nikita Amelchev <[email protected]>
AuthorDate: Fri Sep 4 12:11:09 2026 +0300
IGNITE-29035 Fixed metrics documentation: broken tables, dead links, time
units, typos (#13548)
---
docs/_docs/monitoring-metrics/custom-metrics.adoc | 8 ++---
.../monitoring-metrics/new-metrics-system.adoc | 21 +++++++----
docs/_docs/monitoring-metrics/new-metrics.adoc | 42 +++++++++++-----------
docs/_docs/monitoring-metrics/system-views.adoc | 2 +-
.../_docs/perf-and-troubleshooting/sql-tuning.adoc | 2 +-
docs/_docs/persistence/change-data-capture.adoc | 4 +--
docs/_docs/tools/control-script.adoc | 6 ++--
.../processors/cache/CacheMetricsImpl.java | 4 +--
.../transactions/TransactionMetricsAdapter.java | 8 ++---
.../internal/processors/job/GridJobProcessor.java | 4 +--
10 files changed, 54 insertions(+), 47 deletions(-)
diff --git a/docs/_docs/monitoring-metrics/custom-metrics.adoc
b/docs/_docs/monitoring-metrics/custom-metrics.adoc
index a4c2eac8113..2b40fce46d5 100644
--- a/docs/_docs/monitoring-metrics/custom-metrics.adoc
+++ b/docs/_docs/monitoring-metrics/custom-metrics.adoc
@@ -25,12 +25,12 @@ link:monitoring-metrics/new-metrics-system[Metric System].
Custom Metrics are local and are bound only to the local node.
====
-== Custom metric creation.
+== Custom Metric Creation
To register a custom metric, you need to add a new
link:monitoring-metrics/new-metrics-system#registry[registry] first.
After that, metrics can be added to this registry.
-=== Custom metric registry.
+=== Custom Metric Registry
You can create custom metric registries via the `IgniteMetrics` interface
which is obtained by `Ignite.metrics()`.
@@ -40,7 +40,7 @@ You can create custom metric registries via the
`IgniteMetrics` interface which
* `void remove(String registryName)` removes the entire custom metric registry.
-=== Custom metric creation.
+=== Adding a Metric to a Registry
To register a new custom metric, use the `MetricRegistry` interface which is
obtained by `IgniteMetrics.getOrCreate(...)`.
@@ -51,7 +51,7 @@ To register a new custom metric, use the `MetricRegistry`
interface which is obt
* `void remove(String name);` removes a metric.
-== Naming convention.
+== Naming Convention
Names of the custom metrics (and its registries) are similar to the names of
internal metrics. The name can have dot-separated
parts like 'process.status.suspended'.
diff --git a/docs/_docs/monitoring-metrics/new-metrics-system.adoc
b/docs/_docs/monitoring-metrics/new-metrics-system.adoc
index 2e34bd6d299..5adcbfa25f1 100644
--- a/docs/_docs/monitoring-metrics/new-metrics-system.adoc
+++ b/docs/_docs/monitoring-metrics/new-metrics-system.adoc
@@ -15,6 +15,7 @@
= Metrics System
:javaFile: {javaCodeDir}/ConfiguringMetrics.java
+:table_opts: cols="2,1,4,1",opts="header"
== Overview
@@ -228,9 +229,10 @@ Configuration parameters:
== Histograms
-The metrics that represent histograms are available in the JMX exporter only.
-Histogram metrics are exported as a set of values where each value corresponds
to a specific bucket and is available through a separate JMX bean attribute.
-The attribute names of a histogram metric have the following format:
+Histogram metrics are available through every exporter, but the format differs.
+
+The JMX exporter, the OpenCensus exporter, and the `control.sh --metric`
command expose each bucket as a separate value.
+The names of the buckets have the following format:
```
{metric_name}_{low_bound}_{high_bound}
@@ -243,13 +245,18 @@ where
* `{high_bound}` - end of the bound. `inf` for the last bound.
-Example of the metric names if the bounds are [10,100]:
+Example of the bucket names if the bounds are [10,100]:
* `histogram_0_10` - less than 10.
* `histogram_10_100` - between 10 and 100.
* `histogram_100_inf` - more than 100.
-== Common monitoring tasks
+The `SYS.METRICS` system view and the log exporter report the whole histogram
as a single value: an array of bucket
+counters, for example `[3, 15, 2]`. Bucket bounds are not exposed there yet,
so to see them read the same metric through
+JMX, the OpenCensus exporter, or `control.sh --metric`, where every bucket
name carries its bounds.
+
+
+== Common Monitoring Tasks
=== Monitoring the Amount of Data
If you do not use link:persistence/native-persistence[Native persistence]
(i.e., all your data is kept in memory), you would want to monitor RAM usage.
@@ -317,7 +324,7 @@ To monitor the size of the persistent storage on disk, use
the following metrics
===== Data Region Size
-For each configured data region, Metrics collection for data regions are
disabled by default. You can
link:monitoring-metrics/configuring-metrics#enabling-data-region-metrics[enable
it in the data region configuration.
+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].
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.
@@ -381,7 +388,7 @@ Topology refers to the set of nodes in a cluster. There are
a number of metrics
| Attribute | Type | Description | Scope
| TotalServerNodes| long |The number of server nodes in the cluster.| Global
| TotalClientNodes| long |The number of client nodes in the cluster. | Global
-| TotalBaselineNodes | long | 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 remote it manually.
| Global
+| TotalBaselineNodes | long | 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.
| Global
| ActiveBaselineNodes | long | The number of nodes that are currently active
in the baseline topology. | Global
|===
diff --git a/docs/_docs/monitoring-metrics/new-metrics.adoc
b/docs/_docs/monitoring-metrics/new-metrics.adoc
index 23ce5e1a9e9..b07cb629b4c 100644
--- a/docs/_docs/monitoring-metrics/new-metrics.adoc
+++ b/docs/_docs/monitoring-metrics/new-metrics.adoc
@@ -73,8 +73,8 @@ Register name: `cache.{cache_name}.{near}`
|ConflictResolverMergedCount|long|Conflict resolver merged entries count.
|EntryProcessorHits | long|The total number of invocations on keys, which
exist in cache.
|EntryProcessorInvokeTimeNanos | long | The total time of cache invocations
for which this node is the initiator, in nanoseconds.
-|EntryProcessorMaxInvocationTime |long | So far, the maximum time to execute
cache invokes for which this node is the initiator.
-|EntryProcessorMinInvocationTime |long | So far, the minimum time to execute
cache invokes for which this node is the initiator.
+|EntryProcessorMaxInvocationTime |long | So far, the maximum time to execute
cache invokes for which this node is the initiator, in nanoseconds.
+|EntryProcessorMinInvocationTime |long | So far, the minimum time to execute
cache invokes for which this node is the initiator, in nanoseconds.
|EntryProcessorMisses |long|The total number of invocations on keys, which
don't exist in cache.
|EntryProcessorPuts |long|The total number of cache invocations, caused
update.
|EntryProcessorReadOnlyInvocations |long|The total number of cache
invocations, caused no updates.
@@ -104,9 +104,9 @@ Register name: `cache.{cache_name}.{near}`
|QueryCompleted |long|Count of completed queries.
|QueryExecuted |long|Count of executed queries.
|QueryFailed |long|Count of failed queries.
-|QueryMaximumTime |long| Maximum query execution time.
-|QueryMinimalTime |long| Minimum query execution time.
-|QuerySumTime |long| Query summary time.
+|QueryMaximumTime |long| Maximum query execution time, in milliseconds.
+|QueryMinimalTime |long| Minimum query execution time, in milliseconds.
+|QuerySumTime |long| Query summary time, in milliseconds.
|RebalanceClearingPartitionsLeft |long| Number of partitions need to be
cleared before actual rebalance start.
|RebalanceStartTime |long| Rebalance start time.
|RebalancedKeys |long| Number of already rebalanced keys.
@@ -114,7 +114,7 @@ Register name: `cache.{cache_name}.{near}`
|RebalancingKeysRate |long|Estimated rebalancing speed in keys.
|RemoveAllConflictTime | histogram | RemoveAllConflict time for which this
node is the initiator, in nanoseconds.
|RemoveAllTime | histogram | RemoveAll time for which this node is the
initiator, in nanoseconds.
-|RemoveTime | histogram | Remove time for which this node is the initiator. in
nanoseconds.
+|RemoveTime | histogram | Remove time for which this node is the initiator, in
nanoseconds.
|RemoveTimeTotal | long | The total time of cache removal, in nanoseconds.
|RollbackTime|histogram| Rollback time in nanoseconds.
|RollbackTimeTotal |long|The total time of rollback, in nanoseconds.
@@ -164,11 +164,11 @@ Register name: `tx`
|OwnerTransactionsNumber |long| The number of active transactions for which
this node is the initiator.
|TransactionsHoldingLockNumber | long| The number of active transactions
holding at least one key lock.
|LastCommitTime |long| Last commit time.
-|nodeSystemTimeHistogram| histogram| Transactions system times on node
represented as histogram.
-|nodeUserTimeHistogram| histogram| Transactions user times on node
represented as histogram.
+|nodeSystemTimeHistogram| histogram| Transactions system times on node
represented as histogram, in milliseconds.
+|nodeUserTimeHistogram| histogram| Transactions user times on node
represented as histogram, in milliseconds.
|LastRollbackTime| long| Last rollback time.
-|totalNodeSystemTime |long| Total transactions system time on node.
-|totalNodeUserTime |long| Total transactions user time on node.
+|totalNodeSystemTime |long| Total transactions system time on node, in
milliseconds.
+|totalNodeUserTime |long| Total transactions user time on node, in
milliseconds.
|txCommits |integer| Number of transaction commits.
|txRollbacks |integer| Number of transaction rollbacks.
|txDeadlocks |integer| Number of transaction deadlocks.
@@ -200,12 +200,12 @@ Register name: `compute.jobs`
|Name| Type| Description
|compute.jobs.Active |long| Number of active jobs currently executing.
|compute.jobs.Canceled |long| Number of cancelled jobs that are still
running.
-|compute.jobs.ExecutionTime |long| Total execution time of jobs.
+|compute.jobs.ExecutionTime |long| Total execution time of jobs, in
milliseconds.
|compute.jobs.Finished |long| Number of finished jobs.
|compute.jobs.Rejected |long| Number of jobs rejected after more recent
collision resolution operation.
|compute.jobs.Started |long| Number of started jobs.
|compute.jobs.Waiting |long| Number of currently queued jobs waiting to be
executed.
-|compute.jobs.WaitingTime |long| Total time jobs spent on waiting queue.
+|compute.jobs.WaitingTime |long| Total time jobs spent on waiting queue, in
milliseconds.
|===
== Thread Pools
@@ -251,7 +251,7 @@ Register name: `io.statistics.cacheGroups.{group_name}`
|===
-== Sorted Indexes I/O statistics
+== Sorted Indexes I/O Statistics
Register name: `io.statistics.sortedIndexes.{cache_name}.{index_name}`
@@ -267,7 +267,7 @@ Register name:
`io.statistics.sortedIndexes.{cache_name}.{index_name}`
|startTime| long| Statistics collection start time
|===
-== Sorted Indexes operations
+== Sorted Indexes Operations
Contains metrics about low-level operations (such as `Insert`, `Search`, etc.)
on pages of sorted secondary indexes.
@@ -281,7 +281,7 @@ Register name:
`index.{schema_name}.{table_name}.{index_name}`
|===
-== Hash Indexes I/O statistics
+== Hash Indexes I/O Statistics
Register name: `io.statistics.hashIndexes.{cache_name}.{index_name}`
@@ -398,7 +398,7 @@ Register name: `io.dataregion.{data_region_name}`
|EmptyDataPages| long| Calculates empty data pages count for region. It
counts only totally free pages that can be reused (e. g. pages that are
contained in reuse bucket of free list).
|EvictionRate| hitrate| Eviction rate (pages per second).
|EvictionsStarted | boolean | True if page eviction was triggered due to
data region memory pressure.
-|LargeEntriesPagesCount| long| Count of pages that fully ocupied by large
entries that go beyond page size
+|LargeEntriesPagesCount| long| Count of pages that fully occupied by large
entries that go beyond page size
|OffHeapSize| long| Offheap size in bytes.
|OffheapUsedSize| long| Offheap used size in bytes.
|PagesFillFactor| double| The average amount of data in non-empty pages as a
ratio of the page size.
@@ -437,7 +437,7 @@ Register name: `io.datastorage`
|CheckpointPagesWriteHistogram| histogram | Histogram of checkpoint pages
write duration in milliseconds.
|CheckpointSplitAndSortPagesHistogram| histogram | Histogram of splitting
and sorting checkpoint pages duration in milliseconds.
|CheckpointTotalTime| long | Total duration of checkpoint
-|CheckpointWalRecordFsyncHistogram| histogram | Histogram of the WAL fsync
after logging ChTotalNodeseckpointRecord on begin of checkpoint duration in
milliseconds.
+|CheckpointWalRecordFsyncHistogram| histogram | Histogram of the WAL fsync
after logging CheckpointRecord on begin of checkpoint duration in milliseconds.
|CheckpointWriteEntryHistogram| histogram | Histogram of entry buffer
writing to file duration in milliseconds.
|LastArchivedSegment | long | Last archived segment index.
|LastCheckpointBeforeLockDuration| long | Duration of the checkpoint action
before taken write lock in milliseconds.
@@ -485,7 +485,7 @@ Register name: `cluster`
|TotalServerNodes| integer | Server nodes count.
|===
-== Cache processor
+== Cache Processor
Cache processor metrics.
@@ -499,7 +499,7 @@ Register name: `cache`
|DataVersionClusterId| integer | Data version cluster id.
|===
-== SQL parser metrics
+== SQL Parser Metrics
Register name: `sql.parser.cache`
@@ -510,14 +510,14 @@ Register name: `sql.parser.cache`
|misses| long | The number of SQL queries that were parsed and planned.
|===
-== SQL executor metrics
+== SQL Executor Metrics
Register name: `sql.queries.user`
[cols="2,1,3",opts="header"]
|===
|Name| Type| Description
-|success| long | The number of succesfully executed SQL queries.
+|success| long | The number of successfully executed SQL queries.
|failed| long | The number of failed SQL queries (including canceled).
|canceled| long | The number of canceled SQL queries.
|resultSetSizeHistogram| histogram | Histogram of fetched result set sizes for
SQL queries.
diff --git a/docs/_docs/monitoring-metrics/system-views.adoc
b/docs/_docs/monitoring-metrics/system-views.adoc
index 4edf9e574da..d04dc0be9a3 100644
--- a/docs/_docs/monitoring-metrics/system-views.adoc
+++ b/docs/_docs/monitoring-metrics/system-views.adoc
@@ -249,11 +249,11 @@ methods. The parameter is empty, if you use
`IgniteCompute` APIs that don't targ
[{table_opts}]
|===
+| Column | Type | Description
|AFFINITY_KEY | string | Affinity key value for service
|CACHE_NAME | string | Cache name
|MAX_PER_NODE_COUNT | int | Maximum count of services instances per node
|NAME | string | Service name
-|NAME | TYPE | DESCRIPTION
|NODE_FILTER | string | String representation of node filter
|ORIGIN_NODE_ID | UUID | Originating node ID
|SERVICE_CLASS | string | Service class name
diff --git a/docs/_docs/perf-and-troubleshooting/sql-tuning.adoc
b/docs/_docs/perf-and-troubleshooting/sql-tuning.adoc
index 1a96bbb9a20..fac862025f5 100644
--- a/docs/_docs/perf-and-troubleshooting/sql-tuning.adoc
+++ b/docs/_docs/perf-and-troubleshooting/sql-tuning.adoc
@@ -326,7 +326,7 @@ Note that you will only have to set the inline size for the
index on `stringFiel
Refer to the link:SQL/indexes#configuring-index-inline-size[Configuring Index
Inline Size] section for the information on how to change the inline size.
-You can check the inline size of an existing index in the
link:monitoring-metrics/system-views#indexes-view[INDEXES] system view.
+You can check the inline size of an existing index in the
link:monitoring-metrics/system-views#indexes[INDEXES] system view.
[WARNING]
====
diff --git a/docs/_docs/persistence/change-data-capture.adoc
b/docs/_docs/persistence/change-data-capture.adoc
index 40df4755615..589fc9e95ce 100644
--- a/docs/_docs/persistence/change-data-capture.adoc
+++ b/docs/_docs/persistence/change-data-capture.adoc
@@ -68,7 +68,7 @@ CDC is configured in the same way as the Ignite node - via
the spring XML file:
| `checkFrequency` | Amount of time application sleeps between subsequent
checks when no new files available. | 1000 milliseconds.
| `keepBinary` | Flag to specify if key and value of changed entries should be
provided in link:key-value-api/binary-objects[binary format]. | `true`
| `consumer` | Implementation of `org.apache.ignite.cdc.CdcConsumer` that
consumes entries changes. | null
-| `metricExporterSpi` | Array of SPI's to export CDC metrics. See
link:monitoring-metrics/new-metrics-system#_metric_exporters[metrics]
documentation, also. | null
+| `metricExporterSpi` | Array of SPI's to export CDC metrics. See
link:monitoring-metrics/new-metrics-system#metric-exporters[metrics]
documentation, also. | null
|===
=== Distributed properties
@@ -93,7 +93,7 @@ Below is a single change of the data reflected by `CdcEvent`.
|Name |Description
| `key()` | Key for the changed entry.
| `value()` | Value for the changed entry. This method will return `null` if
the event reflects removal.
-| `cacheId()` | ID of the cache where the change happens. The value is equal
to the `CACHE_ID` from
link:monitoring-metrics/system-views#_CACHES[`SYS.CACHES`].
+| `cacheId()` | ID of the cache where the change happens. The value is equal
to the `CACHE_ID` from
link:monitoring-metrics/system-views#caches[`SYS.CACHES`].
| `partition()` | Partition of the changed entry.
| `primary()` | Flag to distinguish if operation happens on the primary or a
backup node.
| `version()` | `Comparable` version of the changed entry. Internally, Ignite
maintains ordered versions of each entry so any changes of the same entry can
be sorted.
diff --git a/docs/_docs/tools/control-script.adoc
b/docs/_docs/tools/control-script.adoc
index edc87dfa66d..f4ba2195553 100644
--- a/docs/_docs/tools/control-script.adoc
+++ b/docs/_docs/tools/control-script.adoc
@@ -1053,9 +1053,9 @@ control.bat --metric sys
Example of the metric output:
[source, text]
-control.sh --metric sysCurrentThreadCpuTime
+control.sh --metric sys.CurrentThreadCpuTime
Command [METRIC] started
-Arguments: --metric sys
+Arguments: --metric sys.CurrentThreadCpuTime
--------------------------------------------------------------------------------
metric value
sys.CurrentThreadCpuTime 17270000
@@ -1066,7 +1066,7 @@ Example of the metric registry output:
[source, text]
control.sh --metric io.dataregion.default
Command [METRIC] started
-Arguments: --metric sys
+Arguments: --metric io.dataregion.default
--------------------------------------------------------------------------------
metric value
io.dataregion.default.TotalAllocatedSize 0
diff --git
a/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/CacheMetricsImpl.java
b/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/CacheMetricsImpl.java
index b483dd64904..20f566a0733 100644
---
a/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/CacheMetricsImpl.java
+++
b/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/CacheMetricsImpl.java
@@ -305,10 +305,10 @@ public class CacheMetricsImpl implements CacheMetrics {
"The total time of cache invocations for which this node is the
initiator, in nanoseconds.");
entryProcessorMinInvocationTime =
mreg.longMetric("EntryProcessorMinInvocationTime",
- "So far, the minimum time to execute cache invokes for which this
node is the initiator.");
+ "So far, the minimum time to execute cache invokes for which this
node is the initiator, in nanoseconds.");
entryProcessorMaxInvocationTime =
mreg.longMetric("EntryProcessorMaxInvocationTime",
- "So far, the maximum time to execute cache invokes for which this
node is the initiator.");
+ "So far, the maximum time to execute cache invokes for which this
node is the initiator, in nanoseconds.");
entryProcessorHits = mreg.longMetric("EntryProcessorHits",
"The total number of invocations on keys, which exist in cache.");
diff --git
a/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/transactions/TransactionMetricsAdapter.java
b/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/transactions/TransactionMetricsAdapter.java
index d5cd833179e..aa004505409 100644
---
a/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/transactions/TransactionMetricsAdapter.java
+++
b/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/transactions/TransactionMetricsAdapter.java
@@ -110,19 +110,19 @@ public class TransactionMetricsAdapter implements
TransactionMetrics {
txDeadlocks = mreg.intMetric("txDeadlocks", "Number of transaction
deadlocks.");
commitTime = mreg.longMetric("commitTime", "Last commit time.");
rollbackTime = mreg.longMetric("rollbackTime", "Last rollback time.");
- totalTxSystemTime = mreg.longAdderMetric(METRIC_TOTAL_SYSTEM_TIME,
"Total transactions system time on node.");
- totalTxUserTime = mreg.longAdderMetric(METRIC_TOTAL_USER_TIME, "Total
transactions user time on node.");
+ totalTxSystemTime = mreg.longAdderMetric(METRIC_TOTAL_SYSTEM_TIME,
"Total transactions system time on node, in milliseconds.");
+ totalTxUserTime = mreg.longAdderMetric(METRIC_TOTAL_USER_TIME, "Total
transactions user time on node, in milliseconds.");
txSystemTimeHistogram = mreg.histogram(
METRIC_SYSTEM_TIME_HISTOGRAM,
METRIC_TIME_BUCKETS,
- "Transactions system times on node represented as histogram."
+ "Transactions system times on node represented as histogram, in
milliseconds."
);
txUserTimeHistogram = mreg.histogram(
METRIC_USER_TIME_HISTOGRAM,
METRIC_TIME_BUCKETS,
- "Transactions user times on node represented as histogram."
+ "Transactions user times on node represented as histogram, in
milliseconds."
);
}
diff --git
a/modules/core/src/main/java/org/apache/ignite/internal/processors/job/GridJobProcessor.java
b/modules/core/src/main/java/org/apache/ignite/internal/processors/job/GridJobProcessor.java
index 0276827b6cc..127814406bd 100644
---
a/modules/core/src/main/java/org/apache/ignite/internal/processors/job/GridJobProcessor.java
+++
b/modules/core/src/main/java/org/apache/ignite/internal/processors/job/GridJobProcessor.java
@@ -376,9 +376,9 @@ public class GridJobProcessor extends GridProcessorAdapter {
finishedJobsMetric = mreg.longMetric(FINISHED, "Number of finished
jobs.");
- totalExecutionTimeMetric = mreg.longMetric(EXECUTION_TIME, "Total
execution time of jobs.");
+ totalExecutionTimeMetric = mreg.longMetric(EXECUTION_TIME, "Total
execution time of jobs, in milliseconds.");
- totalWaitTimeMetric = mreg.longMetric(WAITING_TIME, "Total time jobs
spent on waiting queue.");
+ totalWaitTimeMetric = mreg.longMetric(WAITING_TIME, "Total time jobs
spent on waiting queue, in milliseconds.");
ctx.systemView().registerInnerCollectionView(JOBS_VIEW, JOBS_VIEW_DESC,
new ComputeJobViewWalker(),
