Microservices Metrics targets with MicroProfile

In our previous blog post, Getting Started with Microprofile Metrics, we covered the basic concepts about metrics scopes and types of application metrics you can include in your existing JAX-RS endpoints.

In this article, we are going to summarize the metadata and default values from the MicroProfile Metrics annotations and how they should be applied. The type of annotations applied to a target tracks how that target (field, method, etc.) is measured and the default values help us to make our code cleaner.

Default units and targets per annotation

Table No.1 describes each of the Metrics annotations and the target areas where they can be applied. The following convention is used for Targets: (C=Constructor, F=Field, M=Method, P=Parameter, T=Type/Class).

Annotation	Description	Default Unit	Targets
@Counted	Denotes a counter that counts the invocations of the annotated target. This annotation has changed in MicroProfile Metrics 2.0 because now counters always increase monotonically upon invocation. The old behavior pre 2.0 can now be achieved with @ConcurrentGauge.	NONE	M, C, T
@ConcurrentGauge	Denotes a gauge that counts the parallel invocations of the annotated target.	NONE	M, C, T
@Gauge	Denotes a gauge that samples the value of the annotated target.	no default. It must be supplied by the user.	M
@Metered	Denotes a meter that tracks the frequency of invocations of the annotated target.	PER_SECOND	M, C, T
@Timed	Denotes a timer that tracks the duration of the annotated object.	NANOSECONDS	M, C, T
@Metric	An annotation that contains the metadata information when requesting a metric to be injected or produced. This annotation can be used on fields of type Meter, Timer,Counter, and Histogram. For Gauge, the @Metric annotation can only be used on producer methods/fields.	NONE	M, F, P

Table 1. Default unit and targets defined by the latest version of MicroProfile Metrics, 2.0.1.

Examples of different code targets:

Constructor

@Counted
public CounterBean() {
}

The @Counted annotation tells metrics to keep track of the number of times this constructor is invoked.

Field

@Produces
@Metric(name="hitPercentage")
@ApplicationScoped
Gauge hitPercentage = new Gauge() {
  @Override
  public Double getValue() {
    return hits / total;
  }
};

The @Metric annotation contains the metadata information when requesting a metric to be injected or produced.

Method

@Gauge(unit = MetricUnits.NONE)
public long getValue() {
  return value;
}

The @Gauge annotation samples the value of the getValue method.

Parameter

@Inject
public void init(@Metric(name="instances") Counter instances) {
  instances.inc();
}

@Metric annotation contains the name of metadata for the metric Counter produced in the init method.

Type/Class

@Timed
public class TimedBean {
  public void timedMethod1() {}
  public void timedMethod2() {}
}

@Timed annotation tracks the duration of each constructor from the TimedBean class.

Annotation Fields

Table 2 shows the fields described in the metric metadata. The following fields apply to all annotations except for org.eclipse.microprofile.metrics.annotation.RegistryType.

Name	Description	Type
name	Sets the name of the metric. If not explicitly given the name of the annotated target is used.	String
absolute	If true, uses the given name as the absolute name of the metric. If false, prepends the package name and class name before the given name. The default value is false.	boolean
displayName	A human-readable display name for the metadata.	String
description	A description of the metric	String
unit	Unit of the metric. Check Table 1 for default unit peer metric annotation.	String
reusable	Denotes if a metric with a certain MetricID that can be registered in more than one place. Does not apply to gauges.	boolean

Learning by coding

Apache TomEE has a series of MicroProfile related examples you can find online on the official project website: https://tomee.apache.org/latest/examples/. The examples are independent of each other and depend only on Java and Maven setup on your computer.

You can use any of the existing MicroProfile metrics examples to test the targets and default units, covered in this article.

• MicroProfile Metrics Counted
• MicroProfile Metrics Timed
• MicroProfile Metrics Metered
• MicroProfile Metrics Histogram

Conclusion

In this article, we presented a summary of code targets and default units available in MicroProfile metrics annotations. This will allow you to better design and instrument your microservices architecture with the metrics data and metadata that will then be processed and presented via metrics aggregator services.