Spring Boot Actuator provides dependency management and auto-configuration for https://micrometer.io[Micrometer], an application metrics facade that supports {micrometer-docs}[numerous monitoring systems], including:
TIP: To learn more about Micrometer's capabilities, please refer to its https://micrometer.io/docs[reference documentation], in particular the {micrometer-concepts-docs}[concepts section].
[[actuator.metrics.getting-started]]
=== Getting started
Spring Boot auto-configures a composite `MeterRegistry` and adds a registry to the composite for each of the supported implementations that it finds on the classpath.
Having a dependency on `micrometer-registry-\{system}` in your runtime classpath is enough for Spring Boot to configure the registry.
Most registries share common features.
For instance, you can disable a particular registry even if the Micrometer registry implementation is on the classpath.
Spring Boot will also add any auto-configured registries to the global static composite registry on the `Metrics` class unless you explicitly tell it not to:
You can register any number of `MeterRegistryCustomizer` beans to further configure the registry, such as applying common tags, before any meters are registered with the registry:
Spring Boot also <<actuator#actuator.metrics.supported,configures built-in instrumentation>> that you can control via configuration or dedicated annotation markers.
[[actuator.metrics.export]]
=== Supported Monitoring Systems
[[actuator.metrics.export.appoptics]]
==== AppOptics
By default, the AppOptics registry pushes metrics to `https://api.appoptics.com/v1/measurements` periodically.
To export metrics to SaaS {micrometer-registry-docs}/appOptics[AppOptics], your API token must be provided:
Config properties in the `v1` namespace only apply when exporting to the {dynatrace-help}/dynatrace-api/environment-api/metric-v1/[Timeseries v1 API].
Config properties in the `v2` namespace only apply when exporting to the {dynatrace-help}/dynatrace-api/environment-api/metric-v2/post-ingest-metrics/[Metrics v2 API].
Please note that this integration can only export to either the `v1` or `v2` version of the API at a time.
If the `device-id` (required for v1, but not used in v2) is set in the `v1` namespace, metrics will be exported to the `v1` endpoint.
If a local OneAgent is running on the host, metrics will be automatically exported to the {dynatrace-help}/how-to-use-dynatrace/metrics/metric-ingestion/ingestion-methods/local-api/[local OneAgent ingest endpoint].
The ingest endpoint forwards the metrics to the Dynatrace backend.
This is the default behaviour and requires no special setup beyond a dependency on `io.micrometer:micrometer-registry-dynatrace`.
If no local OneAgent is running, the endpoint of the {dynatrace-help}/dynatrace-api/environment-api/metric-v2/post-ingest-metrics/[Metrics v2 API] and an API token are required.
The {dynatrace-help}/dynatrace-api/basics/dynatrace-api-authentication/[API token] must have the "Ingest metrics" (`metrics.ingest`) permission set.
It is recommended to limit the scope of the token to this one permission.
* Metric key prefix: sets a prefix that will be prepended to all exported metric keys.
* Enrich with Dynatrace metadata: if a OneAgent or Dynatrace operator is running, enrich metrics with additional metadata (e.g. about the host, process or pod).
* Default dimensions: specify key-value pairs that are added to all exported metrics.
If tags with the same key are specified using Micrometer, they overwrite the default dimensions.
The Dynatrace v1 API metrics registry pushes metrics to the configured URI periodically using the {dynatrace-help}/dynatrace-api/environment-api/metric-v1/[Timeseries v1 API].
For backwards-compatibility with existing setups, when `device-id` is set (required for v1, but not used in v2), metrics will be exported to the Timeseries v1 endpoint.
More information on how to set up the Dynatrace exporter for Micrometer can be found in {micrometer-registry-docs}/dynatrace[the Micrometer documentation].
Micrometer provides a default `HierarchicalNameMapper` that governs how a dimensional meter id is {micrometer-registry-docs}/graphite#_hierarchical_name_mapping[mapped to flat hierarchical names].
By default, metrics are exported to an {micrometer-registry-docs}/influx[Influx] v1 instance running on your local machine with the default configuration.
To export metrics to InfluxDB v2, configure the `org`, `bucket`, and authentication `token` for writing metrics.
The location of the https://www.influxdata.com[Influx server] to use can be provided using:
Micrometer provides a default `HierarchicalNameMapper` that governs how a dimensional meter id is {micrometer-registry-docs}/jmx#_hierarchical_name_mapping[mapped to flat hierarchical names].
Finally, you can take full control by defining your own `NewRelicClientProvider` bean.
[[actuator.metrics.export.prometheus]]
==== Prometheus
{micrometer-registry-docs}/prometheus[Prometheus] expects to scrape or poll individual app instances for metrics.
Spring Boot provides an actuator endpoint available at `/actuator/prometheus` to present a https://prometheus.io[Prometheus scrape] with the appropriate format.
TIP: The endpoint is not available by default and must be exposed, see <<actuator#actuator.endpoints.exposing,exposing endpoints>> for more details.
Here is an example `scrape_config` to add to `prometheus.yml`:
For ephemeral or batch jobs which may not exist long enough to be scraped, https://github.com/prometheus/pushgateway[Prometheus Pushgateway] support can be used to expose their metrics to Prometheus.
To enable Prometheus Pushgateway support, add the following dependency to your project:
When the Prometheus Pushgateway dependency is present on the classpath and the configprop:management.metrics.export.prometheus.pushgateway.enabled[] property is set to `true`, a `PrometheusPushGatewayManager` bean is auto-configured.
This manages the pushing of metrics to a Prometheus Pushgateway.
The `PrometheusPushGatewayManager` can be tuned using properties under `management.metrics.export.prometheus.pushgateway`.
For advanced configuration, you can also provide your own `PrometheusPushGatewayManager` bean.
[[actuator.metrics.export.signalfx]]
==== SignalFx
SignalFx registry pushes metrics to {micrometer-registry-docs}/signalFx[SignalFx] periodically.
To export metrics to https://www.signalfx.com[SignalFx], your access token must be provided:
TIP: If publishing metrics to a Wavefront proxy (as described in https://docs.wavefront.com/proxies_installing.html[the documentation]), the host must be in the `proxy://HOST:PORT` format.
You can also change the interval at which metrics are sent to Wavefront:
Auto-configuration enables the instrumentation of all available `ThreadPoolTaskExecutor` and `ThreadPoolTaskScheduler` beans, as long as the underling `ThreadPoolExecutor` is available.
Metrics are tagged by the name of the executor that is derived from the bean name.
Auto-configuration enables the instrumentation of all requests handled by Spring MVC controllers and functional handlers.
By default, metrics are generated with the name, `http.server.requests`.
The name can be customized by setting the configprop:management.metrics.web.server.request.metric-name[] property.
`@Timed` annotations are supported on `@Controller` classes and `@RequestMapping` methods (see <<actuator#actuator.metrics.supported.timed-annotation>> for details).
If you don't want to record metrics for all Spring MVC requests, you can set configprop:management.metrics.web.server.request.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead.
By default, Spring MVC related metrics are tagged with the following information:
|===
| Tag | Description
| `exception`
| Simple class name of any exception that was thrown while handling the request.
| `method`
| Request's method (for example, `GET` or `POST`)
| `outcome`
| Request's outcome based on the status code of the response.
1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| `status`
| Response's HTTP status code (for example, `200` or `500`)
| `uri`
| Request's URI template prior to variable substitution, if possible (for example, `/api/person/\{id}`)
|===
To add to the default tags, provide one or more ``@Bean``s that implement `WebMvcTagsContributor`.
To replace the default tags, provide a `@Bean` that implements `WebMvcTagsProvider`.
TIP: In some cases, exceptions handled in Web controllers are not recorded as request metrics tags.
Auto-configuration enables the instrumentation of all requests handled by Spring WebFlux controllers and functional handlers.
By default, metrics are generated with the name, `http.server.requests`.
The name can be customized by setting the configprop:management.metrics.web.server.request.metric-name[] property.
`@Timed` annotations are supported on `@Controller` classes and `@RequestMapping` methods (see <<actuator#actuator.metrics.supported.timed-annotation>> for details).
If you don't want to record metrics for all Spring WebFlux requests, you can set configprop:management.metrics.web.server.request.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead.
By default, WebFlux related metrics are tagged with the following information:
|===
| Tag | Description
| `exception`
| Simple class name of any exception that was thrown while handling the request.
| `method`
| Request's method (for example, `GET` or `POST`)
| `outcome`
| Request's outcome based on the status code of the response.
1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| `status`
| Response's HTTP status code (for example, `200` or `500`)
| `uri`
| Request's URI template prior to variable substitution, if possible (for example, `/api/person/\{id}`)
|===
To add to the default tags, provide one or more ``@Bean``s that implement `WebFluxTagsContributor`.
To replace the default tags, provide a `@Bean` that implements `WebFluxTagsProvider`.
TIP: In some cases, exceptions handled in controllers and handler functions are not recorded as request metrics tags.
Auto-configuration enables the instrumentation of all requests handled by the Jersey JAX-RS implementation whenever Micrometer's `micrometer-jersey2` module is on the classpath.
By default, metrics are generated with the name, `http.server.requests`.
The name can be customized by setting the configprop:management.metrics.web.server.request.metric-name[] property.
`@Timed` annotations are supported on request-handling classes and methods (see <<actuator#actuator.metrics.supported.timed-annotation>> for details).
If you don't want to record metrics for all Jersey requests, you can set configprop:management.metrics.web.server.request.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead.
By default, Jersey server metrics are tagged with the following information:
|===
| Tag | Description
| `exception`
| Simple class name of any exception that was thrown while handling the request.
| `method`
| Request's method (for example, `GET` or `POST`)
| `outcome`
| Request's outcome based on the status code of the response.
1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| `status`
| Response's HTTP status code (for example, `200` or `500`)
| `uri`
| Request's URI template prior to variable substitution, if possible (for example, `/api/person/\{id}`)
|===
To customize the tags, provide a `@Bean` that implements `JerseyTagsProvider`.
[[actuator.metrics.supported.http-clients]]
==== HTTP Client Metrics
Spring Boot Actuator manages the instrumentation of both `RestTemplate` and `WebClient`.
For that, you have to inject the auto-configured builder and use it to create instances:
* `RestTemplateBuilder` for `RestTemplate`
* `WebClient.Builder` for `WebClient`
It is also possible to apply manually the customizers responsible for this instrumentation, namely `MetricsRestTemplateCustomizer` and `MetricsWebClientCustomizer`.
By default, metrics are generated with the name, `http.client.requests`.
The name can be customized by setting the configprop:management.metrics.web.client.request.metric-name[] property.
By default, metrics generated by an instrumented client are tagged with the following information:
|===
| Tag | Description
| `clientName`
| Host portion of the URI
| `method`
| Request's method (for example, `GET` or `POST`)
| `outcome`
| Request's outcome based on the status code of the response.
1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`, `UNKNOWN` otherwise
| `status`
| Response's HTTP status code if available (for example, `200` or `500`), or `IO_ERROR` in case of I/O issues, `CLIENT_ERROR` otherwise
| `uri`
| Request's URI template prior to variable substitution, if possible (for example, `/api/person/\{id}`)
|===
To customize the tags, and depending on your choice of client, you can provide a `@Bean` that implements `RestTemplateExchangeTagsProvider` or `WebClientExchangeTagsProvider`.
There are convenience static functions in `RestTemplateExchangeTags` and `WebClientExchangeTags`.
[[actuator.metrics.supported.tomcat]]
==== Tomcat Metrics
Auto-configuration will enable the instrumentation of Tomcat only when an `MBeanRegistry` is enabled.
By default, the `MBeanRegistry` is disabled, but you can enable it by setting configprop:server.tomcat.mbeanregistry.enabled[] to `true`.
Tomcat metrics are published under the `tomcat.` meter name.
[[actuator.metrics.supported.cache]]
==== Cache Metrics
Auto-configuration enables the instrumentation of all available ``Cache``s on startup with metrics prefixed with `cache`.
Cache instrumentation is standardized for a basic set of metrics.
Additional, cache-specific metrics are also available.
The following cache libraries are supported:
* Caffeine
* EhCache 2
* Hazelcast
* Any compliant JCache (JSR-107) implementation
* Redis
Metrics are tagged by the name of the cache and by the name of the `CacheManager` that is derived from the bean name.
NOTE: Only caches that are configured on startup are bound to the registry.
For caches not defined in the cache’s configuration, e.g. caches created on-the-fly or programmatically after the startup phase, an explicit registration is required.
A `CacheMetricsRegistrar` bean is made available to make that process easier.
[[actuator.metrics.supported.jdbc]]
==== DataSource Metrics
Auto-configuration enables the instrumentation of all available `DataSource` objects with metrics prefixed with `jdbc.connections`.
Data source instrumentation results in gauges representing the currently active, idle, maximum allowed, and minimum allowed connections in the pool.
Metrics are also tagged by the name of the `DataSource` computed based on the bean name.
TIP: By default, Spring Boot provides metadata for all supported data sources; you can add additional `DataSourcePoolMetadataProvider` beans if your favorite data source isn't supported out of the box.
See `DataSourcePoolMetadataProvidersConfiguration` for examples.
Also, Hikari-specific metrics are exposed with a `hikaricp` prefix.
Each metric is tagged by the name of the Pool (can be controlled with `spring.datasource.name`).
[[actuator.metrics.supported.hibernate]]
==== Hibernate Metrics
If `org.hibernate:hibernate-micrometer` is on the classpath, all available Hibernate `EntityManagerFactory` instances that have statistics enabled are instrumented with a metric named `hibernate`.
Metrics are also tagged by the name of the `EntityManagerFactory` that is derived from the bean name.
To enable statistics, the standard JPA property `hibernate.generate_statistics` must be set to `true`.
You can enable that on the auto-configured `EntityManagerFactory` as shown in the following example:
Auto-configuration enables the instrumentation of all Spring Data `Repository` method invocations.
By default, metrics are generated with the name, `spring.data.repository.invocations`.
The name can be customized by setting the configprop:management.metrics.data.repository.metric-name[] property.
`@Timed` annotations are supported on `Repository` classes and methods (see <<actuator#actuator.metrics.supported.timed-annotation>> for details).
If you don't want to record metrics for all `Repository` invocations, you can set configprop:management.metrics.data.repository.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead.
By default, repository invocation related metrics are tagged with the following information:
|===
| Tag | Description
| `repository`
| Simple class name of the source `Repository`.
| `method`
| The name of the `Repository` method that was invoked.
| `state`
| The result state (`SUCCESS`, `ERROR`, `CANCELED` or `RUNNING`).
| `exception`
| Simple class name of any exception that was thrown from the invocation.
|===
To replace the default tags, provide a `@Bean` that implements `RepositoryTagsProvider`.
[[actuator.metrics.supported.rabbitmq]]
==== RabbitMQ Metrics
Auto-configuration will enable the instrumentation of all available RabbitMQ connection factories with a metric named `rabbitmq`.
[[actuator.metrics.supported.spring-integration]]
==== Spring Integration Metrics
Spring Integration provides {spring-integration-docs}system-management.html#micrometer-integration[Micrometer support] automatically whenever a `MeterRegistry` bean is available.
Metrics are published under the `spring.integration.` meter name.
[[actuator.metrics.supported.kafka]]
==== Kafka Metrics
Auto-configuration will register a `MicrometerConsumerListener` and `MicrometerProducerListener` for the auto-configured consumer factory and producer factory respectively.
It will also register a `KafkaStreamsMicrometerListener` for `StreamsBuilderFactoryBean`.
For more details refer to {spring-kafka-docs}#micrometer-native[Micrometer Native Metrics] section of the Spring Kafka documentation.
[[actuator.metrics.supported.mongodb]]
==== MongoDB Metrics
[[actuator.metrics.supported.mongodb.command]]
===== Command Metrics
Auto-configuration will register a `MongoMetricsCommandListener` with the auto-configured `MongoClient`.
A timer metric with the name `mongodb.driver.commands` is created for each command issued to the underlying MongoDB driver.
Each metric is tagged with the following information by default:
|===
| Tag | Description
| `command`
| Name of the command issued
| `cluster.id`
| Identifier of the cluster the command was sent to
| `server.address`
| Address of the server the command was sent to
| `status`
| Outcome of the command - one of (`SUCCESS`, `FAILED`)
|===
To replace the default metric tags, define a `MongoCommandTagsProvider` bean, as shown in the following example:
Metrics for Jetty's ``Connector``s are bound using Micrometer's `JettyConnectionMetrics` and, in addition when configprop:server.ssl.enabled[] is set to `true`, Micrometer's `JettySslHandshakeMetrics`.
Using a `MeterBinder` ensures that the correct dependency relationships are set up and that the bean is available when the metric's value is retrieved.
A `MeterBinder` implementation can also be useful if you find that you repeatedly instrument a suite of metrics across components or applications.
NOTE: By default, metrics from all `MeterBinder` beans will be automatically bound to the Spring-managed `MeterRegistry`.
[[actuator.metrics.customizing]]
=== Customizing Individual Metrics
If you need to apply customizations to specific `Meter` instances you can use the `io.micrometer.core.instrument.config.MeterFilter` interface.
For example, if you want to rename the `mytag.region` tag to `mytag.area` for all meter IDs beginning with `com.example`, you can do the following:
| Publish a cumulative histogram with buckets defined by your service-level objectives.
|===
For more details on concepts behind `percentiles-histogram`, `percentiles` and `slo` refer to the {micrometer-concepts-docs}#_histograms_and_percentiles["Histograms and percentiles" section] of the micrometer documentation.
[[actuator.metrics.endpoint]]
=== Metrics Endpoint
Spring Boot provides a `metrics` endpoint that can be used diagnostically to examine the metrics collected by an application.
The endpoint is not available by default and must be exposed, see <<actuator#actuator.endpoints.exposing,exposing endpoints>> for more details.
Navigating to `/actuator/metrics` displays a list of available meter names.
You can drill down to view information about a particular meter by providing its name as a selector, e.g. `/actuator/metrics/jvm.memory.max`.
[TIP]
====
The name you use here should match the name used in the code, not the name after it has been naming-convention normalized for a monitoring system it is shipped to.
In other words, if `jvm.memory.max` appears as `jvm_memory_max` in Prometheus because of its snake case naming convention, you should still use `jvm.memory.max` as the selector when inspecting the meter in the `metrics` endpoint.
====
You can also add any number of `tag=KEY:VALUE` query parameters to the end of the URL to dimensionally drill down on a meter, e.g. `/actuator/metrics/jvm.memory.max?tag=area:nonheap`.
[TIP]
====
The reported measurements are the _sum_ of the statistics of all meters matching the meter name and any tags that have been applied.
So in the example above, the returned "Value" statistic is the sum of the maximum memory footprints of "Code Cache", "Compressed Class Space", and "Metaspace" areas of the heap.
If you only wanted to see the maximum size for the "Metaspace", you could add an additional `tag=id:Metaspace`, i.e. `/actuator/metrics/jvm.memory.max?tag=area:nonheap&tag=id:Metaspace`.
