Spring Boot 3: How To Add Tags in Server Requests Metrics

Understand how we can add tags in server requests metrics using Spring Default Server Request Observation Convention. This is useful for adding tags in application endpoint metrics. These tags will be added as additional tags on top of the default tags that are provided by the framework.

Context

When we add Spring Boot Starter Actuator dependency in our Spring Boot application, we can access the metrics for our application endpoints via the actuator metrics endpoint. In order to access the metrics data, we need to send the GET request specifying the name of metrics we are interested in i.e. in our case server requests metrics.

curl --request GET 'http://localhost:8080/actuator/metrics/http.server.requests'

By default, metrics are available with the name ‘http.server.requests’. This name can be customized by setting one property in the application.properties file.

When we send the request to the above endpoint, by default, we get the following tags in the output:

exception: any exceptions that were encountered during the request processing
method: HTTP methods
uri: endpoints for which we received the requests
outcome: whether the request was processed successfully or not
status: HTTP status code

Advantages

When we add our custom tags, we can utilize this information to create charts and dashboards displaying information at a more granular level.

Example: For each request, we can add a location tag highlighting the region from where we have received a request. Based on this information, we can create graphs and charts and see from what all regions we are receiving major traffic.

Adding Custom Tags

Note:

Below mentioned steps works only in case of Spring Boot 3.x. For Spring Boot 2.x, kindly refer to article Spring Boot 2: How To Add Tags in Server Request Metrics.

If we want to add our own tags in addition to tags that are provided by Spring Framework then we can do it with the help of the Spring Default Server Request Observation Convention class.

Steps:

1. Create a class that extends the DefaultServerRequestObservationConvention class.
2. Override the getLowCardinalityKeyValues method wherein we can add our own additional tags using KeyValues.
3. Register this class as Spring Bean using @Component annotation.

import io.micrometer.common.KeyValue;
import io.micrometer.common.KeyValues;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.server.observation.DefaultServerRequestObservationConvention;
import org.springframework.http.server.observation.ServerRequestObservationContext;
import org.springframework.stereotype.Component;


/**
 * The type Bootcamp to prod extended server request observation convention.
 * Useful for adding tags in controller metrics in addition to default tags.
 */
@Component
public class BootcampToProdExtendedServerRequestObservationConvention extends DefaultServerRequestObservationConvention {

    // Use constructor only if you want to customize the name of metrics
    // Default name will be 'http.server.requests'
    public BootcampToProdExtendedServerRequestObservationConvention(@Value("${management.observations.http.server.requests.name}") String httpServerRequestsName) {
        super(httpServerRequestsName);
    }

    @Override
    public KeyValues getLowCardinalityKeyValues(ServerRequestObservationContext context) {
        // here, we just want to have an additional KeyValue to the observation, keeping the default values
        return super.getLowCardinalityKeyValues(context).and(additionalTags(context));
    }

    protected KeyValues additionalTags(ServerRequestObservationContext context) {
        KeyValues keyValues = KeyValues.empty();

        // Optional tag which will be present in metrics only when the condition is evaluated to true
        if (context.getCarrier() != null && context.getCarrier().getParameter("user") != null) {
            keyValues = keyValues.and(KeyValue.of("user", context.getCarrier().getParameter("user")));
        }

        // Custom tag which will be present in all the controller metrics
        keyValues = keyValues.and(KeyValue.of("tag", "value"));

        return keyValues;
    }

}

We have control over a request object using context.getCarrier(), response object using context.getResponse(), and exception object using context.getError(). Based on this, we can add our own tags.

In the above example, we have added two tags “user” and “tag” wherein the “user” tag is optional and will be added to metrics only if we are receiving requests with the query parameter “user” whereas the “tag” tag will be added to metrics for the all the requests that we have received. We are calling the superclass getLowCardinalityKeyValues() method to get the default tags and on top of it we are adding our own tags,

Output:

Source Code

The source code for this example can be found on GitHub. Link: click here

Learn More