...

Implementation proposal

General approach

1. Custom metrics

...

1. are experimental.
2. Custom Metrics

...

1. base on

...

1. the New Metric System.
2. Allow to register essential ready-to-use metrics like LongMetric which can be exported by a

...

1. providing metric exporter.
2. User can

...

1. add own metrics into different registries.
2. Custom metrics are separated from the internals by registry name prefix "custom." (lower cased). 

...

1. Names of custom metrics and

...

1. thier registries can't contain any spaces.
2. Management of custom metrics might require a permission.

...

1. If we expose only few simple metrics, we should document examples of effecient metrics implementations like LongAdder.

API

   1.

...

APIs description

An API to expose internals read-noly metrics was already proposed. Might be joined with the custom metrics.

To give an user the ability to register additional metrics, we could either:

• Refactor a bit current metrics. Create interfaces for writable metric registry, metric manager. Create interfaces for some essential metrics (int, double, long, longAdder, boolean, object) and the gauge metrics (IntGauge, LongGauge, etc.).  are below.
• Provide tiny enough facade with consumers and suppliers for int, long, double value metrics.

These two approaches are shown below.

2. Obtaining Custom Metrics

package org.apache.ignite;

public interface Ignite {

   public IgniteCustomMetricsIgniteMetrics metrics();

}

3. 

...

4. Minimal Custom Metric interface

package org.apache.ignite;

/**
 * Manages custom metrics. Provides read-only internal metrics.
 *
 * Metrics are grouped into registries. Every metric has full name which is the conjunction of registry name and metric name. 
 * Registry name is part of the full name until last '.'. Metric name is the last part of the full name. 
 * 
 * Full names and registry names of custom metrics are always prefixed with "custom.". For example, if provided fullregistry name is "a.b.c.mname", 
 * it is automatically converted to "custom.a.b.c.mname". If fullthe name is "custom.a.b.c.mname", it is used as is. 
 * Where "custom.a.b.c" is a registry name and "mname" is a metric name. 
 */

@IgniteExperimental
public interface IgniteCustomMetricsIgniteMetrics extends Iterable<ReadOnlyMetricRegistry> {
    /**
    <T extends* Metric>Adds Ta metric(String fullName, T metric);
 void removeMetric(String fullName);
 ReadOnlyMetricRegistry registry(String registryName);
 void removeRegistry(String registryName);
 // Essential metrics. Int, Long and Double should be enough. Return current or new metric.
 
 long value custom metric.
     *
     * @return New or previously registered long value metric. {@code Null} if previous metric is not a {@link LongConsumer}.
     */
    @Nullable LongConsumer longMetric(String fullNameregistryName, String metricName, @Nullable String description);

    /**
     * Adds a double value custom metric.
     *
     * @return New or previously registered long value metric. {@code Null} if previous metric is not a {@link DoubleConsumer}.
     */
    @Nullable DoubleConsumer doubleMetric(String fullNameregistryName, String metricName, @Nullable String description);

    /**
     * Adds a int value custom metric.
     *
     * @return New or previously registered long value metric. {@code Null} if previous metric is not an {@link IntConsumer}.
     */
    @Nullable IntConsumer booleanMetric(String registryName, String fullNamemetricName, @Nullable String description);

    // Might be useful the gauges. Return true if new metric is registered of false if metric is**
     * Adds a long value custom metric.
     *
     * @return {@code True} if {@code supplier} has been registered as a new int metric. {@code False}, if a previous 
     * value supplier already exists.
     */
    boolean longMetric(String registryName, String fullNamemetricName, LongSupplier valueSuppliersupplier, @Nullable String description);

    /**
     * Adds a double value custom metric.
     *
     * @return {@code True} if {@code supplier} has been registered as a new int metric. {@code False}, if a previous 
     * value supplier already exists.
     */
    boolean doubleMetric(String registryName, String fullNamemetricName, DoubleSupplier valueSuppliersupplier, @Nullable String description);

    /**
     * Adds a int value custom metric.
     *
     * @return {@code True} if {@code supplier} has been registered as a new int metric. {@code False}, if a previous 
     * value supplier already exists.
     */
    boolean intMetric(String registryName, String fullNamemetricName, BooleanSupplier valueSuppliersupplier, @Nullable String description);
    
    /** Removes certain custom metric. */
    void removeCustomMetric(String registryName, String metricName);

    /** Removes entire custom metric registry. */
    void removeCustomRegistry(String registryName);

    /** Provides custom or internal read-only metric registry. */
    @Nullable ReadOnlyMetricRegistry findRegistry(String registryName);
}

Risks and Assumptions

• Custom metrics can affect the performanceare just another way to hit performance and consume additional resources.
• There could be race conditions on metric registrations. Metrics with incompatible metric type can be concurrently registered with the same names.
• We do not provide varuous useful metric implementatonsread-only metric wrappers for the internal metrics. User can cast read-only metric to writeable implementation or interface and change value of an iternal metric. But we already have public Metric#reset(), IgniteSpiContext#removeMetricRegistry(). And current ReadOnlyMetricRegistry doesn't return write-protected metric implementation.
• We do not expose API of all internal metrics. At least with the first tickets.
• Custom metrics aren't stored and require re-registration after node restart. At least at with the first phasetickets.

Further Steps

We already have implementations of more complex and useful metrics. We could also store custom metrics. Thus, the development stages might be:

1. Implementation of Extending the initial API .Extending this API with more complex metrics like Histogram , or HitRate, LongAdder.
2. Introduce a permission of custom metric management.
3. Storing registered custom metrics.
4. Allowing to change settings of configurable custom metrics like histograms.

...

1. IEP-35 Monitoring & Profiling
2. New Metric System
3. Ticket of a public metric API
4. IEP-116 : Ignite 3 metric

Discussion Links

Tickets