Skip to content

Grokem · https://www.grokem.com/programming/web-development/backend/spring-boot-actuator-health-checks-and-micrometer-metrics-for-beginners

BackendIntegration guideBeginner level

Spring Boot Actuator health checks and Micrometer metrics for beginners

Connect a Spring Boot app to Actuator and Micrometer: control which endpoints are available, read the health endpoint, add a Prometheus registry and record a custom counter. Each step says what to check.

Pankaj Nigam

Technical Writer

Published
  • 40 min to complete
  • 0 sec

Tested with
  • Spring Boot
  • Spring Boot Actuator
  • Micrometer
  • Micrometer Prometheus registry
Your progress
  1. Spring Boot Actuator health checks and Micrometer metrics for beginners8 min(finished)
    0%

Before you start

5
  • A working Spring Boot web application that you can build and start locally
  • Maven or Gradle as your build tool
  • A terminal with curl
  • Permission to change the application's build file and its application.properties or application.yaml
  • Optional: a Prometheus server, only if you want to scrape the metrics later

Spring Boot Actuator lets you monitor and interact with a running application. It ships built-in endpoints, and the health endpoint is the best known: it provides basic application health information. Micrometer is the metrics facade that Actuator configures for you. It supports numerous monitoring systems.

This guide connects your app to both. You will decide which endpoints may be used, call the health endpoint, add a Micrometer registry for Prometheus, tag every metric with a common tag and record your own counter.

Versions. No version number is pinned here. Use the Spring Boot version your project already uses. Spring Boot Actuator provides dependency management for Micrometer, so you normally do not set a Micrometer version yourself. If you also declare the Micrometer BOM, you only declare it once per project. If your framework already manages Micrometer versions, defer to that.

Access and permissions in one sentence. An endpoint is available when access to it is permitted and it is exposed. Auto-configuration only creates the built-in endpoints that are available.

What this guide does not cover. The pages used here describe endpoint access and exposure, but they do not describe how to put authentication in front of HTTP endpoints. They also do not give the Actuator dependency coordinates or the full name of the exposure property. For those, follow the links to the official Actuator reference in the references list and check the page for your Spring Boot version.

Your Spring Boot appActuator endpoints/actuator/health/actuator/metricsMeterRegistry(Micrometer)Prometheus registryaccess permitted+ exposed
How requests and metrics flow between your app, Actuator and Micrometer.

By default, access to every endpoint except shutdown and heapdump is unrestricted. Most applications choose exposure over HTTP, where the endpoint ID with a prefix of /actuator is mapped to a URL. For example, health is mapped to /actuator/health.

Step 1 of 11: Add the Actuator dependency to your build

Add the Spring Boot Actuator dependency to your project. Without it, no /actuator endpoints exist.

The exact coordinates are not repeated in this guide. Copy them from the official Actuator reference for your Spring Boot version, linked under references. Then rebuild the project so the change is picked up.

Why: Actuator provides both the endpoints and the dependency management and auto-configuration for Micrometer.

Step 2 of 11: Start the app and request the health endpoint

Start your application the way you normally do. Then send one request to the health endpoint from a second terminal. Replace YOUR_PORT with the port your server listens on.

Why: this proves that the endpoint is available, which means access is permitted and the endpoint is exposed.

bash
curl -i http://localhost:YOUR_PORT/actuator/health

Step 3 of 11: Check what the health response tells you

Read the status line and the body. A successful response means the health endpoint is mapped under the /actuator prefix and returns basic application health information.

If you get a 404, go to the troubleshooting section before you continue. The exact response format is described in the Actuator API documentation, so check it there rather than relying on a copy here.

Why: every later step builds on a reachable Actuator.

Step 4 of 11: Choose an access policy for your endpoints

Decide whether endpoints are opt-out or opt-in. The default is opt-out: everything except shutdown and heapdump is unrestricted.

For a safer start, make access opt-in. Set management.endpoints.access.default to none, then turn on only what you need with management.endpoint.<id>.access. The example below denies everything, then opens health and metrics as read-only.

Why: inaccessible endpoints are removed entirely from the application context, so a closed endpoint cannot be reached at all.

The access values shown in the Actuator reference are none, read-only and unrestricted. Read access means read operations only. For request-mapping endpoints it means requests that can handle GET and HEAD.

yaml
management:
  endpoints:
    access:
      default: none
  endpoint:
    health:
      access: read-only
    metrics:
      access: read-only

Step 5 of 11: Set an application-wide ceiling on access

Optionally add management.endpoints.access.max-permitted to cap what any endpoint may do. The value read-only allows only read access. The value none makes all endpoints inaccessible.

Why: this property takes precedence over the default access and over an individual endpoint's access level, so one line protects you from a later, more permissive per-endpoint setting.

Keep the shutdown endpoint closed unless you truly need it. It is disabled by default, only works with jar packaging and lets the application be gracefully shut down. To allow it you would set management.endpoint.shutdown.access=unrestricted.

yaml
management:
  endpoints:
    access:
      max-permitted: read-only

Step 6 of 11: Confirm the exposure setting for HTTP

Check that the endpoints you opened are also exposed over HTTP. Access and exposure are two separate switches. To change only the technologies over which an endpoint is exposed, the Actuator reference tells you to use the include and exclude properties.

The full property names are on the official endpoints page, so open it and copy them from there for your Spring Boot version.

Why: an endpoint with permitted access that is not exposed is still not available.

Step 7 of 11: Add the Micrometer Prometheus registry

Add the Prometheus registry to your build. A dependency on micrometer-registry-{system} in your runtime classpath is enough for Spring Boot to configure the registry.

Do not set a version. Spring Boot's dependency management supplies it. If you use Micrometer's BOM directly instead, declare it once and leave the version off this dependency too.

Why: Spring Boot auto-configures a composite MeterRegistry and adds a registry for each supported implementation it finds on the classpath.

The endpoint that exposes metrics in a Prometheus-scrapable format needs this dependency. Its ID is listed on the official endpoints page. Reach it the same way as the others, with /actuator/ plus the ID.

xml
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
groovy
implementation 'io.micrometer:micrometer-registry-prometheus'

Step 8 of 11: Add a common tag to every metric

Create a configuration class with a MeterRegistryCustomizer bean. It applies the tag region to every meter, so you can slice data by that dimension later. Change us-east-1 to your own value.

Why: registry customizers run before any meters are registered with the registry, so the tag reaches all of them. A meter is identified by its name and its tags, and tags let you drill down on a named metric.

java
package com.example.demo;

import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.boot.micrometer.metrics.autoconfigure.MeterRegistryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyMeterRegistryConfiguration {

    @Bean
    public MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {
        return (registry) -> registry.config().commonTags("region", "us-east-1");
    }

}

Step 9 of 11: Record a custom counter

Add a service that registers a Counter on the injected MeterRegistry. Call feature() from your own code wherever the event you want to count happens.

Why: a counter reports a single metric, a count, and it can only go up by a positive amount. The counter is stored in a field, which avoids looking it up by name and tags on every use.

Use a counter only for things you cannot time. A Timer or a DistributionSummary already publishes a count of events, so you do not need a separate counter for code you time.

java
package com.example.demo;

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.stereotype.Service;

@Service
public class FeatureService {

    private final Counter featureCounter;

    public FeatureService(MeterRegistry registry) {
        this.featureCounter = Counter.builder("feature")
                .description("Number of times the feature was used")
                .tags("region", "test")
                .register(registry);
    }

    public void feature() {
        featureCounter.increment();
    }

}

Step 10 of 11: Restart the app and list the metrics

Restart the application so the new beans load. Then request the metrics endpoint.

Why: the metrics endpoint shows the metrics the application has recorded, which lets you diagnose what is being collected. Look for the name feature in the response.

bash
curl -i http://localhost:YOUR_PORT/actuator/metrics

Step 11 of 11: Turn registries off when you do not want an export

Disable a registry through configuration if its library is on the classpath but you do not want it active. The setting below disables all registries unless a registry-specific property says otherwise.

Why: most registries share these common features, so you can keep a dependency in the build and still control the export per environment.

To disable one registry only, use its own property. The Actuator reference shows management.datadog.metrics.export.enabled=false as the pattern for Datadog.

yaml
management:
  defaults:
    metrics:
      export:
        enabled: false

Expected result

A request to /actuator/health returns a successful HTTP response with basic application health information. A request to /actuator/metrics returns a response that lists the metrics the application has recorded, including the name feature once the counter is registered. If you set max-permitted to none, or the default access to none without opening an endpoint, the same requests return an error because inaccessible endpoints are removed from the application context. The exact response bodies are documented in the Actuator API documentation.

Troubleshooting

ProblemLikely causeFix
/actuator/health returns 404The endpoint is not available: Actuator is missing from the build, access is not permitted, or the endpoint is not exposed over HTTP. An endpoint is available only when it is both permitted and exposed.Confirm the Actuator dependency is in the build. Check that management.endpoint.health.access is not none and that management.endpoints.access.max-permitted does not block it. Then check the HTTP exposure setting on the official endpoints page.
An endpoint you opened is still missing after you set its access propertymanagement.endpoints.access.max-permitted takes precedence over default access and over an individual endpoint's access level.Raise or remove max-permitted, then restart the application.
The shutdown endpoint does not respondIt is disabled by default and only works when you use jar packaging.Set management.endpoint.shutdown.access=unrestricted only if you really need it, and run the app from a jar.
The Prometheus endpoint is not presentThe endpoint requires the micrometer-registry-prometheus dependency, and it only exists if it is available (permitted and exposed).Add micrometer-registry-prometheus to the runtime classpath, check the endpoint ID on the official endpoints page, and open access and exposure for it.
Your custom metric is not in the metrics listThe meter was never registered, for example because the class that creates it is not a Spring bean, or all registries are disabled with management.defaults.metrics.export.enabled=false.Make sure the service is a Spring bean that receives the MeterRegistry. Check the export settings. Restart the application and request /actuator/metrics again.
Metrics recorded on a CompositeMeterRegistry have no effectRecordings have no effect until there is a non-composite registry in the composite. Meters recorded before a registry was added are not reflected in it.Add your registries and filters first, then register meters. In Spring Boot, use MeterRegistryCustomizer beans so configuration happens before meters are registered.

Frequently asked questions

What URL does the Spring Boot health check use?

By default the health endpoint is mapped to /actuator/health. The endpoint ID plus the /actuator prefix forms the URL for HTTP.

What makes an Actuator endpoint available?

Access to it must be permitted and it must be exposed. Built-in endpoints are auto-configured only when they are available.

Which endpoints are restricted by default?

Access to all endpoints is unrestricted except shutdown and heapdump.

How do I make endpoint access opt-in?

Set management.endpoints.access.default to none. Then set management.endpoint.<id>.access for each endpoint you want, for example read-only.

Do I need to configure a MeterRegistry myself?

No. Spring Boot auto-configures a composite MeterRegistry and adds a registry for each supported implementation it finds on the classpath. You can inject the MeterRegistry into your own beans.

Do I need a version for micrometer-registry-prometheus?

Not when a BOM or your framework's dependency management defines it. Spring Boot Actuator provides dependency management for Micrometer.

Can I try metrics without a monitoring system?

Yes. Micrometer includes a SimpleMeterRegistry that holds the latest value of each meter in memory and exports nothing. It is autowired for you in Spring-based applications.

How do I secure the endpoints with a login?

This guide covers endpoint access and exposure only. Check the official Spring Boot documentation for authentication of HTTP endpoints.

References

From Grokem: https://www.grokem.com/programming/web-development/backend/spring-boot-actuator-health-checks-and-micrometer-metrics-for-beginners

Finished this article?

How did this strike you?

Be the first to react – it is anonymous.

Community

Questions about this?

Ask in Questions and help and get help from other readers.

Ask a questionBrowse Questions and help

Comments

No comments yet. Share what worked for you, or ask a question.

Keep learning

Picked for this article

Related reading, discussions and learning paths on the same subject.

All in Backend

Choose what we may use. You can change this at any time with “Privacy choices” at the foot of every page. Details are in the Cookie policy and the Privacy policy.

Strictly necessary

Remembers your theme, the lessons you marked as done and this choice. It stays on your device, tracks nothing and cannot be switched off.

Always on
What exactly is collected, and why

Google Analytics

Collects
The pages you view, your device and browser type, your language, how you reached the site and your approximate location (country and city, worked out from your IP address).
Why
To understand which pages and lessons are used, so we can improve them.
Stored
Two cookies, _ga and _ga_<id>, for up to 2 years. Google acts for us; the data is processed by Google, including outside your country.

Grokem’s own counts

Collects
The pages you open and how long you stay, how far you scroll, where you came from, your device type, browser, screen size, language and time zone. Your IP address is turned into a code that changes every day; it is never stored as it is.
Why
To see how long lessons are read and where readers leave. Not shared with anyone.
Stored
A random visitor ID, a visit ID and the time of your last page view in your browser’s storage (gr_vid, gr_sid, gr_last). No name or email is attached.