Introduction

In Spring Boot, the default Prometheus scrape endpoint is usually exposed at /actuator/prometheus, but you can move it if your routing, security, or infrastructure conventions require a different path. The important detail is that Spring Boot offers two related levers: changing the base path for all web actuator endpoints, or remapping only the Prometheus endpoint. Which one you use depends on whether you want to move the whole actuator namespace or just one endpoint.

Default Prometheus Actuator Path

With the Prometheus registry enabled and the endpoint exposed, the normal path is:

/actuator/prometheus

A minimal setup usually includes:

management.endpoints.web.exposure.include=prometheus

If that is all you need, Prometheus can scrape the default location and no path customization is necessary.

Option 1: Change the Base Path for All Actuator Endpoints

If you want every web actuator endpoint to move under a different prefix, use the actuator web base path.

management.endpoints.web.base-path=/manage
management.endpoints.web.exposure.include=prometheus,health,info

Now the Prometheus endpoint becomes:

/manage/prometheus

This is useful when your platform standardizes management endpoints under a shared prefix other than /actuator.

Option 2: Remap Only the Prometheus Endpoint

If you want to keep the general actuator base path but give Prometheus a custom endpoint name, use path mapping.

management.endpoints.web.base-path=/actuator
management.endpoints.web.path-mapping.prometheus=metrics
management.endpoints.web.exposure.include=prometheus

Now Prometheus is available at:

/actuator/metrics

This changes only that endpoint's web path, not the rest of the actuator namespace.

Example Prometheus Scrape Configuration

Once the application path changes, update the Prometheus scrape target accordingly.

1scrape_configs:
2  - job_name: 'my_service'
3    metrics_path: /manage/prometheus
4    static_configs:
5      - targets: ['localhost:8080']

The key point is that Prometheus must scrape the actual exported path. Changing the Spring Boot configuration alone is not enough.

Distinguish Path Customization from Port Customization

Spring Boot also lets you expose management endpoints on a different port. That is separate from changing the path.

For example:

management.server.port=9090
management.endpoints.web.base-path=/manage
management.endpoints.web.exposure.include=prometheus

Now the full scrape target is:

http://host:9090/manage/prometheus

This pattern is common when management traffic is isolated from the main application port.

Security and Routing Considerations

A custom path can help fit an existing gateway or security policy, but it does not secure the endpoint by itself. Prometheus metrics can still reveal useful operational details.

So if you move the endpoint, also think about:

• whether it should be exposed publicly
• whether it belongs on a management-only port
• whether network policy or gateway rules should restrict access
• whether authentication applies in your environment

The path name is only one part of the deployment design.

Test the Endpoint After the Change

After changing actuator path settings, verify the endpoint directly rather than assuming the new path works.

curl http://localhost:8080/manage/prometheus

If the endpoint returns metric text in Prometheus format, the application-side configuration is correct. If not, check whether:

• the endpoint is exposed
• the registry dependency is present
• the path mapping is correct
• you are hitting the right port

Common Pitfalls

The most common mistake is changing the Spring Boot path and forgetting to update Prometheus metrics_path to match.

Another mistake is confusing management.endpoints.web.base-path with management.endpoints.web.path-mapping.prometheus. One moves the whole actuator namespace, while the other remaps one endpoint.

Developers also change the path but forget that the endpoint still needs to be exposed explicitly through actuator configuration.

Summary

• The default Prometheus actuator endpoint is usually /actuator/prometheus.
• Use management.endpoints.web.base-path to move all actuator endpoints under a new prefix.
• Use management.endpoints.web.path-mapping.prometheus to rename only the Prometheus path.
• Update Prometheus scrape configuration to match the new application path.
• Treat path customization, port customization, and endpoint security as related but separate concerns.