metrics

Reporting Metrics

Version: 17.07

Developer Guide

Overview

Project-X has built-in metrics collection and publishing capabilities. The developers also have the the ability to report any custom metrics in addition to the framework level metrics. The following guidelines should be followed in order to initialize and report any such metrics stream.

STEP 1 - Annotate metrics reporting class with @MetricsReporter

Any class in Project-X which is supposed to report one or more metrics streams should be annotated with the @MetricsReporter annotation so that the framework can identify it as a metrics reporting class.

@MetricsReporter
public class SampleClass {
    ...
}

STEP 2 - Implement MetricsReportable interface

Then this class or one of its super classes should implement the MetricsReportable interface and the following methods of that interface.

@MetricsReporter
public class SampleClass implements MetricsReportable {
    ...
}

getMetricsEngine()

This method should return an instance of the metrics engine to be used for the metrics reporting

getEntityId()

This method should return a String identifier that can be used to distinguish the metrics records reported by this entity from the records of other similar type of entities.

For example, if the metrics reporting entity is a processing element, beanName of the processing element can be used as this entity ID.

getFlowId()

In case the ID of the Integration Flow is important for the metrics, this method should be implemented and should return the ID of the current Integration Flow.

getProjectId()

In case the enclosing Ultra Project is important for the metrics, this method should be implemented and should return the ID of the enclosing Ultra Project.

getProjectVersion()

In case the enclosing Ultra Project is important for the metrics, this method should be implemented and should return the version of the enclosing Ultra Project.

getAdditionalProperties()

If it is needed to add any additional properties to the metrics records, this method should be implemented and should return a map with those additional properties as key-value pairs.

STEP 3 - Declare the metrics stream

A metrics stream should be declared as an int variable which can have any access modifier depending on the development requirements.

@MetricsReporter
public class SampleClass implements MetricsReportable {

    private int myMetricsStream;

    ...
}

STEP 4 - Initialize the metrics stream

There are two ways to initialize a metrics stream. In either case, it is required to provide the following stream specific parameters.

stream

A unique identifier for the metrics stream. The recommended convention is to use the format stream_prefix:$:stream_name for this, where stream_prefix is a common identifier of these set of metrics streams and stream_name is the name of the this particular metrics stream.

Example : connector:$:receivedMsgCount or custom:$:validationFailureCount

recordType

The metrics record type to be used for this metrics stream. This record type should be one of these supported record types.

templateType

The name of the entity type that this metrics stream belong to.

Example : ConnectorMetrics or CustomMetrics

creationType

The creation type of the metrics stream which can be either PROCESSING, GLOBAL or SYSTEM. But it is highly recommended to use only the PROCESSING creation type for custom metrics streams as other two types are generally intended for framework level use.

Annotation based initialization

The first way to initialize a metrics stream is to annotate the declared metrics stream field with the @MetricsStream annotation. The above mentioned parameters should be set as the properties of the annotation. Then the framework will automatically identify the metrics stream and will perform the initialization steps.

@MetricsReporter
public class SampleClass implements MetricsReportable {

    @MetricsStream(stream = "custom:$:myStream",
                    recordType = COUNTER,
                    templateType = "CustomMetrics",
                    creationType = PROCESSING)
    private int myMetricsStream;

    ...
}
Since annotation properties always have to be constants, this method can be used only if all the above mentioned parameters are constants that can be defined at development time. Otherwise use the following method to initialize the stream.

Method based initialization

In-case the annotation based initialization is not a viable option, it is required to initialize metrics stream using the computeStream() method of metrics engine as follows.

@MetricsReporter
public class SampleClass implements MetricsReportable {

    private int myMetricsStream;

    public void init() {
        ...

        myMetricsStream = getMetricsEngine()
                    .computeStream(
                            "custom:$:myStream",
                            COUNTER,
                            "CustomMetrics",
                            PROCESSING,
                            getEntityId(),
                            getProjectId(),
                            getProjectVersion(),
                            getFlowId(),
                            getAdditionalProperties())
                    .getId();

        ...
    }

    ...
}
The methods getMetricsEngine(), getEntityId(), getProjectId(), getProjectVersion(), getFlowId(), and getAdditionalProperties() should have been already implemented at the STEP 2.

STEP 5 - Report metrics

Based on the record type of the metrics stream, the following methods of metrics engine can be used to report metrics to the stream.

The following methods are of the metrics engine and can be executed as getMetricsEngine().methodName().
Record Type Method Description

Counter

increment(streamID)

Increments the value of the counter metrics stream (with the provided stream ID) by 1.

decrement(streamID)

Decrements the value of the counter metrics stream (with the provided stream ID) by 1.

Counter Map

incrementCounterMap(streamID, key)

Increments the value of the counter with the given key that belongs to the metrics stream (with the provided stream ID) by 1.

decrementCounterMap(streamID, key)

Decrements the value of the counter with the given key that belongs to the metrics stream (with the provided stream ID) by 1.

Summation Gauge / Average Gauge

reportGauge(streamID, value)

Adds a data point with the provided value to the gauge metrics stream (with the provided stream ID).

Negative values reported to a gauge metrics stream will be ignored.
In this topic
In this topic
Contact Us