apache-ignite

1
// Licensed to the Apache Software Foundation (ASF) under one or more
2
// contributor license agreements.  See the NOTICE file distributed with
3
// this work for additional information regarding copyright ownership.
4
// The ASF licenses this file to You under the Apache License, Version 2.0
5
// (the "License"); you may not use this file except in compliance with
6
// the License.  You may obtain a copy of the License at
7
//
8
// http://www.apache.org/licenses/LICENSE-2.0
9
//
10
// Unless required by applicable law or agreed to in writing, software
11
// distributed under the License is distributed on an "AS IS" BASIS,
12
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
// See the License for the specific language governing permissions and
14
// limitations under the License.
15
= Custom Metrics
16

17
WARNING: This feature is experimental and may change in future releases.
18

19
Ignite provides various internal link:monitoring-metrics/new-metrics.adoc[metrics]. However, these metrics might
20
not be enough. Users can design and publish their own custom metrics. Custom Metrics are based on
21
link:monitoring-metrics/new-metrics-system.adoc[Metric System].
22

23
[NOTE]
24
====
25
Custom Metrics are local and are bound only to the local node.
26
====
27

28
== Custom metric creation.
29

30
To register a custom metric, you need to add a new link:monitoring-metrics/new-metrics-system#registry[registry] first.
31
After that, metrics can be added to this registry.
32

33
=== Custom metric registry.
34

35
You can create custom metric registries via the `IgniteMetrics` interface which is obtained by `Ignite.metrics()`.
36

37
`IgniteMetric` interface has the following methods:
38

39
* `MetricRegistry getOrCreate(String registryName)` provides a new or existing custom metric registry.
40
* `void remove(String registryName)` removes the entire custom metric registry.
41

42

43
=== Custom metric creation.
44

45
To register a new custom metric, use the `MetricRegistry` interface which is obtained by `IgniteMetrics.getOrCreate(...)`.
46

47
`MetricRegistry` has several methods to add or remove metrics like:
48

49
* `void register(String metricName, IntSupplier valueSupplier, @Nullable String description);` registers an integer-value metric.
50
* `void register(String metricName, DoubleSupplier valueSupplier, @Nullable String description);` registers a double-value metric.
51
* `void remove(String name);` removes a metric.
52

53

54
== Naming convention.
55
Names of the custom metrics (and its registries) are similar to the names of internal metrics. The name can have dot-separated
56
parts like 'process.status.suspended'.
57

58
Prefix 'custom.' is always added to the custom registry name in `IgniteMetrics`. For instance, if the passed registry name is
59
'process.status.suspended', it is automatically extended to 'custom.process.status.suspended'.
60

61

62
== Limitations
63
* It is impossible to affect the internal metrics.
64
* Custom metrics are registered on-demand and aren't persistent. After a node restarts, they have to be registered anew.
65
* Configuration of a custom metric isn't supported.
66
* The names must not be empty and cannot have spaces or empty dot-separated parts.
67