Spring Prometheus scrape endpoint: registry, exposure and label contract

Three pieces must agree

Adding Actuator alone does not make a Prometheus scrape. Include the Prometheus registry in the application, expose the prometheus endpoint over HTTP, and configure the collector to reach the instance through an allowed operations route. The scrape representation lives at the Actuator prometheus endpoint; metric-cardinality starts with what each meter labels. The Actuator metrics endpoint is useful for human inspection, but it is not the collector's scrape format.

Keep identity stable

A request counter tagged with customer ID creates one series per customer, which grows with traffic rather than with the small set of routes and outcomes. Tag by bounded route template, method and response class. Keep environment and service identity consistent across redeployments; do not put timestamps or pod IDs into a custom label when the collector already supplies target identity. A collector outage should not make the receipt API fail a request.

Check real samples

After deployment, fetch the scrape from the same network and credentials used by the collector. Assert that the receipt outcome counter is present after one success and one rejection, then inspect its distinct label combinations. A zero or missing series can mean no event occurred, a bean was not registered, the registry is absent, or the endpoint is not exposed. These are different faults and deserve different tests. Management routing determines where the collector connects.

Implementation contract

management.endpoints.web.exposure.include=health,prometheus
management.metrics.tags.application=receipt-api

Cost and verification

Scraping walks and formats the registered meters on each interval. Series cost grows roughly with the product of distinct label values; keep that product bounded before choosing a short scrape interval.

Common Mistakes

• Do not point a Prometheus collector at the diagnostic metrics endpoint.
• Do not expose a scrape publicly just because it contains no customer response bodies.
• Do not use receipt IDs, tenant IDs or request IDs as metric label values.

Read next

Spring Boot metrics: bound tag values instead of tracking each receipt, Spring Actuator management port: separate listener, explicit access rule, Spring Boot Actuator health: public liveness without public diagnostics, Spring Boot tracing across RestClient: construct the client from Boot's builder, Spring tracing and logs: preserve request identity across outbound calls.