IGNITE-29039 Fix metrics documentation: align the metrics reference with the code

docs/_docs/services/services.adoc

@@ -286,7 +286,7 @@ In this way, you don't have to stop the server nodes, so you don't interrupt the
 
 You can measure durations of your service's methods. If you want this analytics, enable service statistics in the
 service configuration. Service statistics are collected under name "Services" in
-link:monitoring-metrics/new-metrics-system.adoc[metrics], in
+link:monitoring-metrics/new-metrics#services[metrics], in
 link:monitoring-metrics/system-views.adoc[system views], and in JMX.
 
 [tabs]

modules/core/src/main/java/org/apache/ignite/internal/metric/IoStatisticsHolderCache.java

@@ -75,9 +75,9 @@ public IoStatisticsHolderCache(String grpName, int grpId, GridMetricManager mmgr
 
         MetricRegistryImpl mreg = mmgr.registry(metricRegistryName());
 
-        mreg.longMetric("startTime", null).value(U.currentTimeMillis());
-        mreg.objectMetric("name", String.class, null).value(grpName);
-        mreg.intMetric("grpId", null).value(grpId);
+        mreg.longMetric("startTime", "Statistics collection start time, in milliseconds.").value(U.currentTimeMillis());
+        mreg.objectMetric("name", String.class, "Cache or cache group name.").value(grpName);
+        mreg.intMetric("grpId", "Cache group ID.").value(grpId);
 
         logicalReadCtr = mreg.longAdderMetric(LOGICAL_READS, "Count of logical page reads");
         physicalReadCtr = mreg.longAdderMetric(PHYSICAL_READS, "Count of physical page reads");

modules/core/src/main/java/org/apache/ignite/internal/metric/IoStatisticsHolderIndex.java

@@ -86,14 +86,14 @@ public IoStatisticsHolderIndex(
 
         MetricRegistryImpl mreg = mmgr.registry(metricRegistryName());
 
-        mreg.longMetric("startTime", null).value(U.currentTimeMillis());
-        mreg.objectMetric("name", String.class, null).value(grpName);
-        mreg.objectMetric("indexName", String.class, null).value(idxName);
-
-        logicalReadLeafCtr = mreg.longAdderMetric(LOGICAL_READS_LEAF, null);
-        logicalReadInnerCtr = mreg.longAdderMetric(LOGICAL_READS_INNER, null);
-        physicalReadLeafCtr = mreg.longAdderMetric(PHYSICAL_READS_LEAF, null);
-        physicalReadInnerCtr = mreg.longAdderMetric(PHYSICAL_READS_INNER, null);
+        mreg.longMetric("startTime", "Statistics collection start time, in milliseconds.").value(U.currentTimeMillis());
+        mreg.objectMetric("name", String.class, "Cache or cache group name.").value(grpName);
+        mreg.objectMetric("indexName", String.class, "Index name.").value(idxName);
+
+        logicalReadLeafCtr = mreg.longAdderMetric(LOGICAL_READS_LEAF, "Number of logical reads for leaf tree node.");
+        logicalReadInnerCtr = mreg.longAdderMetric(LOGICAL_READS_INNER, "Number of logical reads for inner tree node.");
+        physicalReadLeafCtr = mreg.longAdderMetric(PHYSICAL_READS_LEAF, "Number of physical reads for leaf tree node.");
+        physicalReadInnerCtr = mreg.longAdderMetric(PHYSICAL_READS_INNER, "Number of physical reads for inner tree node.");
     }
 
     /** {@inheritDoc} */

modules/core/src/main/java/org/apache/ignite/internal/processors/cache/CacheGroupMetricsImpl.java

@@ -93,7 +93,7 @@ public CacheGroupMetricsImpl(CacheGroupContext ctx) {
 
         MetricRegistryImpl mreg = kernalCtx.metric().registry(metricGroupName());
 
-        mreg.register("Caches", this::getCaches, List.class, null);
+        mreg.register("Caches", this::getCaches, List.class, "List of caches.");
 
         mreg.register("StorageSize", this::getStorageSize, "Storage space allocated for group, in bytes.");
 
@@ -182,7 +182,7 @@ public void onTopologyInitialized() {
 
             mreg.register("ReencryptionBytesLeft",
                 () -> ctx.shared().kernalContext().encryption().getBytesLeftForReencryption(ctx.groupId()),
-                "The number of bytes left for re-ecryption.");
+                "The number of bytes left for re-encryption.");
         }
     }
 

modules/core/src/main/java/org/apache/ignite/internal/processors/cache/persistence/DataRegionMetricsImpl.java

@@ -244,7 +244,7 @@ public DataRegionMetricsImpl(
             5);
 
         largeEntriesPages = mreg.longAdderMetric("LargeEntriesPagesCount",
-            "Count of pages that fully ocupied by large entries that go beyond page size");
+            "Number of pages fully occupied by large entries that go beyond the page size.");
 
         dirtyPages = mreg.longAdderMetric("DirtyPages",
             "Number of pages in memory not yet synchronized with persistent storage.");
@@ -727,13 +727,12 @@ public void pageMemory(PageMemory pageMem) {
 
         mreg.register("PagesFillFactor",
             this::getPagesFillFactor,
-            "Returns the ratio of space occupied by user and system data to the size of all pages that contain " +
-                "this data");
+            "The ratio of space occupied by user and system data to the size of all pages that contain this data.");
 
         mreg.register("SizeUsedByData",
             this::getSizeUsedByData,
-            "Returns the number of bytes, occupied by data. Similar to TotalUsedSize, but it also takes into " +
-                "account the empty space in non-empty pages");
+            "Estimated number of bytes occupied by data. Similar to TotalUsedSize, but also takes into account " +
+                "the empty space in non-empty pages.");
 
         mreg.register("PhysicalMemoryPages",
             this::getPhysicalMemoryPages,
@@ -747,23 +746,23 @@ public void pageMemory(PageMemory pageMem) {
 
         mreg.register("TotalAllocatedSize",
             this::getTotalAllocatedSize,
-            "Gets a total size of memory allocated in the data region, in bytes");
+            "Total size of memory allocated in the data region, in bytes.");
 
         mreg.register("TotalUsedPages",
             this::getTotalUsedPages,
-            "Gets an amount of non-empty pages allocated in the data region");
+            "The number of non-empty pages allocated in the data region.");
 
         mreg.register("TotalUsedSize",
             this::getTotalUsedSize,
-            "Gets an amount of bytes, occupied by non-empty pages allocated in the data region");
+            "The number of bytes occupied by non-empty pages allocated in the data region.");
 
         mreg.register("PhysicalMemorySize",
             this::getPhysicalMemorySize,
-            "Gets total size of pages loaded to the RAM, in bytes");
+            "Total size of pages loaded to the RAM, in bytes.");
 
         mreg.register("UsedCheckpointBufferSize",
             this::getUsedCheckpointBufferSize,
-            "Gets used checkpoint buffer size in bytes");
+            "Used checkpoint buffer size in bytes.");
     }
 
     /**

modules/core/src/main/java/org/apache/ignite/internal/processors/cache/persistence/snapshot/IgniteSnapshotManager.java

@@ -544,7 +544,7 @@ public IgniteSnapshotManager(GridKernalContext ctx) {
             "The name of full snapshot for which the last incremental snapshot created on this node.");
         incSnpMReg.register("incrementIndex",
             () -> Optional.ofNullable(lastSeenIncSnpFut).map(f -> f.incIdx).orElse(0),
-            "Ihe index of the last incremental snapshot created on this node.");
+            "The index of the last incremental snapshot created on this node.");
         incSnpMReg.register("startTime",
             () -> Optional.ofNullable(lastSeenIncSnpFut).map(f -> f.startTime).orElse(0L),
             "The system time of the last incremental snapshot creation start time on this node.");

modules/core/src/main/java/org/apache/ignite/internal/processors/cache/query/GridCacheQueryMetricsAdapter.java

@@ -59,14 +59,14 @@ public class GridCacheQueryMetricsAdapter implements QueryMetrics {
     public GridCacheQueryMetricsAdapter(GridMetricManager mmgr, String cacheName, boolean isNear) {
         MetricRegistryImpl mreg = mmgr.registry(MetricUtils.cacheMetricsRegistryName(cacheName, isNear));
 
-        minTime = mreg.longMetric("QueryMinimalTime", null);
+        minTime = mreg.longMetric("QueryMinimalTime", "Minimum execution time of queries, in milliseconds.");
         minTime.value(Long.MAX_VALUE);
 
-        maxTime = mreg.longMetric("QueryMaximumTime", null);
-        sumTime = mreg.longAdderMetric("QuerySumTime", null);
-        execs = mreg.longAdderMetric("QueryExecuted", null);
-        completed = mreg.longAdderMetric("QueryCompleted", null);
-        fails = mreg.longAdderMetric("QueryFailed", null);
+        maxTime = mreg.longMetric("QueryMaximumTime", "Maximum execution time of queries, in milliseconds.");
+        sumTime = mreg.longAdderMetric("QuerySumTime", "Total execution time of queries, in milliseconds.");
+        execs = mreg.longAdderMetric("QueryExecuted", "Number of executed queries.");
+        completed = mreg.longAdderMetric("QueryCompleted", "Number of completed queries.");
+        fails = mreg.longAdderMetric("QueryFailed", "Number of failed queries.");
     }
 
     /** {@inheritDoc} */

modules/core/src/main/java/org/apache/ignite/internal/processors/metric/GridMetricManager.java

@@ -235,14 +235,18 @@ public GridMetricManager(GridKernalContext ctx) {
         gcCpuLoad = sysreg.doubleMetric(GC_CPU_LOAD, GC_CPU_LOAD_DESCRIPTION);
         cpuLoad = sysreg.doubleMetric(CPU_LOAD, CPU_LOAD_DESCRIPTION);
 
-        sysreg.register("SystemLoadAverage", os::getSystemLoadAverage, Double.class, null);
-        sysreg.register(UP_TIME, rt::getUptime, null);
-        sysreg.register(THREAD_CNT, threads::getThreadCount, null);
-        sysreg.register(PEAK_THREAD_CNT, threads::getPeakThreadCount, null);
-        sysreg.register(TOTAL_STARTED_THREAD_CNT, threads::getTotalStartedThreadCount, null);
-        sysreg.register(DAEMON_THREAD_CNT, threads::getDaemonThreadCount, null);
-        sysreg.register("CurrentThreadCpuTime", threads::getCurrentThreadCpuTime, null);
-        sysreg.register("CurrentThreadUserTime", threads::getCurrentThreadUserTime, null);
+        sysreg.register("SystemLoadAverage", os::getSystemLoadAverage, Double.class,
+            "System load average for the last minute, or a negative value if not available.");
+        sysreg.register(UP_TIME, rt::getUptime, "JVM uptime, in milliseconds.");
+        sysreg.register(THREAD_CNT, threads::getThreadCount, "Current number of live threads, including daemon threads.");
+        sysreg.register(PEAK_THREAD_CNT, threads::getPeakThreadCount, "Peak live thread count since the JVM started.");
+        sysreg.register(TOTAL_STARTED_THREAD_CNT, threads::getTotalStartedThreadCount,
+            "Total number of threads created and started since the JVM started.");
+        sysreg.register(DAEMON_THREAD_CNT, threads::getDaemonThreadCount, "Current number of live daemon threads.");
+        sysreg.register("CurrentThreadCpuTime", threads::getCurrentThreadCpuTime,
+            "CPU time of the thread that reads the metric, in nanoseconds.");
+        sysreg.register("CurrentThreadUserTime", threads::getCurrentThreadUserTime,
+            "User-mode CPU time of the thread that reads the metric, in nanoseconds.");
 
         MetricRegistryImpl pmeReg = registry(PME_METRICS);
 
@@ -764,10 +768,16 @@ public class MemoryUsageMetrics {
         public MemoryUsageMetrics(String grp, String metricNamePrefix) {
             MetricRegistryImpl mreg = registry(grp);
 
-            this.init = mreg.longMetric(metricName(metricNamePrefix, "init"), null);
-            this.used = mreg.longMetric(metricName(metricNamePrefix, "used"), null);
-            this.committed = mreg.longMetric(metricName(metricNamePrefix, "committed"), null);
-            this.max = mreg.longMetric(metricName(metricNamePrefix, "max"), null);
+            String kind = metricNamePrefix.endsWith("nonheap") ? "non-heap" : "heap";
+
+            this.init = mreg.longMetric(metricName(metricNamePrefix, "init"),
+                "Initial amount of " + kind + " memory requested by the JVM, in bytes; -1 if undefined.");
+            this.used = mreg.longMetric(metricName(metricNamePrefix, "used"),
+                "Amount of used " + kind + " memory, in bytes.");
+            this.committed = mreg.longMetric(metricName(metricNamePrefix, "committed"),
+                "Amount of " + kind + " memory committed for the JVM to use, in bytes.");
+            this.max = mreg.longMetric(metricName(metricNamePrefix, "max"),
+                "Maximum amount of " + kind + " memory that can be used, in bytes; -1 if undefined.");
         }
 
         /** Updates metric to the provided values. */

modules/core/src/main/java/org/apache/ignite/internal/processors/query/QueryParserMetricsHolder.java

@@ -42,8 +42,9 @@ public class QueryParserMetricsHolder {
     public QueryParserMetricsHolder(GridMetricManager metricMgr) {
         MetricRegistryImpl registry = metricMgr.registry(QUERY_PARSER_METRIC_GROUP_NAME);
 
-        qryCacheHits = registry.longAdderMetric("hits", "Count of hits for queries cache");
-        qryCacheMisses = registry.longAdderMetric("misses", "Count of misses for queries cache");
+        qryCacheHits = registry.longAdderMetric("hits",
+            "The number of SQL queries found in the parser cache, which do not require parsing and planning before execution.");
+        qryCacheMisses = registry.longAdderMetric("misses", "The number of SQL queries that were parsed and planned.");
     }
 
     /**

modules/core/src/main/java/org/apache/ignite/internal/processors/service/IgniteServiceProcessor.java

@@ -133,7 +133,7 @@ public class IgniteServiceProcessor extends GridProcessorAdapter implements Igni
     private static final String SERVICE_METRIC_REGISTRY = "Services";
 
     /** Description for the service method invocation metric. */
-    private static final String DESCRIPTION_OF_INVOCATION_METRIC_PREF = "Duration in milliseconds of ";
+    private static final String DESCRIPTION_OF_INVOCATION_METRIC_PREF = "Duration in nanoseconds of ";
 
     /** Default bounds of invocation histogram in nanoseconds. */
     public static final long[] DEFAULT_INVOCATION_BOUNDS = new long[] {

modules/core/src/main/java/org/apache/ignite/internal/thread/pool/IgniteStripedExecutor.java

@@ -518,7 +518,7 @@ public void awaitComplete(int... stripes) throws InterruptedException {
         mreg.register("StripesActiveStatuses",
             this::stripesActiveStatuses,
             boolean[].class,
-            "Number of active tasks per stripe.");
+            "Active status of each stripe.");
 
         mreg.register("StripesQueueSizes",
             this::stripesQueueSizes,

modules/core/src/main/java/org/apache/ignite/internal/thread/pool/IgniteStripedThreadPoolExecutor.java

@@ -52,6 +52,7 @@
 import static org.apache.ignite.internal.processors.pool.PoolProcessor.REJ_HND_DESC;
 import static org.apache.ignite.internal.processors.pool.PoolProcessor.TASK_COUNT_DESC;
 import static org.apache.ignite.internal.processors.pool.PoolProcessor.TASK_EXEC_TIME;
+import static org.apache.ignite.internal.processors.pool.PoolProcessor.TASK_EXEC_TIME_DESC;
 import static org.apache.ignite.internal.processors.pool.PoolProcessor.TASK_EXEC_TIME_HISTOGRAM_BUCKETS;
 import static org.apache.ignite.internal.processors.pool.PoolProcessor.THRD_FACTORY_DESC;
 
@@ -86,7 +87,7 @@ public IgniteStripedThreadPoolExecutor(
         boolean allowCoreThreadTimeOut,
         long keepAliveTime) {
         execs = new IgniteThreadPoolExecutor[concurrentLvl];
-        execTime = new HistogramMetricImpl(TASK_EXEC_TIME, TASK_COUNT_DESC, TASK_EXEC_TIME_HISTOGRAM_BUCKETS);
+        execTime = new HistogramMetricImpl(TASK_EXEC_TIME, TASK_EXEC_TIME_DESC, TASK_EXEC_TIME_HISTOGRAM_BUCKETS);
 
         ThreadFactory factory = new IgniteThreadFactory(igniteInstanceName, threadNamePrefix, eHnd);
 

modules/core/src/main/java/org/apache/ignite/services/ServiceConfiguration.java

@@ -284,7 +284,7 @@ public ServiceConfiguration setNodeFilter(IgnitePredicate<ClusterNode> nodeFilte
 
     /**
      * Enables or disables statistics for the service. If enabled, durations of the service's methods invocations are
-     * measured (in milliseconds) and stored in histograms of metric registry
+     * measured (in nanoseconds) and stored in histograms of metric registry
      * {@link IgniteServiceProcessor#SERVICE_METRIC_REGISTRY} by service name.
      * <p>
      * <b>NOTE:</b> Statistics are collected only with service proxies obtaining by methods like