1107 lines
39 KiB
Plaintext
1107 lines
39 KiB
Plaintext
[[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`.
|
||
====
|