Learnitweb

Spring Boot Actuator Tutorial: Introduction to Custom Metrics

What Are Metrics?

Metrics are numerical measurements that represent the behavior or state of your application over time. They provide insight into everything from response times and memory usage to custom business metrics such as the number of purchases or API errors.

Spring Boot Actuator includes built-in metrics and also allows us to create custom metrics tailored to our application’s specific needs.

Types of Metrics in Spring Boot

Spring Boot groups metrics into four main categories:

  1. Gauges: Represents a snapshot value at a point in time (e.g., memory usage, queue size).
  2. Counters: Monotonic increasing values (e.g., number of HTTP requests).
  3. Timers: Measures both the total time taken and the count of events.
  4. Distribution Summaries: Tracks distributions like request payload sizes, useful for statistical analysis.

Built-in Metrics with Auto-Configuration

When you include the Spring Boot Actuator dependency in your project, Spring automatically:

  • Scans your classpath
  • Applies conditions based on your configuration (e.g., enabled endpoints)
  • Registers default metrics for things like JVM, memory, disk space, and HTTP requests

These are made available under the /actuator/metrics endpoint.

Creating Custom Metrics

You can define custom metrics using the MeterRegistry. This bean is automatically configured when you add the actuator to your project.

You can inject the MeterRegistry into your classes using:

  • Constructor injection
  • Field injection
  • Setter injection

These custom metrics are then accessible under the /actuator/metrics endpoint, alongside the default ones.

Dimensional vs Hierarchical Metrics

Understanding how metrics are organized and queried is crucial for maintainability and scalability.

1. Hierarchical Metrics

Hierarchical metrics follow a dot-separated naming convention, for example:

http.server.requests.GET.200

If you want to find the number of successful GET requests, you query using this strict structure. However, it’s rigid:

  • You must follow the correct order
  • Adding or removing dimensions can break existing queries
  • Not flexible when requirements evolve

Example:

Querying successful GET requests:

http.server.requests.GET.200

If you want to add the region (say, Africa), it becomes:

http.server.requests.GET.200.Africa

This breaks earlier queries unless updated everywhere.

2. Dimensional Metrics

Dimensional metrics use tags instead of a naming convention, making them flexible and maintainable.

Example:

http.server.requests?tag=method:GET&tag=status:200

Or to get all failed requests from Africa:

http.server.requests?tag=status:500&tag=region:Africa

Benefits of Dimensional Metrics:

  • Order doesn’t matter – you can change the tag sequence without breaking queries
  • Easily filterable by attributes (method, status, region, etc.)
  • New tags can be added without affecting existing queries

This is the modern approach and is fully supported by Micrometer (which Spring Boot Actuator uses under the hood).

Business Use Cases for Metrics

Let’s explore some real-world examples where custom metrics help:

  • Count how many requests were successful (HTTP 200)
  • Track number of failed requests from a specific region
  • Measure time taken by a specific business operation
  • Monitor database connection pool size

These metrics provide business value by turning raw data into actionable insights.