Extensible metrics for monitoring and alerts

Metrics are enabled by default when using the HCL Commerce Helm charts. They can also be enabled by configuring the environment variable:

EXPOSE_METRICS=true

Metrics are exposed on each pods on the following paths and ports:

Counters

A positive count that can be increased by a fixed amount. For example, “number of requests.” Prometheus includes functions such as rate() and increase() that can be used to protect against counter resets

See the following examples for defining a Counter type:

Adding a new Counter with known value labels

private static Counter BACKEND_COUNTER = 
        Metrics.isEnabled() 
            ? Counter.builder( "backend.calls.total" )
               .tags( "result", "ok" )
               .description("Number of successful backend requests")
               .builder.register( Metrics.getRegistry())
            : null;
…

if ( BACKEND_COUNTER != null ) {
   BACKEND_COUNTER.increment();
}

Adding a new Counter with labels unknown in advance

if ( Metrics.isEnabled() ) {

   Metrics.getRegistry().counter( 
      "backend.calls.total", 
      "result",
      myGetResult()
     ).increment();  
}

Timers

Timers are used to track the duration and frequency of events. Besides calculating the average durations, the API allows to configure a set of Service Level Objectives (SLO), which are translated to histogram buckets. SLOs can also be used to calculate quantiles. For more information, see Histograms and Summaries on the Prometheus website.

The Metrics class defines SLOs for common usages. For example, Metrics.DEFAULT_SLO_REST_DURATIONS_NAME defines buckets that are appropriate for typical REST execution times. If your timer doesn’t match these durations, you can specify new values as a long array. For more information, see .sla() in the Timer.Builder class definition on the Micrometer website.

Example: Adding a new Timer with known value labels

private static Timer BACKEND_TIMER = 
        Metrics.isEnabled() 
            ? Timer.builder( "backend.calls.duration" )
               .tags( "result", "ok" )
               .sla( Metrics.getSLOsByName(Metrics.DEFAULT_SLO_REST_DURATIONS_NAME) )  
               .description("Duration of successful backend requests")
               .builder.register( Metrics.getRegistry())
            : null;

…

if (BACKEND_TIMER != null ) {
  startTime = System.nanoTime();
}

doWork();

if (BACKEND_TIMER != null ) {
  final long deltaTime = System.nanoTime() - startTime;
  BACKEND_TIMER .record(deltaTime, TimeUnit.NANOSECONDS );
}

When using a Timer with label values that are not known in advance, the micrometer API doesn’t allow for SLO (.sla(..)) to be specified. In order to achieve this, define a meter filter to merge the config. The Metrics.applySLO(final String metricName, final long[] slos) or Metrics.applySLO(final String metricName, final String name) utility methods can be used for the same.

Example: Adding a new Timer with label values not known in advance

private static String TIMER_NAME = "backend.calls.duration";

static {
   Metrics.applySLO( TIMER_NAME, Metrics.DEFAULT_SLO_REST_DURATIONS_NAME );
}

…

if ( Metrics.isEnabled() ) {
  startTime = System.nanoTime();
}

doWork();

if ( Metrics.isEnabled() ) {
   final long deltaTime = System.nanoTime() - startTime;
   Metrics.getRegistry().timer(
        TIMER_NAME,
        "result",
        getResult() )
            .record( deltaTime , TimeUnit.MILLISECONDS ); 

}

Gauges

A gauge holds a value that can increase and decrease over time. The meter is mapped to a function to obtain the value. Examples include number of active sessions and current cache sizes.

Example: Defining a gauge

class MyService {

 private Gauge myActiveClientsGauge;

 final void setup() {
   if (Metrics.isEnabled()) {
     myActiveClientsGauge = Gauge.builder( "myservice.activeclients", this,       
                                MyService::getActiveClients )
      .tags("endpoint", getEndpointName())
      .register(Metrics.getRegistry());
   }
 }
 
 private double getActiveClients() {		
   return nActiveClients; 
 }
}