spring-boot/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/metrics.adoc

[[actuator.metrics]]
== Metrics
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:

- <<actuator#actuator.metrics.export.appoptics,AppOptics>>
- <<actuator#actuator.metrics.export.atlas,Atlas>>
- <<actuator#actuator.metrics.export.datadog,Datadog>>
- <<actuator#actuator.metrics.export.dynatrace,Dynatrace>>
- <<actuator#actuator.metrics.export.elastic,Elastic>>
- <<actuator#actuator.metrics.export.ganglia,Ganglia>>
- <<actuator#actuator.metrics.export.graphite,Graphite>>
- <<actuator#actuator.metrics.export.humio,Humio>>
- <<actuator#actuator.metrics.export.influx,Influx>>
- <<actuator#actuator.metrics.export.jmx,JMX>>
- <<actuator#actuator.metrics.export.kairos,KairosDB>>
- <<actuator#actuator.metrics.export.newrelic,New Relic>>
- <<actuator#actuator.metrics.export.prometheus,Prometheus>>
- <<actuator#actuator.metrics.export.signalfx,SignalFx>>
- <<actuator#actuator.metrics.export.simple,Simple (in-memory)>>
- <<actuator#actuator.metrics.export.stackdriver,Stackdriver>>
- <<actuator#actuator.metrics.export.statsd,StatsD>>
- <<actuator#actuator.metrics.export.wavefront,Wavefront>>

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.
For example, to disable Datadog:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      datadog:
	        enabled: false
----

You can also disable all registries unless stated otherwise by the registry-specific property, as shown in the following example:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      defaults:
	        enabled: false
----

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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    use-global-registry: false
----

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:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/gettingstarted/commontags/MyMeterRegistryConfiguration.java[]
----

You can apply customizations to particular registry implementations by being more specific about the generic type:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/gettingstarted/specifictype/MyMeterRegistryConfiguration.java[]
----

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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      appoptics:
	        api-token: "YOUR_TOKEN"
----



[[actuator.metrics.export.atlas]]
==== Atlas
By default, metrics are exported to {micrometer-registry-docs}/atlas[Atlas] running on your local machine.
The location of the https://github.com/Netflix/atlas[Atlas server] to use can be provided using:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      atlas:
	        uri: "https://atlas.example.com:7101/api/v1/publish"
----



[[actuator.metrics.export.datadog]]
==== Datadog
Datadog registry pushes metrics to https://www.datadoghq.com[datadoghq] periodically.
To export metrics to {micrometer-registry-docs}/datadog[Datadog], your API key must be provided:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      datadog:
	        api-key: "YOUR_KEY"
----

You can also change the interval at which metrics are sent to Datadog:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      datadog:
	        step: "30s"
----



[[actuator.metrics.export.dynatrace]]
==== Dynatrace
Dynatrace registry pushes metrics to the configured URI periodically.
To export metrics to {micrometer-registry-docs}/dynatrace[Dynatrace], your API token, device ID, and URI must be provided:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      dynatrace:
	        api-token: "YOUR_TOKEN"
	        device-id: "YOUR_DEVICE_ID"
	        uri: "YOUR_URI"
----

You can also change the interval at which metrics are sent to Dynatrace:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      dynatrace:
	        step: "30s"
----



[[actuator.metrics.export.elastic]]
==== Elastic
By default, metrics are exported to {micrometer-registry-docs}/elastic[Elastic] running on your local machine.
The location of the Elastic server to use can be provided using the following property:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      elastic:
	        host: "https://elastic.example.com:8086"
----



[[actuator.metrics.export.ganglia]]
==== Ganglia
By default, metrics are exported to {micrometer-registry-docs}/ganglia[Ganglia] running on your local machine.
The http://ganglia.sourceforge.net[Ganglia server] host and port to use can be provided using:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      ganglia:
	        host: "ganglia.example.com"
	        port: 9649
----



[[actuator.metrics.export.graphite]]
==== Graphite
By default, metrics are exported to {micrometer-registry-docs}/graphite[Graphite] running on your local machine.
The https://graphiteapp.org[Graphite server] host and port to use can be provided using:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	     export:
	       graphite:
	         host: "graphite.example.com"
	         port: 9004
----

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].

TIP: To take control over this behavior, define your `GraphiteMeterRegistry` and supply your own `HierarchicalNameMapper`.
An auto-configured `GraphiteConfig` and `Clock` beans are provided unless you define your own:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/export/graphite/MyGraphiteConfiguration.java[]
----



[[actuator.metrics.export.humio]]
==== Humio
By default, the Humio registry pushes metrics to https://cloud.humio.com periodically.
To export metrics to SaaS {micrometer-registry-docs}/humio[Humio], your API token must be provided:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      humio:
	        api-token: "YOUR_TOKEN"
----

You should also configure one or more tags to identify the data source to which metrics will be pushed:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      humio:
	        tags:
	          alpha: "a"
	          bravo: "b"
----



[[actuator.metrics.export.influx]]
==== Influx
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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      influx:
	        uri: "https://influx.example.com:8086"
----



[[actuator.metrics.export.jmx]]
==== JMX
Micrometer provides a hierarchical mapping to {micrometer-registry-docs}/jmx[JMX], primarily as a cheap and portable way to view metrics locally.
By default, metrics are exported to the `metrics` JMX domain.
The domain to use can be provided using:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      jmx:
	        domain: "com.example.app.metrics"
----

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].

TIP: To take control over this behavior, define your `JmxMeterRegistry` and supply your own `HierarchicalNameMapper`.
An auto-configured `JmxConfig` and `Clock` beans are provided unless you define your own:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/export/jmx/MyJmxConfiguration.java[]
----



[[actuator.metrics.export.kairos]]
==== KairosDB
By default, metrics are exported to {micrometer-registry-docs}/kairos[KairosDB] running on your local machine.
The location of the https://kairosdb.github.io/[KairosDB server] to use can be provided using:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      kairos:
	        uri: "https://kairosdb.example.com:8080/api/v1/datapoints"
----



[[actuator.metrics.export.newrelic]]
==== New Relic
New Relic registry pushes metrics to {micrometer-registry-docs}/new-relic[New Relic] periodically.
To export metrics to https://newrelic.com[New Relic], your API key and account id must be provided:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      newrelic:
	        api-key: "YOUR_KEY"
	        account-id: "YOUR_ACCOUNT_ID"
----

You can also change the interval at which metrics are sent to New Relic:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      newrelic:
	        step: "30s"
----

By default, metrics are published via REST calls but it is also possible to use the Java Agent API if you have it on the classpath:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      newrelic:
	        client-provider-type: "insights-agent"
----

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`:

[source,yaml,indent=0,subs="verbatim"]
----
	scrape_configs:
	  - job_name: 'spring'
		metrics_path: '/actuator/prometheus'
		static_configs:
		  - targets: ['HOST:PORT']
----

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:

[source,xml,indent=0,subs="verbatim"]
----
<dependency>
	<groupId>io.prometheus</groupId>
	<artifactId>simpleclient_pushgateway</artifactId>
</dependency>
----

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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      signalfx:
	        access-token: "YOUR_ACCESS_TOKEN"
----

You can also change the interval at which metrics are sent to SignalFx:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      signalfx:
	        step: "30s"
----



[[actuator.metrics.export.simple]]
==== Simple
Micrometer ships with a simple, in-memory backend that is automatically used as a fallback if no other registry is configured.
This allows you to see what metrics are collected in the <<actuator#actuator.metrics.endpoint,metrics endpoint>>.

The in-memory backend disables itself as soon as you're using any of the other available backend.
You can also disable it explicitly:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      simple:
	        enabled: false
----



[[actuator.metrics.export.stackdriver]]
==== Stackdriver
Stackdriver registry pushes metrics to https://cloud.google.com/stackdriver/[Stackdriver] periodically.
To export metrics to SaaS {micrometer-registry-docs}/stackdriver[Stackdriver], your Google Cloud project id must be provided:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      stackdriver:
	        project-id: "my-project"
----

You can also change the interval at which metrics are sent to Stackdriver:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      stackdriver:
	        step: "30s"
----



[[actuator.metrics.export.statsd]]
==== StatsD
The StatsD registry pushes metrics over UDP to a StatsD agent eagerly.
By default, metrics are exported to a {micrometer-registry-docs}/statsD[StatsD] agent running on your local machine.
The StatsD agent host, port, and protocol to use can be provided using:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      statsd:
	        host: "statsd.example.com"
	        port: 9125
	        protocol: "udp"
----

You can also change the StatsD line protocol to use (default to Datadog):

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      statsd:
	        flavor: "etsy"
----



[[actuator.metrics.export.wavefront]]
==== Wavefront
Wavefront registry pushes metrics to {micrometer-registry-docs}/wavefront[Wavefront] periodically.
If you are exporting metrics to https://www.wavefront.com/[Wavefront] directly, your API token must be provided:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      wavefront:
	        api-token: "YOUR_API_TOKEN"
----

Alternatively, you may use a Wavefront sidecar or an internal proxy set up in your environment that forwards metrics data to the Wavefront API host:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      wavefront:
	        uri: "proxy://localhost:2878"
----

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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    export:
	      wavefront:
	        step: "30s"
----



[[actuator.metrics.supported]]
=== Supported Metrics and Meters
Spring Boot provides automatic meter registration for a wide variety of technologies.
In most situations, the out-of-the-box defaults will provide sensible metrics that can be published to any of the supported monioring systems.



[[actuator.metrics.supported.jvm]]
==== JVM Metrics
Auto-configuration will enable JVM Metrics using core Micrometer classes.
JVM metrics are published under the `jvm.` meter name.

The following JVM metrics are provided:

* Various memory and buffer pool details
* Statistics related to garbage collection
* Threads utilization
* The Number of classes loaded/unloaded



[[actuator.metrics.supported.system]]
==== System Metrics
Auto-configuration will enable system metrics using core Micrometer classes.
System metrics are published under the `system.` and `process.` meter names.

The following system metrics are provided:

* CPU metrics
* File descriptor metrics
* Uptime metrics (both the amount of time the application has been running as well as a fixed gauge of the absolute start time)



[[actuator.metrics.supported.logger]]
==== Logger Metrics
Auto-configuration enables the event metrics for both Logback and Log4J2.
Details are published under the `log4j2.events.` or `logback.events.` meter names.



[[actuator.metrics.supported.spring-mvc]]
==== Spring MVC Metrics
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.
Applications can opt-in and record exceptions by <<features#features.developing-web-applications.spring-mvc.error-handling, setting handled exceptions as request attributes>>.



[[actuator.metrics.supported.spring-webflux]]
==== Spring WebFlux Metrics
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.
Applications can opt-in and record exceptions by <<features#features.developing-web-applications.spring-webflux.error-handling, setting handled exceptions as request attributes>>.



[[actuator.metrics.supported.jersey]]
==== Jersey Server Metrics
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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  jpa:
	    properties:
	      "[hibernate.generate_statistics]": true
----



[[actuator.metrics.supported.spring-data-repository]]
==== Spring Data Repository Metrics
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:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/supported/mongodb/command/MyCommandTagsProviderConfiguration.java[]
----

To disable the auto-configured command metrics, set the following property:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    mongo:
	      command:
	        enabled: false
----



[[actuator.metrics.supported.mongodb.connection-pool]]
===== Connection Pool Metrics
Auto-configuration will register a `MongoMetricsConnectionPoolListener` with the auto-configured `MongoClient`.

The following gauge metrics are created for the connection pool:

* `mongodb.driver.pool.size` that reports the current size of the connection pool, including idle and and in-use members
* `mongodb.driver.pool.checkedout` that reports the count of connections that are currently in use
* `mongodb.driver.pool.waitqueuesize` that reports the current size of the wait queue for a connection from the pool

Each metric is tagged with the following information by default:
|===
| Tag | Description

| `cluster.id`
| Identifier of the cluster the connection pool corresponds to

| `server.address`
| Address of the server the connection pool corresponds to
|===

To replace the default metric tags, define a `MongoConnectionPoolTagsProvider` bean, as shown in the following example:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/supported/mongodb/connectionpool/MyConnectionPoolTagsProviderConfiguration.java[]
----

To disable the auto-configured connection pool metrics, set the following property:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    mongo:
	      connectionpool:
	        enabled: false
----



[[actuator.metrics.supported.jetty]]
==== Jetty Metrics
Auto-configuration will bind metrics for Jetty's `ThreadPool` using Micrometer's `JettyServerThreadPoolMetrics`.



[[actuator.metrics.supported.timed-annotation]]
==== @Timed Annotation Support
The `@Timed` annotation from the `io.micrometer.core.annotation` package can be used with several of the supported technologies listed above.
If supported, the annotation can be used either at the class-level or the method-level.

For example, the following code shows how the annotation can be used to instrument all request mappings in a `@RestController`:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/supported/timedannotation/all/MyController.java[]
----

If you only want to instrument a single mapping, you can use the annotation on the method instead of the class:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/supported/timedannotation/single/MyController.java[]
----

You can also combine class-level and method-level annotations if you want to change timing details for a specific method:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/supported/timedannotation/change/MyController.java[]
----

NOTE: A `@Timed` annotation with `longTask = true` will enable a long task timer for the method.
Long task timers require a separate metric name, and can be stacked with a short task timer.



[[actuator.metrics.registering-custom]]
=== Registering Custom Metrics
To register custom metrics, inject `MeterRegistry` into your component, as shown in the following example:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/registeringcustom/MyBean.java[]
----

If your metrics depend on other beans, it is recommended that you use a `MeterBinder` to register them, as shown in the following example:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/registeringcustom/MyMeterBinderConfiguration.java[]
----

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:

[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/customizing/MyMetricsFilterConfiguration.java[]
----

NOTE: By default, all `MeterFilter` beans will be automatically bound to the Spring-managed `MeterRegistry`.
Make sure to register your metrics using the Spring-managed `MeterRegistry` and not any of the static methods on `Metrics`.
These use the global registry that is not Spring-managed.



[[actuator.metrics.customizing.common-tags]]
==== Common Tags
Common tags are generally used for dimensional drill-down on the operating environment like host, instance, region, stack, etc.
Commons tags are applied to all meters and can be configured as shown in the following example:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    tags:
	      region: "us-east-1"
	      stack: "prod"
----

The example above adds `region` and `stack` tags to all meters with a value of `us-east-1` and `prod` respectively.

NOTE: The order of common tags is important if you are using Graphite.
As the order of common tags cannot be guaranteed using this approach, Graphite users are advised to define a custom `MeterFilter` instead.



[[actuator.metrics.customizing.per-meter-properties]]
==== Per-meter Properties
In addition to `MeterFilter` beans, it's also possible to apply a limited set of customization on a per-meter basis using properties.
Per-meter customizations apply to any all meter IDs that start with the given name.
For example, the following will disable any meters that have an ID starting with `example.remote`

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  metrics:
	    enable:
	      example:
	        remote: false
----

The following properties allow per-meter customization:

.Per-meter customizations
|===
| Property | Description

| configprop:management.metrics.enable[]
| Whether to deny meters from emitting any metrics.

| configprop:management.metrics.distribution.percentiles-histogram[]
| Whether to publish a histogram suitable for computing aggregable (across dimension) percentile approximations.

| configprop:management.metrics.distribution.minimum-expected-value[], configprop:management.metrics.distribution.maximum-expected-value[]
| Publish less histogram buckets by clamping the range of expected values.

| configprop:management.metrics.distribution.percentiles[]
| Publish percentile values computed in your application

| configprop:management.metrics.distribution.slo[]
| 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`.
====