1756 lines
62 KiB
Plaintext
1756 lines
62 KiB
Plaintext
[[production-ready]]
|
|
= Spring Boot Actuator: Production-ready features
|
|
|
|
[partintro]
|
|
--
|
|
Spring Boot includes a number of additional features to help you monitor and manage your
|
|
application when it's pushed to production. You can choose to manage and monitor your
|
|
application using HTTP endpoints, with JMX or even by remote shell (SSH or Telnet).
|
|
Auditing, health and metrics gathering can be automatically applied to your application.
|
|
|
|
Actuator HTTP endpoints are only available with a Spring MVC-based application. In
|
|
particular, it will not work with Jersey <<howto.adoc#howto-use-actuator-with-jersey,
|
|
unless you enable Spring MVC as well.>>
|
|
--
|
|
|
|
|
|
|
|
[[production-ready-enabling]]
|
|
== Enabling production-ready features
|
|
The {github-code}/spring-boot-actuator[`spring-boot-actuator`] module provides all of
|
|
Spring Boot's production-ready features. The simplest way to enable the features is to add
|
|
a dependency to the `spring-boot-starter-actuator` '`Starter`'.
|
|
|
|
.Definition of Actuator
|
|
****
|
|
An actuator is a manufacturing term, referring to a mechanical device for moving or
|
|
controlling something. Actuators can generate a large amount of motion from a small
|
|
change.
|
|
****
|
|
|
|
To add the actuator to a Maven based project, add the following '`Starter`'
|
|
dependency:
|
|
|
|
[source,xml,indent=0]
|
|
----
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-actuator</artifactId>
|
|
</dependency>
|
|
</dependencies>
|
|
----
|
|
|
|
For Gradle, use the declaration:
|
|
|
|
[source,groovy,indent=0]
|
|
----
|
|
dependencies {
|
|
compile("org.springframework.boot:spring-boot-starter-actuator")
|
|
}
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-endpoints]]
|
|
== Endpoints
|
|
Actuator endpoints allow you to monitor and interact with your application. Spring Boot
|
|
includes a number of built-in endpoints and you can also add your own. For example the
|
|
`health` endpoint provides basic application health information.
|
|
|
|
The way that endpoints are exposed will depend on the type of technology that you choose.
|
|
Most applications choose HTTP monitoring, where the ID of the endpoint is mapped
|
|
to a URL. For example, by default, the `health` endpoint will be mapped to `/health`.
|
|
|
|
The following technology agnostic endpoints are available:
|
|
|
|
[cols="2,5,1"]
|
|
|===
|
|
| ID | Description | Sensitive Default
|
|
|
|
|`actuator`
|
|
|Provides a hypermedia-based "`discovery page`" for the other endpoints. Requires Spring
|
|
HATEOAS to be on the classpath.
|
|
|true
|
|
|
|
|`auditevents`
|
|
|Exposes audit events information for the current application.
|
|
|true
|
|
|
|
|`autoconfig`
|
|
|Displays an auto-configuration report showing all auto-configuration candidates and the
|
|
reason why they '`were`' or '`were not`' applied.
|
|
|true
|
|
|
|
|`beans`
|
|
|Displays a complete list of all the Spring beans in your application.
|
|
|true
|
|
|
|
|`configprops`
|
|
|Displays a collated list of all `@ConfigurationProperties`.
|
|
|true
|
|
|
|
|`dump`
|
|
|Performs a thread dump.
|
|
|true
|
|
|
|
|`env`
|
|
|Exposes properties from Spring's `ConfigurableEnvironment`.
|
|
|true
|
|
|
|
|`flyway`
|
|
|Shows any Flyway database migrations that have been applied.
|
|
|true
|
|
|
|
|`health`
|
|
|Shows application health information (when the application is secure, a simple '`status`'
|
|
when accessed over an unauthenticated connection or full message details when
|
|
authenticated).
|
|
|false
|
|
|
|
|`info`
|
|
|Displays arbitrary application info.
|
|
|false
|
|
|
|
|`loggers`
|
|
|Shows and modifies the configuration of loggers in the application.
|
|
|true
|
|
|
|
|`liquibase`
|
|
|Shows any Liquibase database migrations that have been applied.
|
|
|true
|
|
|
|
|`metrics`
|
|
|Shows '`metrics`' information for the current application.
|
|
|true
|
|
|
|
|`mappings`
|
|
|Displays a collated list of all `@RequestMapping` paths.
|
|
|true
|
|
|
|
|`shutdown`
|
|
|Allows the application to be gracefully shutdown (not enabled by default).
|
|
|true
|
|
|
|
|`trace`
|
|
|Displays trace information (by default the last 100 HTTP requests).
|
|
|true
|
|
|===
|
|
|
|
If you are using Spring MVC, the following additional endpoints can also be used:
|
|
|
|
[cols="2,5,1"]
|
|
|===
|
|
| ID | Description | Sensitive Default
|
|
|
|
|`docs`
|
|
|Displays documentation, including example requests and responses, for the Actuator's
|
|
endpoints. Requires `spring-boot-actuator-docs` to be on the classpath.
|
|
|false
|
|
|
|
|`heapdump`
|
|
|Returns a GZip compressed `hprof` heap dump file.
|
|
|true
|
|
|
|
|`jolokia`
|
|
|Exposes JMX beans over HTTP (when Jolokia is on the classpath).
|
|
|true
|
|
|
|
|`logfile`
|
|
|Returns the contents of the logfile (if `logging.file` or `logging.path` properties have
|
|
been set). Supports the use of the HTTP `Range` header to retrieve part of the log file's
|
|
content.
|
|
|true
|
|
|===
|
|
|
|
NOTE: Depending on how an endpoint is exposed, the `sensitive` property may be used as
|
|
a security hint. For example, sensitive endpoints will require a username/password when
|
|
they are accessed over HTTP (or simply disabled if web security is not enabled).
|
|
|
|
|
|
|
|
[[production-ready-customizing-endpoints]]
|
|
=== Customizing endpoints
|
|
Endpoints can be customized using Spring properties. You can change if an endpoint is
|
|
`enabled`, if it is considered `sensitive` and even its `id`.
|
|
|
|
For example, here is an `application.properties` that changes the sensitivity and id
|
|
of the `beans` endpoint and also enables `shutdown`.
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
endpoints.beans.id=springbeans
|
|
endpoints.beans.sensitive=false
|
|
endpoints.shutdown.enabled=true
|
|
----
|
|
|
|
NOTE: The prefix ‟`endpoints` + `.` + `name`” is used to uniquely identify the endpoint
|
|
that is being configured.
|
|
|
|
By default, all endpoints except for `shutdown` are enabled. If you prefer to
|
|
specifically "`opt-in`" endpoint enablement you can use the `endpoints.enabled` property.
|
|
For example, the following will disable _all_ endpoints except for `info`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
endpoints.enabled=false
|
|
endpoints.info.enabled=true
|
|
----
|
|
|
|
Likewise, you can also choose to globally set the "`sensitive`" flag of all endpoints. By
|
|
default, the sensitive flag depends on the type of endpoint (see the table above).
|
|
For example, to mark _all_ endpoints as sensitive except `info`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
endpoints.sensitive=true
|
|
endpoints.info.sensitive=false
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-endpoint-hypermedia]]
|
|
=== Hypermedia for actuator MVC endpoints
|
|
If `endpoints.hypermedia.enabled` is set to `true` and
|
|
http://projects.spring.io/spring-hateoas[Spring HATEOAS] is on the classpath (e.g.
|
|
through the `spring-boot-starter-hateoas` or if you are using
|
|
http://projects.spring.io/spring-data-rest[Spring Data REST]) then the HTTP endpoints
|
|
from the Actuator are enhanced with hypermedia links, and a "`discovery page`" is added
|
|
with links to all the endpoints. The "`discovery page`" is available on `/actuator` by
|
|
default. It is implemented as an endpoint, allowing properties to be used to configure
|
|
its path (`endpoints.actuator.path`) and whether or not it is enabled
|
|
(`endpoints.actuator.enabled`).
|
|
|
|
When a custom management context path is configured, the "`discovery page`" will
|
|
automatically move from `/actuator` to the root of the management context. For example,
|
|
if the management context path is `/management` then the discovery page will be available
|
|
from `/management`.
|
|
|
|
If the https://github.com/mikekelly/hal-browser[HAL Browser] is on the classpath
|
|
via its webjar (`org.webjars:hal-browser`), or via the `spring-data-rest-hal-browser` then
|
|
an HTML "`discovery page`", in the form of the HAL Browser, is also provided.
|
|
|
|
|
|
|
|
[[production-ready-endpoint-cors]]
|
|
=== CORS support
|
|
http://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing]
|
|
(CORS) is a http://www.w3.org/TR/cors/[W3C specification] that allows you to specify in a
|
|
flexible way what kind of cross domain requests are authorized. Actuator's MVC endpoints
|
|
can be configured to support such scenarios.
|
|
|
|
CORS support is disabled by default and is only enabled once the
|
|
`endpoints.cors.allowed-origins` property has been set. The configuration below permits
|
|
`GET` and `POST` calls from the `example.com` domain:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
endpoints.cors.allowed-origins=http://example.com
|
|
endpoints.cors.allowed-methods=GET,POST
|
|
----
|
|
|
|
TIP: Check {sc-spring-boot-actuator}/autoconfigure/EndpointCorsProperties.{sc-ext}[EndpointCorsProperties]
|
|
for a complete list of options.
|
|
|
|
|
|
|
|
[[production-ready-customizing-endpoints-programmatically]]
|
|
=== Adding custom endpoints
|
|
If you add a `@Bean` of type `Endpoint` then it will automatically be exposed over JMX and
|
|
HTTP (if there is an server available). An HTTP endpoints can be customized further by
|
|
creating a bean of type `MvcEndpoint`. Your `MvcEndpoint` is not a `@Controller` but it
|
|
can use `@RequestMapping` (and `@Managed*`) to expose resources.
|
|
|
|
TIP: If you are doing this as a library feature consider adding a configuration class
|
|
annotated with `@ManagementContextConfiguration` to `/META-INF/spring.factories` under the
|
|
key `org.springframework.boot.actuate.autoconfigure.ManagementContextConfiguration`. If
|
|
you do that then the endpoint will move to a child context with all the other MVC
|
|
endpoints if your users ask for a separate management port or address. A configuration
|
|
declared this way can be a `WebConfigurerAdapter` if it wants to add static resources (for
|
|
instance) to the management endpoints.
|
|
|
|
|
|
|
|
[[production-ready-health]]
|
|
=== Health information
|
|
Health information can be used to check the status of your running application. It is
|
|
often used by monitoring software to alert someone if a production system goes down.
|
|
The default information exposed by the `health` endpoint depends on how it is accessed.
|
|
For an unauthenticated connection in a secure application a simple '`status`' message is
|
|
returned, and for an authenticated connection additional details are also displayed (see
|
|
<<production-ready-health-access-restrictions>> for HTTP details).
|
|
|
|
Health information is collected from all
|
|
{sc-spring-boot-actuator}/health/HealthIndicator.{sc-ext}[`HealthIndicator`] beans defined
|
|
in your `ApplicationContext`. Spring Boot includes a number of auto-configured
|
|
`HealthIndicators` and you can also write your own. By default, the final system state is
|
|
derived by the `HealthAggregator` which sorts the statuses from each `HealthIndicator`
|
|
based on an ordered list of statuses. The first status in the sorted list is used as the
|
|
overall health status. If no `HealthIndicator` returns a status that is known to the
|
|
`HealthAggregator`, an `UNKNOWN` status is used.
|
|
|
|
|
|
|
|
=== Security with HealthIndicators
|
|
Information returned by `HealthIndicators` is often somewhat sensitive in nature. For
|
|
example, you probably don't want to publish details of your database server to the
|
|
world. For this reason, by default, only the health status is exposed over an
|
|
unauthenticated HTTP connection. If you are happy for complete health information to always
|
|
be exposed you can set `endpoints.health.sensitive` to `false`.
|
|
|
|
Health responses are also cached to prevent "`denial of service`" attacks. Use the
|
|
`endpoints.health.time-to-live` property if you want to change the default cache period
|
|
of 1000 milliseconds.
|
|
|
|
|
|
|
|
==== Auto-configured HealthIndicators
|
|
The following `HealthIndicators` are auto-configured by Spring Boot when appropriate:
|
|
|
|
[cols="1,4"]
|
|
|===
|
|
|Name |Description
|
|
|
|
|{sc-spring-boot-actuator}/health/CassandraHealthIndicator.{sc-ext}[`CassandraHealthIndicator`]
|
|
|Checks that a Cassandra database is up.
|
|
|
|
|{sc-spring-boot-actuator}/health/DiskSpaceHealthIndicator.{sc-ext}[`DiskSpaceHealthIndicator`]
|
|
|Checks for low disk space.
|
|
|
|
|{sc-spring-boot-actuator}/health/DataSourceHealthIndicator.{sc-ext}[`DataSourceHealthIndicator`]
|
|
|Checks that a connection to `DataSource` can be obtained.
|
|
|
|
|{sc-spring-boot-actuator}/health/ElasticsearchHealthIndicator.{sc-ext}[`ElasticsearchHealthIndicator`]
|
|
|Checks that an Elasticsearch cluster is up.
|
|
|
|
|{sc-spring-boot-actuator}/health/JmsHealthIndicator.{sc-ext}[`JmsHealthIndicator`]
|
|
|Checks that a JMS broker is up.
|
|
|
|
|{sc-spring-boot-actuator}/health/MailHealthIndicator.{sc-ext}[`MailHealthIndicator`]
|
|
|Checks that a mail server is up.
|
|
|
|
|{sc-spring-boot-actuator}/health/MongoHealthIndicator.{sc-ext}[`MongoHealthIndicator`]
|
|
|Checks that a Mongo database is up.
|
|
|
|
|{sc-spring-boot-actuator}/health/RabbitHealthIndicator.{sc-ext}[`RabbitHealthIndicator`]
|
|
|Checks that a Rabbit server is up.
|
|
|
|
|{sc-spring-boot-actuator}/health/RedisHealthIndicator.{sc-ext}[`RedisHealthIndicator`]
|
|
|Checks that a Redis server is up.
|
|
|
|
|{sc-spring-boot-actuator}/health/SolrHealthIndicator.{sc-ext}[`SolrHealthIndicator`]
|
|
|Checks that a Solr server is up.
|
|
|===
|
|
|
|
TIP: It is possible to disable them all using the `management.health.defaults.enabled`
|
|
property.
|
|
|
|
|
|
==== Writing custom HealthIndicators
|
|
To provide custom health information you can register Spring beans that implement the
|
|
{sc-spring-boot-actuator}/health/HealthIndicator.{sc-ext}[`HealthIndicator`] interface.
|
|
You need to provide an implementation of the `health()` method and return a `Health`
|
|
response. The `Health` response should include a status and can optionally include
|
|
additional details to be displayed.
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
import org.springframework.boot.actuate.health.Health;
|
|
import org.springframework.boot.actuate.health.HealthIndicator;
|
|
import org.springframework.stereotype.Component;
|
|
|
|
@Component
|
|
public class MyHealthIndicator implements HealthIndicator {
|
|
|
|
@Override
|
|
public Health health() {
|
|
int errorCode = check(); // perform some specific health check
|
|
if (errorCode != 0) {
|
|
return Health.down().withDetail("Error Code", errorCode).build();
|
|
}
|
|
return Health.up().build();
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
NOTE: The identifier for a given `HealthIndicator` is the name of the bean without the
|
|
`HealthIndicator` suffix if it exists. In the example above, the health information will
|
|
be available in an entry named `my`.
|
|
|
|
In addition to Spring Boot's predefined {sc-spring-boot-actuator}/health/Status.{sc-ext}[`Status`]
|
|
types, it is also possible for `Health` to return a custom `Status` that represents a
|
|
new system state. In such cases a custom implementation of the
|
|
{sc-spring-boot-actuator}/health/HealthAggregator.{sc-ext}[`HealthAggregator`]
|
|
interface also needs to be provided, or the default implementation has to be configured
|
|
using the `management.health.status.order` configuration property.
|
|
|
|
For example, assuming a new `Status` with code `FATAL` is being used in one of your
|
|
`HealthIndicator` implementations. To configure the severity order add the following
|
|
to your application properties:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
management.health.status.order=FATAL, DOWN, OUT_OF_SERVICE, UNKNOWN, UP
|
|
----
|
|
|
|
The HTTP status code in the response reflects the overall health status (e.g. `UP`
|
|
maps to 200, `OUT_OF_SERVICE` or `DOWN` to 503). You might also want to register custom
|
|
status mappings with the `HealthMvcEndpoint` if you access the health endpoint over HTTP.
|
|
For example, the following maps `FATAL` to 503 (service unavailable):
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
endpoints.health.mapping.FATAL=503
|
|
----
|
|
|
|
The default status mappings for the built-in statuses are:
|
|
|
|
[cols="1,3"]
|
|
|===
|
|
|Status |Mapping
|
|
|
|
|DOWN
|
|
|SERVICE_UNAVAILABLE (503)
|
|
|
|
|OUT_OF_SERVICE
|
|
|SERVICE_UNAVAILABLE (503)
|
|
|
|
|UP
|
|
|No mapping by default, so http status is 200
|
|
|
|
|UNKNOWN
|
|
|No mapping by default, so http status is 200
|
|
|===
|
|
|
|
|
|
|
|
[[production-ready-application-info]]
|
|
=== Application information
|
|
Application information exposes various information collected from all
|
|
{sc-spring-boot-actuator}/info/InfoContributor.{sc-ext}[`InfoContributor`] beans defined
|
|
in your `ApplicationContext`. Spring Boot includes a number of auto-configured
|
|
`InfoContributors` and you can also write your own.
|
|
|
|
[[production-ready-application-info-autoconfigure]]
|
|
==== Auto-configured InfoContributors
|
|
|
|
The following `InfoContributors` are auto-configured by Spring Boot when appropriate:
|
|
|
|
[cols="1,4"]
|
|
|===
|
|
|Name |Description
|
|
|
|
|{sc-spring-boot-actuator}/info/EnvironmentInfoContributor.{sc-ext}[`EnvironmentInfoContributor`]
|
|
|Expose any key from the `Environment` under the `info` key.
|
|
|
|
|{sc-spring-boot-actuator}/info/GitInfoContributor.{sc-ext}[`GitInfoContributor`]
|
|
|Expose git information if a `git.properties` file is available.
|
|
|
|
|{sc-spring-boot-actuator}/info/BuildInfoContributor.{sc-ext}[`BuildInfoContributor`]
|
|
|Expose build information if a `META-INF/build-info.properties` file is available.
|
|
|===
|
|
|
|
TIP: It is possible to disable them all using the `management.info.defaults.enabled`
|
|
property.
|
|
|
|
[[production-ready-application-info-env]]
|
|
==== Custom application info information
|
|
You can customize the data exposed by the `info` endpoint by setting `+info.*+` Spring
|
|
properties. All `Environment` properties under the info key will be automatically
|
|
exposed. For example, you could add the following to your `application.properties`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
info.app.encoding=UTF-8
|
|
info.app.java.source=1.8
|
|
info.app.java.target=1.8
|
|
----
|
|
|
|
[TIP]
|
|
====
|
|
Rather than hardcoding those values you could also
|
|
<<howto.adoc#howto-automatic-expansion,expand info properties at build time>>.
|
|
|
|
Assuming you are using Maven, you could rewrite the example above as follows:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
info.app.encoding=@project.build.sourceEncoding@
|
|
info.app.java.source=@java.version@
|
|
info.app.java.target=@java.version@
|
|
----
|
|
====
|
|
|
|
|
|
|
|
[[production-ready-application-info-git]]
|
|
==== Git commit information
|
|
Another useful feature of the `info` endpoint is its ability to publish information
|
|
about the state of your `git` source code repository when the project was built. If a
|
|
`GitProperties` bean is available, the `git.branch`, `git.commit.id` and
|
|
`git.commit.time` properties will be exposed.
|
|
|
|
TIP: A `GitProperties` bean is auto-configured if a `git.properties` file is available
|
|
at the root of the classpath. See
|
|
<<howto.adoc#howto-git-info,Generate git information>> for more details.
|
|
|
|
If you want to display the full git information (i.e. the full content of
|
|
`git.properties`), use the `management.info.git.mode` property:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
management.info.git.mode=full
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-application-info-build]]
|
|
==== Build information
|
|
The `info` endpoint can also publish information about your build if a `BuildProperties`
|
|
bean is available. This happens if a `META-INF/build-info.properties` file is available
|
|
in the classpath.
|
|
|
|
TIP: The Maven and Gradle plugins can both generate that file, see
|
|
<<howto.adoc#howto-build-info,Generate build information>> for more details.
|
|
|
|
|
|
[[production-ready-application-info-custom]]
|
|
==== Writing custom InfoContributors
|
|
To provide custom application information you can register Spring beans that implement
|
|
the {sc-spring-boot-actuator}/info/InfoContributor.{sc-ext}[`InfoContributor`] interface.
|
|
|
|
The example below contributes an `example` entry with a single value:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
import java.util.Collections;
|
|
|
|
import org.springframework.boot.actuate.info.Info;
|
|
import org.springframework.boot.actuate.info.InfoContributor;
|
|
import org.springframework.stereotype.Component;
|
|
|
|
@Component
|
|
public class ExampleInfoContributor implements InfoContributor {
|
|
|
|
@Override
|
|
public void contribute(Info.Builder builder) {
|
|
builder.withDetail("example",
|
|
Collections.singletonMap("key", "value"));
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
If you hit the `info` endpoint you should see a response that contains the following
|
|
additional entry:
|
|
|
|
[source,json,indent=0]
|
|
----
|
|
{
|
|
"example": {
|
|
"key" : "value"
|
|
}
|
|
}
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-monitoring]]
|
|
== Monitoring and management over HTTP
|
|
If you are developing a Spring MVC application, Spring Boot Actuator will auto-configure
|
|
all enabled endpoints to be exposed over HTTP. The default convention is to use the
|
|
`id` of the endpoint as the URL path. For example, `health` is exposed as `/health`.
|
|
|
|
|
|
|
|
[[production-ready-sensitive-endpoints]]
|
|
=== Accessing sensitive endpoints
|
|
By default all sensitive HTTP endpoints are secured such that only users that have an
|
|
`ACTUATOR` role may access them. Security is enforced using the standard
|
|
`HttpServletRequest.isUserInRole` method.
|
|
|
|
TIP: Use the `management.security.roles` property if you want something different to
|
|
`ACTUATOR`.
|
|
|
|
If you are deploying applications behind a firewall, you may prefer that all your actuator
|
|
endpoints can be accessed without requiring authentication. You can do this by changing
|
|
the `management.security.enabled` property:
|
|
|
|
.application.properties
|
|
[source,properties,indent=0]
|
|
----
|
|
management.security.enabled=false
|
|
----
|
|
|
|
NOTE: By default, actuator endpoints are exposed on the same port that serves regular
|
|
HTTP traffic. Take care not to accidentally expose sensitive information if you change
|
|
the `management.security.enabled` property.
|
|
|
|
If you're deploying applications publicly, you may want to add '`Spring Security`' to
|
|
handle user authentication. When '`Spring Security`' is added, by default '`basic`'
|
|
authentication will be used with the username `user` and a generated password (which is
|
|
printed on the console when the application starts).
|
|
|
|
TIP: Generated passwords are logged as the application starts. Search for '`Using default
|
|
security password`'.
|
|
|
|
You can use Spring properties to change the username and password and to change the
|
|
security role(s) required to access the endpoints. For example, you might set the following
|
|
in your `application.properties`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
security.user.name=admin
|
|
security.user.password=secret
|
|
management.security.roles=SUPERUSER
|
|
----
|
|
|
|
If your application has custom security configuration and you want all your actuator endpoints
|
|
to be accessible without authentication, you need to explicitly configure that in your
|
|
security configuration. Along with that, you need to change the `management.security.enabled`
|
|
property to `false`.
|
|
|
|
If your custom security configuration secures your actuator endpoints, you also need to ensure that
|
|
the authenticated user has the roles specified under `management.security.roles`.
|
|
|
|
TIP: If you don't have a use case for exposing basic health information to unauthenticated users,
|
|
and you have secured the actuator endpoints with custom security, you can set `management.security.enabled`
|
|
to `false`. This will inform Spring Boot to skip the additional role check.
|
|
|
|
|
|
|
|
|
|
|
|
[[production-ready-customizing-management-server-context-path]]
|
|
=== Customizing the management endpoint paths
|
|
Sometimes it is useful to group all management endpoints under a single path. For example,
|
|
your application might already use `/info` for another purpose. You can use the
|
|
`management.context-path` property to set a prefix for your management endpoint:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
management.context-path=/manage
|
|
----
|
|
|
|
The `application.properties` example above will change the endpoint from `/{id}` to
|
|
`/manage/{id}` (e.g. `/manage/info`).
|
|
|
|
NOTE: Unless the management port has been configured to
|
|
<<production-ready-customizing-management-server-port,expose endpoints using a different
|
|
HTTP port>>, `management.context-path` is relative to `server.context-path`.
|
|
|
|
You can also change the "`id`" of an endpoint (using `endpoints.{name}.id`) which then
|
|
changes the default resource path for the MVC endpoint. Legal endpoint ids are composed
|
|
only of alphanumeric characters (because they can be exposed in a number of places,
|
|
including JMX object names, where special characters are forbidden). The MVC path can be
|
|
changed separately by configuring `endpoints.{name}.path`, and there is no validation on
|
|
those values (so you can use anything that is legal in a URL path). For example, to change
|
|
the location of the `/health` endpoint to `/ping/me` you can set
|
|
`endpoints.health.path=/ping/me`.
|
|
|
|
NOTE: Even if an endpoint path is configured separately, it is still relative to the
|
|
`management.context-path`.
|
|
|
|
TIP: If you provide a custom `MvcEndpoint` remember to include a settable `path` property,
|
|
and default it to `/{id}` if you want your code to behave like the standard MVC endpoints.
|
|
(Take a look at the `HealthMvcEndpoint` to see how you might do that.) If your custom
|
|
endpoint is an `Endpoint` (not an `MvcEndpoint`) then Spring Boot will take care of the
|
|
path for you.
|
|
|
|
|
|
|
|
[[production-ready-customizing-management-server-port]]
|
|
=== Customizing the management server port
|
|
Exposing management endpoints using the default HTTP port is a sensible choice for cloud
|
|
based deployments. If, however, your application runs inside your own data center you
|
|
may prefer to expose endpoints using a different HTTP port.
|
|
|
|
The `management.port` property can be used to change the HTTP port.
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
management.port=8081
|
|
----
|
|
|
|
Since your management port is often protected by a firewall, and not exposed to the public
|
|
you might not need security on the management endpoints, even if your main application is
|
|
secure. In that case you will have Spring Security on the classpath, and you can disable
|
|
management security like this:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
management.security.enabled=false
|
|
----
|
|
|
|
(If you don't have Spring Security on the classpath then there is no need to explicitly
|
|
disable the management security in this way, and it might even break the application.)
|
|
|
|
|
|
|
|
[[production-ready-management-specific-ssl]]
|
|
=== Configuring management-specific SSL
|
|
When configured to use a custom port, the management server can also be configured with
|
|
its own SSL using the various `management.ssl.*` properties. For example, this allows a
|
|
management server to be available via HTTP while the main application uses HTTPS:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
server.port=8443
|
|
server.ssl.enabled=true
|
|
server.ssl.key-store=classpath:store.jks
|
|
server.ssl.key-password=secret
|
|
management.port=8080
|
|
management.ssl.enabled=false
|
|
----
|
|
|
|
Alternatively, both the main server and the management server can use SSL but with
|
|
different key stores:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
server.port=8443
|
|
server.ssl.enabled=true
|
|
server.ssl.key-store=classpath:main.jks
|
|
server.ssl.key-password=secret
|
|
management.port=8080
|
|
management.ssl.enabled=true
|
|
management.ssl.key-store=classpath:management.jks
|
|
management.ssl.key-password=secret
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-customizing-management-server-address]]
|
|
=== Customizing the management server address
|
|
You can customize the address that the management endpoints are available on by
|
|
setting the `management.address` property. This can be useful if you want to
|
|
listen only on an internal or ops-facing network, or to only listen for connections from
|
|
`localhost`.
|
|
|
|
NOTE: You can only listen on a different address if the port is different to the
|
|
main server port.
|
|
|
|
Here is an example `application.properties` that will not allow remote management
|
|
connections:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
management.port=8081
|
|
management.address=127.0.0.1
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-disabling-http-endpoints]]
|
|
=== Disabling HTTP endpoints
|
|
If you don't want to expose endpoints over HTTP you can set the management port to `-1`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
management.port=-1
|
|
----
|
|
|
|
|
|
[[production-ready-health-access-restrictions]]
|
|
=== HTTP health endpoint format and access restrictions
|
|
The information exposed by the health endpoint varies depending on whether or not it's
|
|
accessed anonymously, and whether or not the enclosing application is secure.
|
|
By default, when accessed anonymously in a secure application, any details about the
|
|
server's health are hidden and the endpoint will simply indicate whether or not the server
|
|
is up or down. Furthermore the response is cached for a configurable period to prevent the
|
|
endpoint being used in a denial of service attack. The `endpoints.health.time-to-live`
|
|
property is used to configure the caching period in milliseconds. It defaults to 1000,
|
|
i.e. one second.
|
|
|
|
Sample summarized HTTP response (default for anonymous request):
|
|
|
|
[source,indent=0]
|
|
----
|
|
$ curl -i localhost:8080/health
|
|
HTTP/1.1 200
|
|
X-Application-Context: application
|
|
Content-Type: application/vnd.spring-boot.actuator.v1+json;charset=UTF-8
|
|
Content-Length: 15
|
|
|
|
{"status":"UP"}
|
|
----
|
|
|
|
Sample summarized HTTP response for status "DOWN" (notice the 503 status code):
|
|
|
|
[source,indent=0]
|
|
----
|
|
$ curl -i localhost:8080/health
|
|
HTTP/1.1 503
|
|
X-Application-Context: application
|
|
Content-Type: application/vnd.spring-boot.actuator.v1+json;charset=UTF-8
|
|
Content-Length: 17
|
|
|
|
{"status":"DOWN"}
|
|
----
|
|
|
|
Sample detailed HTTP response:
|
|
|
|
[source,indent=0]
|
|
----
|
|
$ curl -i localhost:8080/health
|
|
HTTP/1.1 200 OK
|
|
X-Application-Context: application
|
|
Content-Type: application/vnd.spring-boot.actuator.v1+json;charset=UTF-8
|
|
Content-Length: 221
|
|
|
|
{
|
|
"status" : "UP",
|
|
"diskSpace" : {
|
|
"status" : "UP",
|
|
"total" : 63251804160,
|
|
"free" : 31316164608,
|
|
"threshold" : 10485760
|
|
},
|
|
"db" : {
|
|
"status" : "UP",
|
|
"database" : "H2",
|
|
"hello" : 1
|
|
}
|
|
}
|
|
----
|
|
|
|
The above-described restrictions can be enhanced, thereby allowing only authenticated
|
|
users full access to the health endpoint in a secure application. To do so, set
|
|
`endpoints.health.sensitive` to `true`. Here's a summary of behavior (with default
|
|
`sensitive` flag value "`false`" indicated in bold):
|
|
|
|
|====
|
|
| `management.security.enabled` | `endpoints.health.sensitive` | Unauthenticated | Authenticated (with right role)
|
|
|
|
|false
|
|
|*
|
|
|Full content
|
|
|Full content
|
|
|
|
|true
|
|
|**false**
|
|
|Status only
|
|
|Full content
|
|
|
|
|true
|
|
|true
|
|
|No content
|
|
|Full content
|
|
|====
|
|
|
|
|
|
|
|
[[production-ready-jmx]]
|
|
== Monitoring and management over JMX
|
|
Java Management Extensions (JMX) provide a standard mechanism to monitor and manage
|
|
applications. By default Spring Boot will expose management endpoints as JMX MBeans
|
|
under the `org.springframework.boot` domain.
|
|
|
|
|
|
|
|
[[production-ready-custom-mbean-names]]
|
|
=== Customizing MBean names
|
|
The name of the MBean is usually generated from the `id` of the endpoint. For example
|
|
the `health` endpoint is exposed as `org.springframework.boot/Endpoint/healthEndpoint`.
|
|
|
|
If your application contains more than one Spring `ApplicationContext` you may find that
|
|
names clash. To solve this problem you can set the `endpoints.jmx.unique-names` property
|
|
to `true` so that MBean names are always unique.
|
|
|
|
You can also customize the JMX domain under which endpoints are exposed. Here is an
|
|
example `application.properties`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
endpoints.jmx.domain=myapp
|
|
endpoints.jmx.unique-names=true
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-disable-jmx-endpoints]]
|
|
=== Disabling JMX endpoints
|
|
If you don't want to expose endpoints over JMX you can set the `endpoints.jmx.enabled`
|
|
property to `false`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
endpoints.jmx.enabled=false
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-jolokia]]
|
|
=== Using Jolokia for JMX over HTTP
|
|
Jolokia is a JMX-HTTP bridge giving an alternative method of accessing JMX beans. To
|
|
use Jolokia, simply include a dependency to `org.jolokia:jolokia-core`. For example,
|
|
using Maven you would add the following:
|
|
|
|
[source,xml,indent=0]
|
|
----
|
|
<dependency>
|
|
<groupId>org.jolokia</groupId>
|
|
<artifactId>jolokia-core</artifactId>
|
|
</dependency>
|
|
----
|
|
|
|
Jolokia can then be accessed using `/jolokia` on your management HTTP server.
|
|
|
|
|
|
|
|
[[production-ready-customizing-jolokia]]
|
|
==== Customizing Jolokia
|
|
Jolokia has a number of settings that you would traditionally configure using servlet
|
|
parameters. With Spring Boot you can use your `application.properties`, simply prefix the
|
|
parameter with `jolokia.config.`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
jolokia.config.debug=true
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-disabling-jolokia]]
|
|
==== Disabling Jolokia
|
|
If you are using Jolokia but you don't want Spring Boot to configure it, simply set the
|
|
`endpoints.jolokia.enabled` property to `false`:
|
|
|
|
[source,properties,indent=0]
|
|
----
|
|
endpoints.jolokia.enabled=false
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-remote-shell]]
|
|
== Monitoring and management using a remote shell (deprecated)
|
|
Spring Boot supports an integrated Java shell called '`CRaSH`'. You can use CRaSH to
|
|
`ssh` or `telnet` into your running application. To enable remote shell support, add
|
|
the following dependency to your project:
|
|
|
|
[source,xml,indent=0]
|
|
----
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-remote-shell</artifactId>
|
|
</dependency>
|
|
----
|
|
|
|
NOTE: The remote shell is deprecated and will be removed in Spring Boot 2.0.
|
|
|
|
TIP: If you want to also enable telnet access you will additionally need a dependency
|
|
on `org.crsh:crsh.shell.telnet`.
|
|
|
|
NOTE: CRaSH requires to run with a JDK as it compiles commands on the fly. If a basic
|
|
`help` command fails, you are probably running with a JRE.
|
|
|
|
|
|
[[production-ready-connecting-to-the-remote-shell]]
|
|
=== Connecting to the remote shell
|
|
By default the remote shell will listen for connections on port `2000`. The default user
|
|
is `user` and the default password will be randomly generated and displayed in the log
|
|
output. If your application is using Spring Security, the shell will use
|
|
<<boot-features-security, the same configuration>> by default. If not, a simple
|
|
authentication will be applied and you should see a message like this:
|
|
|
|
[indent=0]
|
|
----
|
|
Using default password for shell access: ec03e16c-4cf4-49ee-b745-7c8255c1dd7e
|
|
----
|
|
|
|
Linux and OSX users can use `ssh` to connect to the remote shell, Windows users can
|
|
download and install http://www.putty.org/[PuTTY].
|
|
|
|
[indent=0,subs="attributes"]
|
|
----
|
|
$ ssh -p 2000 user@localhost
|
|
|
|
user@localhost's password:
|
|
. ____ _ __ _ _
|
|
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
|
|
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
|
|
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
|
|
' |____| .__|_| |_|_| |_\__, | / / / /
|
|
=========|_|==============|___/=/_/_/_/
|
|
:: Spring Boot :: (v{spring-boot-version}) on myhost
|
|
----
|
|
|
|
Type `help` for a list of commands. Spring Boot provides `metrics`, `beans`, `autoconfig`
|
|
and `endpoint` commands.
|
|
|
|
|
|
|
|
[[production-ready-remote-shell-credentials]]
|
|
==== Remote shell credentials
|
|
You can use the `management.shell.auth.simple.user.name` and
|
|
`management.shell.auth.simple.user.password` properties to configure custom connection
|
|
credentials. It is also possible to use a '`Spring Security`' `AuthenticationManager` to
|
|
handle login duties. See the
|
|
{dc-spring-boot-actuator}/autoconfigure/CrshAutoConfiguration.{dc-ext}[`CrshAutoConfiguration`]
|
|
and {dc-spring-boot-actuator}/autoconfigure/ShellProperties.{dc-ext}[`ShellProperties`]
|
|
Javadoc for full details.
|
|
|
|
|
|
|
|
[[production-ready-extending-the-remote-shell]]
|
|
=== Extending the remote shell
|
|
The remote shell can be extended in a number of interesting ways.
|
|
|
|
|
|
|
|
[[production-ready-remote-commands]]
|
|
==== Remote shell commands
|
|
You can write additional shell commands using Groovy (see the CRaSH documentation for details).
|
|
Due to limitations in CRaSH's Java compiler, commands written in Java are not supported.
|
|
By default Spring Boot will search for commands in the following locations:
|
|
|
|
* `+classpath*:/commands/**+`
|
|
* `+classpath*:/crash/commands/**+`
|
|
|
|
TIP: You can change the search path by settings a `shell.command-path-patterns` property.
|
|
|
|
NOTE: If you are using an executable archive, any classes that a shell command depends
|
|
upon must be packaged in a nested jar rather than directly in the executable jar or war.
|
|
|
|
Here is a simple '`hello`' command that could be loaded from
|
|
`src/main/resources/commands/hello.groovy`
|
|
|
|
[source,groovy,indent=0]
|
|
----
|
|
package commands
|
|
|
|
import org.crsh.cli.Command
|
|
import org.crsh.cli.Usage
|
|
import org.crsh.command.InvocationContext
|
|
|
|
class hello {
|
|
|
|
@Usage("Say Hello")
|
|
@Command
|
|
def main(InvocationContext context) {
|
|
return "Hello"
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
Spring Boot adds some additional attributes to `InvocationContext` that you can access
|
|
from your command:
|
|
|
|
[cols="2,3"]
|
|
|===
|
|
| Attribute Name | Description
|
|
|
|
|`spring.boot.version`
|
|
|The version of Spring Boot
|
|
|
|
|`spring.version`
|
|
|The version of the core Spring Framework
|
|
|
|
|`spring.beanfactory`
|
|
|Access to the Spring `BeanFactory`
|
|
|
|
|`spring.environment`
|
|
|Access to the Spring `Environment`
|
|
|===
|
|
|
|
|
|
|
|
[[production-ready-remote-shell-plugins]]
|
|
==== Remote shell plugins
|
|
In addition to new commands, it is also possible to extend other CRaSH shell features.
|
|
All Spring Beans that extend `org.crsh.plugin.CRaSHPlugin` will be automatically
|
|
registered with the shell.
|
|
|
|
For more information please refer to the http://www.crashub.org/[CRaSH reference
|
|
documentation].
|
|
|
|
|
|
|
|
[[production-ready-loggers]]
|
|
== Loggers
|
|
Spring Boot Actuator includes the ability to view and configure the log levels of your
|
|
application at runtime. You can view either the entire list or an individual logger's
|
|
configuration which is made up of both the explicitly configured logging level as well as
|
|
the effective logging level given to it by the logging framework. These levels can be:
|
|
|
|
* `TRACE`
|
|
* `DEBUG`
|
|
* `INFO`
|
|
* `WARN`
|
|
* `ERROR`
|
|
* `FATAL`
|
|
* `OFF`
|
|
* `null`
|
|
|
|
with `null` indicating that there is no explicit configuration.
|
|
|
|
|
|
|
|
[[production-ready-logger-configuration]]
|
|
=== Configure a Logger
|
|
In order to configure a given logger, you `POST` a partial entity to the resource's URI:
|
|
|
|
[source,json,indent=0]
|
|
----
|
|
{
|
|
"configuredLevel": "DEBUG"
|
|
}
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-metrics]]
|
|
== Metrics
|
|
Spring Boot Actuator includes a metrics service with '`gauge`' and '`counter`' support.
|
|
A '`gauge`' records a single value; and a '`counter`' records a delta (an increment or
|
|
decrement). Spring Boot Actuator also provides a
|
|
{sc-spring-boot-actuator}/endpoint/PublicMetrics.{sc-ext}[`PublicMetrics`] interface that
|
|
you can implement to expose metrics that you cannot record via one of those two
|
|
mechanisms. Look at {sc-spring-boot-actuator}/endpoint/SystemPublicMetrics.{sc-ext}[`SystemPublicMetrics`]
|
|
for an example.
|
|
|
|
Metrics for all HTTP requests are automatically recorded, so if you hit the `metrics`
|
|
endpoint you should see a response similar to this:
|
|
|
|
[source,json,indent=0]
|
|
----
|
|
{
|
|
"counter.status.200.root": 20,
|
|
"counter.status.200.metrics": 3,
|
|
"counter.status.200.star-star": 5,
|
|
"counter.status.401.root": 4,
|
|
"gauge.response.star-star": 6,
|
|
"gauge.response.root": 2,
|
|
"gauge.response.metrics": 3,
|
|
"classes": 5808,
|
|
"classes.loaded": 5808,
|
|
"classes.unloaded": 0,
|
|
"heap": 3728384,
|
|
"heap.committed": 986624,
|
|
"heap.init": 262144,
|
|
"heap.used": 52765,
|
|
"nonheap": 0,
|
|
"nonheap.committed": 77568,
|
|
"nonheap.init": 2496,
|
|
"nonheap.used": 75826,
|
|
"mem": 986624,
|
|
"mem.free": 933858,
|
|
"processors": 8,
|
|
"threads": 15,
|
|
"threads.daemon": 11,
|
|
"threads.peak": 15,
|
|
"threads.totalStarted": 42,
|
|
"uptime": 494836,
|
|
"instance.uptime": 489782,
|
|
"datasource.primary.active": 5,
|
|
"datasource.primary.usage": 0.25
|
|
}
|
|
----
|
|
|
|
Here we can see basic `memory`, `heap`, `class loading`, `processor` and `thread pool`
|
|
information along with some HTTP metrics. In this instance the `root` ('`/`') and `/metrics`
|
|
URLs have returned `HTTP 200` responses `20` and `3` times respectively. It also appears
|
|
that the `root` URL returned `HTTP 401` (unauthorized) `4` times. The double asterisks (`star-star`)
|
|
comes from a request matched by Spring MVC as `+/**+` (normally a static resource).
|
|
|
|
The `gauge` shows the last response time for a request. So the last request to `root` took
|
|
`2ms` to respond and the last to `/metrics` took `3ms`.
|
|
|
|
NOTE: In this example we are actually accessing the endpoint over HTTP using the
|
|
`/metrics` URL, this explains why `metrics` appears in the response.
|
|
|
|
|
|
|
|
[[production-ready-system-metrics]]
|
|
=== System metrics
|
|
The following system metrics are exposed by Spring Boot:
|
|
|
|
* The total system memory in KB (`mem`)
|
|
* The amount of free memory in KB (`mem.free`)
|
|
* The number of processors (`processors`)
|
|
* The system uptime in milliseconds (`uptime`)
|
|
* The application context uptime in milliseconds (`instance.uptime`)
|
|
* The average system load (`systemload.average`)
|
|
* Heap information in KB (`heap`, `heap.committed`, `heap.init`, `heap.used`)
|
|
* Thread information (`threads`, `thread.peak`, `thread.daemon`)
|
|
* Class load information (`classes`, `classes.loaded`, `classes.unloaded`)
|
|
* Garbage collection information (`gc.xxx.count`, `gc.xxx.time`)
|
|
|
|
|
|
|
|
[[production-ready-datasource-metrics]]
|
|
=== DataSource metrics
|
|
The following metrics are exposed for each supported `DataSource` defined in your
|
|
application:
|
|
|
|
* The number of active connections (`datasource.xxx.active`)
|
|
* The current usage of the connection pool (`datasource.xxx.usage`).
|
|
|
|
All data source metrics share the `datasource.` prefix. The prefix is further qualified
|
|
for each data source:
|
|
|
|
* If the data source is the primary data source (that is either the only available data
|
|
source or the one flagged `@Primary` amongst the existing ones), the prefix is
|
|
`datasource.primary`.
|
|
* If the data source bean name ends with `DataSource`, the prefix is the name of the bean
|
|
without `DataSource` (i.e. `datasource.batch` for `batchDataSource`).
|
|
* In all other cases, the name of the bean is used.
|
|
|
|
It is possible to override part or all of those defaults by registering a bean with a
|
|
customized version of `DataSourcePublicMetrics`. 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.
|
|
|
|
|
|
|
|
[[production-ready-datasource-cache]]
|
|
=== Cache metrics
|
|
The following metrics are exposed for each supported cache defined in your application:
|
|
|
|
* The current size of the cache (`cache.xxx.size`)
|
|
* Hit ratio (`cache.xxx.hit.ratio`)
|
|
* Miss ratio (`cache.xxx.miss.ratio`)
|
|
|
|
NOTE: Cache providers do not expose the hit/miss ratio in a consistent way. While some
|
|
expose an **aggregated** value (i.e. the hit ratio since the last time the stats were
|
|
cleared), others expose a **temporal** value (i.e. the hit ratio of the last second).
|
|
Check your caching provider documentation for more details.
|
|
|
|
If two different cache managers happen to define the same cache, the name of the cache
|
|
is prefixed by the name of the `CacheManager` bean.
|
|
|
|
It is possible to override part or all of those defaults by registering a bean with a
|
|
customized version of `CachePublicMetrics`. By default, Spring Boot provides cache
|
|
statistics for EhCache, Hazelcast, Infinispan, JCache and Guava. You can add additional
|
|
`CacheStatisticsProvider` beans if your favorite caching library isn't supported out of
|
|
the box. See `CacheStatisticsAutoConfiguration` for examples.
|
|
|
|
|
|
[[production-ready-session-metrics]]
|
|
=== Tomcat session metrics
|
|
If you are using Tomcat as your embedded servlet container, session metrics will
|
|
automatically be exposed. The `httpsessions.active` and `httpsessions.max` keys provide
|
|
the number of active and maximum sessions.
|
|
|
|
|
|
|
|
[[production-ready-recording-metrics]]
|
|
=== Recording your own metrics
|
|
To record your own metrics inject a
|
|
{sc-spring-boot-actuator}/metrics/CounterService.{sc-ext}[`CounterService`] and/or
|
|
{sc-spring-boot-actuator}/metrics/GaugeService.{sc-ext}[`GaugeService`] into
|
|
your bean. The `CounterService` exposes `increment`, `decrement` and `reset` methods; the
|
|
`GaugeService` provides a `submit` method.
|
|
|
|
Here is a simple example that counts the number of times that a method is invoked:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
import org.springframework.beans.factory.annotation.Autowired;
|
|
import org.springframework.boot.actuate.metrics.CounterService;
|
|
import org.springframework.stereotype.Service;
|
|
|
|
@Service
|
|
public class MyService {
|
|
|
|
private final CounterService counterService;
|
|
|
|
@Autowired
|
|
public MyService(CounterService counterService) {
|
|
this.counterService = counterService;
|
|
}
|
|
|
|
public void exampleMethod() {
|
|
this.counterService.increment("services.system.myservice.invoked");
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
TIP: You can use any string as a metric name but you should follow guidelines of your chosen
|
|
store/graphing technology. Some good guidelines for Graphite are available on
|
|
http://matt.aimonetti.net/posts/2013/06/26/practical-guide-to-graphite-monitoring/[Matt Aimonetti's Blog].
|
|
|
|
|
|
|
|
[[production-ready-public-metrics]]
|
|
=== Adding your own public metrics
|
|
To add additional metrics that are computed every time the metrics endpoint is invoked,
|
|
simply register additional `PublicMetrics` implementation bean(s). By default, all such
|
|
beans are gathered by the endpoint. You can easily change that by defining your own
|
|
`MetricsEndpoint`.
|
|
|
|
|
|
|
|
[[production-ready-metric-repositories]]
|
|
=== Special features with Java 8
|
|
The default implementation of `GaugeService` and `CounterService` provided by Spring Boot
|
|
depends on the version of Java that you are using. With Java 8 (or better) the
|
|
implementation switches to a high-performance version optimized for fast writes, backed by
|
|
atomic in-memory buffers, rather than by the immutable but relatively expensive
|
|
`Metric<?>` type (counters are approximately 5 times faster and gauges approximately twice
|
|
as fast as the repository-based implementations). The Dropwizard metrics services (see
|
|
below) are also very efficient even for Java 7 (they have backports of some of the Java 8
|
|
concurrency libraries), but they do not record timestamps for metric values. If
|
|
performance of metric gathering is a concern then it is always advisable to use one of the
|
|
high-performance options, and also to only read metrics infrequently, so that the writes
|
|
are buffered locally and only read when needed.
|
|
|
|
NOTE: The old `MetricRepository` and its `InMemoryMetricRepository` implementation are not
|
|
used by default if you are on Java 8 or if you are using Dropwizard metrics.
|
|
|
|
|
|
|
|
[[production-ready-metric-writers]]
|
|
=== Metric writers, exporters and aggregation
|
|
Spring Boot provides a couple of implementations of a marker interface called `Exporter`
|
|
which can be used to copy metric readings from the in-memory buffers to a place where they
|
|
can be analyzed and displayed. Indeed, if you provide a `@Bean` that implements the
|
|
`MetricWriter` interface (or `GaugeWriter` for simple use cases) and mark it
|
|
`@ExportMetricWriter`, then it will automatically be hooked up to an `Exporter` and fed
|
|
metric updates every 5 seconds (configured via `spring.metrics.export.delay-millis`).
|
|
In addition, any `MetricReader` that you define and mark as `@ExportMetricReader` will
|
|
have its values exported by the default exporter.
|
|
|
|
NOTE: This feature is enabling scheduling in your application (`@EnableScheduling`) which
|
|
can be a problem if you run an integration test as your own scheduled tasks will start.
|
|
You can disable this behaviour by setting `spring.metrics.export.enabled` to `false`.
|
|
|
|
The default exporter is a `MetricCopyExporter` which tries to optimize itself by not
|
|
copying values that haven't changed since it was last called (the optimization can be
|
|
switched off using a flag `spring.metrics.export.send-latest`). Note also that the
|
|
Dropwizard `MetricRegistry` has no support for timestamps, so the optimization is not
|
|
available if you are using Dropwizard metrics (all metrics will be copied on every tick).
|
|
|
|
The default values for the export trigger (`delay-millis`, `includes`, `excludes`
|
|
and `send-latest`) can be set as `spring.metrics.export.\*`. Individual
|
|
values for specific `MetricWriters` can be set as
|
|
`spring.metrics.export.triggers.<name>.*` where `<name>` is a bean name (or pattern for
|
|
matching bean names).
|
|
|
|
WARNING: The automatic export of metrics is disabled if you switch off the default
|
|
`MetricRepository` (e.g. by using Dropwizard metrics). You can get back the same
|
|
functionality be declaring a bean of your own of type `MetricReader` and declaring it to
|
|
be `@ExportMetricReader`.
|
|
|
|
|
|
|
|
[[production-ready-metric-writers-export-to-redis]]
|
|
==== Example: Export to Redis
|
|
If you provide a `@Bean` of type `RedisMetricRepository` and mark it `@ExportMetricWriter`
|
|
the metrics are exported to a Redis cache for aggregation. The `RedisMetricRepository` has
|
|
two important parameters to configure it for this purpose: `prefix` and `key` (passed into
|
|
its constructor). It is best to use a prefix that is unique to the application instance
|
|
(e.g. using a random value and maybe the logical name of the application to make it
|
|
possible to correlate with other instances of the same application). The "`key`" is used
|
|
to keep a global index of all metric names, so it should be unique "`globally`", whatever
|
|
that means for your system (e.g. two instances of the same system could share a Redis cache
|
|
if they have distinct keys).
|
|
|
|
Example:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
@Bean
|
|
@ExportMetricWriter
|
|
MetricWriter metricWriter(MetricExportProperties export) {
|
|
return new RedisMetricRepository(connectionFactory,
|
|
export.getRedis().getPrefix(), export.getRedis().getKey());
|
|
}
|
|
----
|
|
|
|
.application.properties
|
|
[source,properties,indent=0]
|
|
----
|
|
spring.metrics.export.redis.prefix: metrics.mysystem.${spring.application.name:application}.${random.value:0000}
|
|
spring.metrics.export.redis.key: keys.metrics.mysystem
|
|
----
|
|
|
|
The prefix is constructed with the application name and id at the end, so it can easily be used
|
|
to identify a group of processes with the same logical name later.
|
|
|
|
NOTE: It's important to set both the `key` and the `prefix`. The key is used for all
|
|
repository operations, and can be shared by multiple repositories. If multiple
|
|
repositories share a key (like in the case where you need to aggregate across them), then
|
|
you normally have a read-only "`master`" repository that has a short, but identifiable,
|
|
prefix (like "`metrics.mysystem`"), and many write-only repositories with prefixes that
|
|
start with the master prefix (like `metrics.mysystem.*` in the example above). It is
|
|
efficient to read all the keys from a "`master`" repository like that, but inefficient to
|
|
read a subset with a longer prefix (e.g. using one of the writing repositories).
|
|
|
|
TIP: The example above uses `MetricExportProperties` to inject and extract the key and
|
|
prefix. This is provided to you as a convenience by Spring Boot, configured with sensible
|
|
defaults. There is nothing to stop you using your own values as long as they follow the
|
|
recommendations.
|
|
|
|
|
|
|
|
[[production-ready-metric-writers-export-to-open-tsdb]]
|
|
==== Example: Export to Open TSDB
|
|
If you provide a `@Bean` of type `OpenTsdbGaugeWriter` and mark it
|
|
`@ExportMetricWriter` metrics are exported to http://opentsdb.net/[Open TSDB] for
|
|
aggregation. The `OpenTsdbGaugeWriter` has a `url` property that you need to set
|
|
to the Open TSDB "`/put`" endpoint, e.g. `http://localhost:4242/api/put`). It also has a
|
|
`namingStrategy` that you can customize or configure to make the metrics match the data
|
|
structure you need on the server. By default it just passes through the metric name as an
|
|
Open TSDB metric name, and adds the tags "`domain`" (with value
|
|
"`org.springframework.metrics`") and "`process`" (with the value equal to the object hash
|
|
of the naming strategy). Thus, after running the application and generating some metrics
|
|
you can inspect the metrics in the TSD UI (http://localhost:4242 by default).
|
|
|
|
Example:
|
|
|
|
[source,indent=0]
|
|
----
|
|
curl localhost:4242/api/query?start=1h-ago&m=max:counter.status.200.root
|
|
[
|
|
{
|
|
"metric": "counter.status.200.root",
|
|
"tags": {
|
|
"domain": "org.springframework.metrics",
|
|
"process": "b968a76"
|
|
},
|
|
"aggregateTags": [],
|
|
"dps": {
|
|
"1430492872": 2,
|
|
"1430492875": 6
|
|
}
|
|
}
|
|
]
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-metric-writers-export-to-statsd]]
|
|
==== Example: Export to Statsd
|
|
To export metrics to Statsd, make sure first that you have added
|
|
`com.timgroup:java-statsd-client` as a dependency of your project (Spring Boot
|
|
provides a dependency management for it). Then add a `spring.metrics.export.statsd.host`
|
|
value to your `application.properties` file. Connections will be opened to port `8125`
|
|
unless a `spring.metrics.export.statsd.port` override is provided. You can use
|
|
`spring.metrics.export.statsd.prefix` if you want a custom prefix.
|
|
|
|
Alternatively, you can provide a `@Bean` of type `StatsdMetricWriter` and mark it
|
|
`@ExportMetricWriter`:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
@Value("${spring.application.name:application}.${random.value:0000}")
|
|
private String prefix = "metrics";
|
|
|
|
@Bean
|
|
@ExportMetricWriter
|
|
MetricWriter metricWriter() {
|
|
return new StatsdMetricWriter(prefix, "localhost", 8125);
|
|
}
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-metric-writers-export-to-jmx]]
|
|
==== Example: Export to JMX
|
|
If you provide a `@Bean` of type `JmxMetricWriter` marked `@ExportMetricWriter` the metrics are exported as MBeans to
|
|
the local server (the `MBeanExporter` is provided by Spring Boot JMX auto-configuration as
|
|
long as it is switched on). Metrics can then be inspected, graphed, alerted etc. using any
|
|
tool that understands JMX (e.g. JConsole or JVisualVM).
|
|
|
|
Example:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
@Bean
|
|
@ExportMetricWriter
|
|
MetricWriter metricWriter(MBeanExporter exporter) {
|
|
return new JmxMetricWriter(exporter);
|
|
}
|
|
----
|
|
|
|
Each metric is exported as an individual MBean. The format for the `ObjectNames` is given
|
|
by an `ObjectNamingStrategy` which can be injected into the `JmxMetricWriter` (the default
|
|
breaks up the metric name and tags the first two period-separated sections in a way that
|
|
should make the metrics group nicely in JVisualVM or JConsole).
|
|
|
|
|
|
|
|
[[production-ready-metric-aggregation]]
|
|
=== Aggregating metrics from multiple sources
|
|
There is an `AggregateMetricReader` that you can use to consolidate metrics from different
|
|
physical sources. Sources for the same logical metric just need to publish them with a
|
|
period-separated prefix, and the reader will aggregate (by truncating the metric names,
|
|
and dropping the prefix). Counters are summed and everything else (i.e. gauges) take their
|
|
most recent value.
|
|
|
|
This is very useful if multiple application instances are feeding to a central (e.g.
|
|
Redis) repository and you want to display the results. Particularly recommended in
|
|
conjunction with a `MetricReaderPublicMetrics` for hooking up to the results to the
|
|
"`/metrics`" endpoint.
|
|
|
|
Example:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
@Autowired
|
|
private MetricExportProperties export;
|
|
|
|
@Bean
|
|
public PublicMetrics metricsAggregate() {
|
|
return new MetricReaderPublicMetrics(aggregatesMetricReader());
|
|
}
|
|
|
|
private MetricReader globalMetricsForAggregation() {
|
|
return new RedisMetricRepository(this.connectionFactory,
|
|
this.export.getRedis().getAggregatePrefix(), this.export.getRedis().getKey());
|
|
}
|
|
|
|
private MetricReader aggregatesMetricReader() {
|
|
AggregateMetricReader repository = new AggregateMetricReader(
|
|
globalMetricsForAggregation());
|
|
return repository;
|
|
}
|
|
----
|
|
|
|
NOTE: The example above uses `MetricExportProperties` to inject and extract the key and
|
|
prefix. This is provided to you as a convenience by Spring Boot, and the defaults will be
|
|
sensible. They are set up in `MetricExportAutoConfiguration`.
|
|
|
|
NOTE: The `MetricReaders` above are not `@Beans` and are not marked as
|
|
`@ExportMetricReader` because they are just collecting and analyzing data from other
|
|
repositories, and don't want to export their values.
|
|
|
|
|
|
|
|
[[production-ready-dropwizard-metrics]]
|
|
=== Dropwizard Metrics
|
|
A default `MetricRegistry` Spring bean will be created when you declare a dependency to
|
|
the `io.dropwizard.metrics:metrics-core` library; you can also register you own `@Bean`
|
|
instance if you need customizations. Users of the
|
|
https://dropwizard.github.io/metrics/[Dropwizard '`Metrics`' library] will find that
|
|
Spring Boot metrics are automatically published to `com.codahale.metrics.MetricRegistry`.
|
|
Metrics from the `MetricRegistry` are also automatically exposed via the `/metrics`
|
|
endpoint
|
|
|
|
When Dropwizard metrics are in use, the default `CounterService` and `GaugeService` are
|
|
replaced with a `DropwizardMetricServices`, which is a wrapper around the `MetricRegistry`
|
|
(so you can `@Autowired` one of those services and use it as normal). You can also create
|
|
"`special`" Dropwizard metrics by prefixing your metric names with the appropriate type
|
|
(i.e. `+timer.*+`, `+histogram.*+` for gauges, and `+meter.*+` for counters).
|
|
|
|
|
|
|
|
[[production-ready-metrics-message-channel-integration]]
|
|
=== Message channel integration
|
|
If a `MessageChannel` bean called `metricsChannel` exists, then a `MetricWriter` will be
|
|
created that writes metrics to that channel. Each message sent to the channel will contain
|
|
a {dc-spring-boot-actuator}/metrics/writer/Delta.{dc-ext}[`Delta`] or
|
|
{dc-spring-boot-actuator}/metrics/Metric.{dc-ext}[`Metric`] payload and have a `metricName`
|
|
header. The writer is automatically hooked up to an exporter (as for all writers), so all
|
|
metric values will appear on the channel, and additional analysis or actions can be taken
|
|
by subscribers (it's up to you to provide the channel and any subscribers you need).
|
|
|
|
|
|
|
|
[[production-ready-auditing]]
|
|
== Auditing
|
|
Spring Boot Actuator has a flexible audit framework that will publish events once Spring
|
|
Security is in play ('`authentication success`', '`failure`' and '`access denied`'
|
|
exceptions by default). This can be very useful for reporting, and also to implement a
|
|
lock-out policy based on authentication failures. To customize published security events
|
|
you can provide your own implementations of `AbstractAuthenticationAuditListener` and
|
|
`AbstractAuthorizationAuditListener`.
|
|
|
|
You can also choose to use the audit services for your own business events. To do that
|
|
you can either inject the existing `AuditEventRepository` into your own components and
|
|
use that directly, or you can simply publish `AuditApplicationEvent` via the Spring
|
|
`ApplicationEventPublisher` (using `ApplicationEventPublisherAware`).
|
|
|
|
|
|
|
|
[[production-ready-tracing]]
|
|
== Tracing
|
|
Tracing is automatically enabled for all HTTP requests. You can view the `trace` endpoint
|
|
and obtain basic information about the last 100 requests:
|
|
|
|
[source,json,indent=0]
|
|
----
|
|
[{
|
|
"timestamp": 1394343677415,
|
|
"info": {
|
|
"method": "GET",
|
|
"path": "/trace",
|
|
"headers": {
|
|
"request": {
|
|
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
|
|
"Connection": "keep-alive",
|
|
"Accept-Encoding": "gzip, deflate",
|
|
"User-Agent": "Mozilla/5.0 Gecko/Firefox",
|
|
"Accept-Language": "en-US,en;q=0.5",
|
|
"Cookie": "_ga=GA1.1.827067509.1390890128; ..."
|
|
"Authorization": "Basic ...",
|
|
"Host": "localhost:8080"
|
|
},
|
|
"response": {
|
|
"Strict-Transport-Security": "max-age=31536000 ; includeSubDomains",
|
|
"X-Application-Context": "application:8080",
|
|
"Content-Type": "application/json;charset=UTF-8",
|
|
"status": "200"
|
|
}
|
|
}
|
|
}
|
|
},{
|
|
"timestamp": 1394343684465,
|
|
...
|
|
}]
|
|
----
|
|
|
|
The following are included in the trace by default:
|
|
|
|
[cols="1,2"]
|
|
|===
|
|
|Name |Description
|
|
|
|
|Request Headers
|
|
|Headers from the request.
|
|
|
|
|Response Headers
|
|
|Headers from the response.
|
|
|
|
|Cookies
|
|
|`Cookie` from request headers and `Set-Cookie` from response headers.
|
|
|
|
|Errors
|
|
|The error attributes (if any).
|
|
|
|
|Time Taken
|
|
|The time taken to service the request in milliseconds.
|
|
|===
|
|
|
|
|
|
|
|
[[production-ready-custom-tracing]]
|
|
=== Custom tracing
|
|
If you need to trace additional events you can inject a
|
|
{sc-spring-boot-actuator}/trace/TraceRepository.{sc-ext}[`TraceRepository`] into your
|
|
Spring beans. The `add` method accepts a single `Map` structure that will be converted to
|
|
JSON and logged.
|
|
|
|
By default an `InMemoryTraceRepository` will be used that stores the last 100 events. You
|
|
can define your own instance of the `InMemoryTraceRepository` bean if you need to expand
|
|
the capacity. You can also create your own alternative `TraceRepository` implementation
|
|
if needed.
|
|
|
|
|
|
|
|
[[production-ready-process-monitoring]]
|
|
== Process monitoring
|
|
In Spring Boot Actuator you can find a couple of classes to create files that are useful
|
|
for process monitoring:
|
|
|
|
* `ApplicationPidFileWriter` creates a file containing the application PID (by default in
|
|
the application directory with the file name `application.pid`).
|
|
* `EmbeddedServerPortFileWriter` creates a file (or files) containing the ports of the
|
|
embedded server (by default in the application directory with the file name
|
|
`application.port`).
|
|
|
|
These writers are not activated by default, but you can enable them in one of the ways
|
|
described below.
|
|
|
|
|
|
|
|
[[production-ready-process-monitoring-configuration]]
|
|
=== Extend configuration
|
|
In `META-INF/spring.factories` file you can activate the listener(s) that
|
|
writes a PID file. Example:
|
|
|
|
[indent=0]
|
|
----
|
|
org.springframework.context.ApplicationListener=\
|
|
org.springframework.boot.system.ApplicationPidFileWriter,\
|
|
org.springframework.boot.actuate.system.EmbeddedServerPortFileWriter
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-process-monitoring-programmatically]]
|
|
=== Programmatically
|
|
You can also activate a listener by invoking the `SpringApplication.addListeners(...)`
|
|
method and passing the appropriate `Writer` object. This method also allows you to
|
|
customize the file name and path via the `Writer` constructor.
|
|
|
|
|
|
|
|
[[production-ready-cloudfoundry]]
|
|
== Cloud Foundry support
|
|
Spring Boot's actuator module includes additional support that is activated when you
|
|
deploy to a compatible Cloud Foundry instance. The `/cloudfoundryapplication` path
|
|
provides an alternative secured route to all `NamedMvcEndpoint` beans.
|
|
|
|
The extended support allows Cloud Foundry management UIs (such as the web
|
|
application that you can use to view deployed applications) to be augmented with Spring
|
|
Boot actuator information. For example, an application status page may include full health
|
|
information instead of the typical "`running`" or "`stopped`" status.
|
|
|
|
NOTE: The `/cloudfoundryapplication` path is not directly accessible to regular users.
|
|
In order to use the endpoint a valid UAA token must be passed with the request.
|
|
|
|
|
|
|
|
[[production-ready-cloudfoundry-disable]]
|
|
=== Disabling extended Cloud Foundry actuator support
|
|
If you want to fully disable the `/cloudfoundryapplication` endpoints you can add the
|
|
following to your `application.properties` file:
|
|
|
|
|
|
.application.properties
|
|
[source,properties,indent=0]
|
|
----
|
|
management.cloudfoundry.enabled=false
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-cloudfoundry-ssl]]
|
|
=== Cloud Foundry self signed certificates
|
|
By default, the security verification for `/cloudfoundryapplication` endpoints makes SSL
|
|
calls to various Cloud Foundry services. If your Cloud Foundry UAA or Cloud Controller
|
|
services use self-signed certificates you will need to set the following property:
|
|
|
|
.application.properties
|
|
[source,properties,indent=0]
|
|
----
|
|
management.cloudfoundry.skip-ssl-validation=true
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-cloudfoundry-custom-security]]
|
|
=== Custom security configuration
|
|
If you define custom security configuration, and you want extended Cloud Foundry actuator
|
|
support, you'll should ensure that `/cloudfoundryapplication/**` paths are open. Without
|
|
a direct open route, your Cloud Foundry application manager will not be able to obtain
|
|
endpoint data.
|
|
|
|
For Spring Security, you'll typically include something like
|
|
`mvcMatchers("/cloudfoundryapplication/**").permitAll()` in your configuration:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
include::{code-examples}/cloudfoundry/CloudFoundryIgnorePathsExample.java[tag=security]
|
|
----
|
|
|
|
|
|
|
|
[[production-ready-whats-next]]
|
|
== What to read next
|
|
If you want to explore some of the concepts discussed in this chapter, you can take a
|
|
look at the actuator {github-code}/spring-boot-samples[sample applications]. You also
|
|
might want to read about graphing tools such as http://graphite.wikidot.com/[Graphite].
|
|
|
|
Otherwise, you can continue on, to read about <<deployment.adoc#deployment,
|
|
'`deployment options`'>> or jump ahead
|
|
for some in-depth information about Spring Boot's
|
|
_<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_.
|