This is an automated email from the ASF dual-hosted git repository.
namelchev 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 01d7719ef31 IGNITE-22104 Added documentation of custom metrics (#11331)
01d7719ef31 is described below
commit 01d7719ef318130d501942a6c0b0d531cec3180d
Author: Vladimir Steshin <[email protected]>
AuthorDate: Fri Apr 26 22:31:49 2024 +0300
IGNITE-22104 Added documentation of custom metrics (#11331)
---
docs/_data/toc.yaml | 2 +
docs/_docs/monitoring-metrics/custom-metrics.adoc | 66 ++++++++++++++++++++++
.../monitoring-metrics/new-metrics-system.adoc | 14 ++---
docs/_docs/monitoring-metrics/new-metrics.adoc | 3 -
4 files changed, 75 insertions(+), 10 deletions(-)
diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml
index d3d3534e6ce..11472772401 100644
--- a/docs/_data/toc.yaml
+++ b/docs/_data/toc.yaml
@@ -440,6 +440,8 @@
url: monitoring-metrics/configuring-metrics
- title: Metrics
url: monitoring-metrics/new-metrics
+ - title: Custom Metrics
+ url: monitoring-metrics/custom-metrics
- title: System Views
url: monitoring-metrics/system-views
- title: Performance Statistics
diff --git a/docs/_docs/monitoring-metrics/custom-metrics.adoc
b/docs/_docs/monitoring-metrics/custom-metrics.adoc
new file mode 100644
index 00000000000..6dcedf37ecf
--- /dev/null
+++ b/docs/_docs/monitoring-metrics/custom-metrics.adoc
@@ -0,0 +1,66 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+= Custom Metrics
+
+WARNING: This feature is experimental and may change in future releases.
+
+Ignite provides various internal
link:monitoring-metrics/new-metrics.adoc[metrics]. However, these metrics might
+not be enough. Users can design and publish their own custom metrics. Custom
Metrics are based on
+link:monitoring-metrics/new-metrics-system.adoc[Metric System].
+
+[NOTE]
+====
+Custom Metrics are local and are bound only to the local node.
+====
+
+== 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.
+
+You can create custom metric registries via the `IgniteMetrics` interface
which is obtained by `Ignite.metrics()`.
+
+`IgniteMetric` interface has the following methods:
+
+* `MetricRegistry getOrCreate(String registryName)` provides a new or existing
custom metric registry.
+* `void remove(String registryName)` removes the entire custom metric registry.
+
+
+=== Custom metric creation.
+
+To register a new custom metric, use the `MetricRegistry` interface which is
obtained by `IgniteMetrics.getOrCreate(...)`.
+
+`MetricRegistry` has several methods to add or remove metrics like:
+
+* `void register(String metricName, IntSupplier valueSupplier, @Nullable
String description);` registers an integer-value metric.
+* `void register(String metricName, DoubleSupplier valueSupplier, @Nullable
String description);` registers a double-value metric.
+* `void remove(String name);` removes a metric.
+
+
+== 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'.
+
+Prefix 'custom.' is always added to the custom registry name in
`IgniteMetrics`. For instance, if the passed registry name is
+'process.status.suspended', it is automatically extended to
'custom.process.status.suspended'.
+
+
+== Limitations
+* It is impossible to affect the internal metrics.
+* Custom metrics are registered on-demand and aren't persistent. After a node
restarts, they have to be registered anew.
+* Configuration of a custom metric isn't supported.
+* The names must not be empty and cannot have spaces or empty dot-separated
parts.
diff --git a/docs/_docs/monitoring-metrics/new-metrics-system.adoc
b/docs/_docs/monitoring-metrics/new-metrics-system.adoc
index 62a6cba3158..5f2de5d21a5 100644
--- a/docs/_docs/monitoring-metrics/new-metrics-system.adoc
+++ b/docs/_docs/monitoring-metrics/new-metrics-system.adoc
@@ -41,15 +41,15 @@ Ignite includes the following exporters:
You can create a custom exporter by implementing the
javadoc:org.apache.ignite.spi.metric.MetricExporterSpi[] interface.
-== Metric Registers
+== Metric Registries [[registry]]
-Metrics are grouped into categories (called _registers_).
-Each register has a name.
-The full name of a specific metric within the register consists of the
register name followed by a dot, followed by the name of the metric:
`<register_name>.<metric_name>`.
-For example, the register for data storage metrics is called `io.datastorage`.
-The metric that return the storage size is called `io.datastorage.StorageSize`.
+Metrics are grouped into categories (called _registries_).
+Each registry has a name.
+The full name of a specific metric within the registry consists of the
registry name followed by a dot, followed by the name of the metric:
`<registry_name>.<metric_name>`.
+For example, the registry for data storage metrics is called `io.datastorage`.
+The metric that returns the storage size is called
`io.datastorage.StorageSize`.
-The list of all registers and the metrics they contain are described
link:monitoring-metrics/new-metrics[here].
+The list of all registries and the metrics they contain are described
link:monitoring-metrics/new-metrics[here].
== Metric Exporters
diff --git a/docs/_docs/monitoring-metrics/new-metrics.adoc
b/docs/_docs/monitoring-metrics/new-metrics.adoc
index 5f3aaeabc00..7bce59dcb00 100644
--- a/docs/_docs/monitoring-metrics/new-metrics.adoc
+++ b/docs/_docs/monitoring-metrics/new-metrics.adoc
@@ -507,6 +507,3 @@ Register name: `sql.queries.user`
|failed| long | The number of failed SQL queries (including canceled).
|canceled| long | The number of canceled SQL queries.
|===
-
-
-
