1348 lines
45 KiB
Plaintext
1348 lines
45 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 you push it to production. You can choose to manage and monitor your
|
||
application by using HTTP endpoints or with JMX. Auditing, health, and metrics gathering
|
||
can also be automatically applied to your application.
|
||
--
|
||
|
||
|
||
|
||
[[production-ready-enabling]]
|
||
== Enabling Production-ready Features
|
||
The {github-code}/spring-boot-project/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 that refers 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 following declaration:
|
||
|
||
[source,groovy,indent=0]
|
||
----
|
||
dependencies {
|
||
compile("org.springframework.boot:spring-boot-starter-actuator")
|
||
}
|
||
----
|
||
|
||
|
||
|
||
[[production-ready-endpoints]]
|
||
== Endpoints
|
||
Actuator endpoints let you monitor and interact with your application. Spring Boot
|
||
includes a number of built-in endpoints and lets you add your own. For example, the
|
||
`health` endpoint provides basic application health information.
|
||
|
||
The way that endpoints are exposed depends on the type of technology that you choose.
|
||
Most applications choose HTTP monitoring, where the ID of the endpoint along with a
|
||
prefix of `/actuator` is mapped to a URL. For example, by default, the `health`
|
||
endpoint is mapped to `/actuator/health`.
|
||
|
||
The following technology-agnostic endpoints are available:
|
||
|
||
[cols="2,5"]
|
||
|===
|
||
| ID | Description
|
||
|
||
|`auditevents`
|
||
|Exposes audit events information for the current application.
|
||
|
||
|`beans`
|
||
|Displays a complete list of all the Spring beans in your application.
|
||
|
||
|`conditions`
|
||
|Shows the conditions that were evaluated on configuration and auto-configuration
|
||
classes and the reasons why they did or did not match.
|
||
|
||
|`configprops`
|
||
|Displays a collated list of all `@ConfigurationProperties`.
|
||
|
||
|`env`
|
||
|Exposes properties from Spring's `ConfigurableEnvironment`.
|
||
|
||
|`flyway`
|
||
|Shows any Flyway database migrations that have been applied.
|
||
|
||
|`health`
|
||
|Shows application health information.
|
||
|
||
|`info`
|
||
|Displays arbitrary application info.
|
||
|
||
|`loggers`
|
||
|Shows and modifies the configuration of loggers in the application.
|
||
|
||
|`liquibase`
|
||
|Shows any Liquibase database migrations that have been applied.
|
||
|
||
|`metrics`
|
||
|Shows '`metrics`' information for the current application.
|
||
|
||
|`mappings`
|
||
|Displays a collated list of all `@RequestMapping` paths.
|
||
|
||
|`scheduledtasks`
|
||
|Displays the scheduled tasks in your application.
|
||
|
||
|`sessions`
|
||
|Allows retrieval and deletion of user sessions from a Spring Session-backed session
|
||
store. Not available when using Spring Session's support for reactive web applications.
|
||
|
||
|`shutdown`
|
||
|Lets the application be gracefully shutdown (not enabled by default).
|
||
|
||
|`threaddump`
|
||
|Performs a thread dump.
|
||
|
||
|`trace`
|
||
|Displays trace information (by default, the last 100 HTTP requests).
|
||
|===
|
||
|
||
If your application is a web application (Spring MVC, Spring WebFlux, or Jersey), you can
|
||
use the following additional endpoints:
|
||
|
||
[cols="2,5"]
|
||
|===
|
||
| ID | Description
|
||
|
||
|`heapdump`
|
||
|Returns a GZip compressed `hprof` heap dump file.
|
||
|
||
|`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.
|
||
|
||
|`prometheus`
|
||
|Exposes metrics in a format that can be scraped by a Prometheus server.
|
||
|
||
|
||
|`jolokia`
|
||
|Exposes JMX beans over HTTP (when Jolokia is on the classpath, not availble for WebFlux).
|
||
|
||
|===
|
||
|
||
|
||
To learn more about the Actuator's endpoints and their request and response formats,
|
||
please refer to the separate API documentation ({spring-boot-actuator-api}/html[HTML] or
|
||
{spring-boot-actuator-api}/pdf/spring-boot-actuator-web-api.pdf[PDF]).
|
||
|
||
|
||
|
||
[[production-ready-endpoints-exposing-endpoints]]
|
||
=== Exposing Endpoints
|
||
Since Endpoints may contain sensitive information, careful consideration should be given
|
||
about when to expose them. By default, Spring Boot exposes all enabled endpoints
|
||
over JMX but only the `health` and `info` endpoints over HTTP.
|
||
|
||
To change the endpoints that are exposed, you can use the `expose` and `exclude` property
|
||
for the technology. For example, to only expose the `health` over JMX you would set the
|
||
following property:
|
||
|
||
.application.properties
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.jmx.expose=health
|
||
----
|
||
|
||
The `*` character can be used to indicate all endpoints. For example, to expose everything
|
||
over HTTP except the `env` endpoint, you would use the following properties:
|
||
|
||
.application.properties
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.web.expose=*
|
||
management.endpoints.web.exclude=env
|
||
----
|
||
|
||
NOTE: If your application is exposed publicly, we strongly recommend that you also
|
||
<<production-ready-endpoints-security, secure your endpoints>>.
|
||
|
||
TIP: If you want to implement your own strategy for when endpoints are exposed, you can
|
||
register an `EndpointFilter` bean.
|
||
|
||
|
||
|
||
[[production-ready-endpoints-security]]
|
||
=== Securing HTTP Endpoints
|
||
You should take care to secure HTTP endpoints in the same way that you would any other
|
||
sensitive URL. If Spring Security is present, endpoints are secured by default using Spring Security’s
|
||
content-negotiation strategy. If you wish to configure custom security for HTTP endpoints, for example, only allow users
|
||
with a certain role to access them, Spring Boot provides some convenient `RequestMatcher` objects that can be used in combination with
|
||
Spring Security.
|
||
|
||
A typical Spring Security configuration might look something like the following example:
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
@Configuration
|
||
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
|
||
|
||
@Override
|
||
protected void configure(HttpSecurity http) throws Exception {
|
||
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
|
||
.anyRequest().hasRole("ENDPOINT_ADMIN")
|
||
.and()
|
||
.httpBasic();
|
||
}
|
||
|
||
}
|
||
----
|
||
|
||
The preceding example uses `EndpointRequest.toAnyEndpoint()` to match a request to any
|
||
endpoint and then ensures that all have the `ENDPOINT_ADMIN` role. Several other matcher
|
||
methods are also available on `EndpointRequest`. See the API documentation
|
||
({spring-boot-actuator-api}/html[HTML] or
|
||
{spring-boot-actuator-api}/pdf/spring-boot-actuator-web-api.pdf[PDF]) for details.
|
||
|
||
If you deploy applications behind a firewall, you may prefer that all your actuator
|
||
endpoints can be accessed without requiring authentication. You can do so by changing the
|
||
`management.endpoints.web.expose` property, as follows:
|
||
|
||
.application.properties
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.web.expose=*
|
||
----
|
||
|
||
Additionally, if Spring Security is present, you would need to add custom security configuration
|
||
that allows unauthenticated access to the endpoints. For example,
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
@Configuration
|
||
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
|
||
|
||
@Override
|
||
protected void configure(HttpSecurity http) throws Exception {
|
||
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
|
||
.anyRequest().permitAll()
|
||
}
|
||
|
||
}
|
||
----
|
||
|
||
|
||
|
||
[[production-ready-customizing-endpoints]]
|
||
=== Customizing Endpoints
|
||
Endpoints can be customized by using Spring properties. You can change whether an
|
||
endpoint is `enabled` and the amount of time for which it caches responses.
|
||
|
||
For example, the following `application.properties` file changes the time-to-live of the
|
||
`beans` endpoint to 10 seconds and also enables `shutdown`:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoint.beans.cache.time-to-live=10s
|
||
management.endpoint.shutdown.enabled=true
|
||
----
|
||
|
||
NOTE: The prefix `management.endpoint.<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
|
||
`management.endpoints.enabled-by-default` property. For example, the following settings
|
||
disable _all_ endpoints except for `info`:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.enabled-by-default=false
|
||
management.endpoint.info.enabled=true
|
||
----
|
||
|
||
NOTE: Disabled endpoints are removed entirely from the `ApplicationContext`. If you want
|
||
to change only the technologies over which an endpoint is exposed, you can use the
|
||
`expose` and `exclude` properties (see <<production-ready-endpoints-exposing-endpoints>>).
|
||
|
||
|
||
|
||
[[production-ready-endpoint-hypermedia]]
|
||
=== Hypermedia for Actuator Web Endpoints
|
||
A "`discovery page`" is added with links to all the endpoints. The "`discovery page`" is
|
||
available on `/actuator` by default.
|
||
|
||
When a custom management context path is configured, the "`discovery page`" automatically
|
||
moves from `/actuator` to the root of the management context. For example, if the
|
||
management context path is `/management`, then the discovery page is available from
|
||
`/management`. When the management context path is set to `/`, the discovery page is
|
||
disabled to prevent the possibility of a clash with other mappings.
|
||
|
||
|
||
|
||
[[production-ready-endpoint-custom-mapping]]
|
||
=== Actuator Web Endpoint Paths
|
||
By default, endpoints are exposed over HTTP under the `/actuator` path by using the ID of
|
||
the endpoint. For example, the `beans` endpoint is exposed under `/actuator/beans`. If you
|
||
want to map endpoints to a different path, you can use the
|
||
`management.endpoints.web.path-mapping` property. Also, if you want change the base path,
|
||
you can use `management.endpoints.web.base-path`.
|
||
|
||
The following example remaps `/actuator/health` to `/healthcheck`:
|
||
|
||
.application.properties
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.web.base-path=/
|
||
management.endpoints.web.path-mapping.health=healthcheck
|
||
----
|
||
|
||
|
||
|
||
[[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 lets you specify in a
|
||
flexible way what kind of cross-domain requests are authorized. If you use Spring MVC or
|
||
Spring WebFlux, Actuator's web endpoints can be configured to support such scenarios.
|
||
|
||
CORS support is disabled by default and is only enabled once the
|
||
`management.endpoints.web.cors.allowed-origins` property has been set. The following
|
||
configuration permits `GET` and `POST` calls from the `example.com` domain:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.web.cors.allowed-origins=http://example.com
|
||
management.endpoints.web.cors.allowed-methods=GET,POST
|
||
----
|
||
|
||
TIP: See
|
||
{sc-spring-boot-actuator-autoconfigure}/endpoint/web/CorsEndpointProperties.{sc-ext}[CorsEndpointProperties]
|
||
for a complete list of options.
|
||
|
||
|
||
|
||
[[production-ready-customizing-endpoints-programmatically]]
|
||
=== Adding Custom Endpoints
|
||
If you add a `@Bean` annotated with `@Endpoint`, any methods annotated with
|
||
`@ReadOperation`, `@WriteOperation`, or `@DeleteOperation` are automatically exposed over
|
||
JMX and, in a web application, over HTTP as well.
|
||
|
||
You can also write technology-specific endpoints by using `@JmxEndpoint` or
|
||
`@WebEndpoint`. These endpoints are filtered to their respective technologies. For
|
||
example, `@WebEndpoint` is exposed only over HTTP and not over JMX.
|
||
|
||
Finally, you can write technology-specific extensions by using `@EndpointWebExtension` and
|
||
`@EndpointJmxExtension`. These annotations let you provide technology-specific operations
|
||
to augment an existing endpoint.
|
||
|
||
TIP: If you add endpoints as a library feature, consider adding a configuration class
|
||
annotated with `@ManagementContextConfiguration` to `/META-INF/spring.factories` under the
|
||
following key:
|
||
`org.springframework.boot.actuate.autoconfigure.ManagementContextConfiguration`. If you do
|
||
so and if your users ask for a separate management port or address, the endpoint moves to
|
||
a child context with all the other web endpoints.
|
||
|
||
|
||
|
||
[[production-ready-health]]
|
||
=== Health Information
|
||
You can use health information to check the status of your running application. It is
|
||
often used by monitoring software to alert someone when a production system goes down.
|
||
The information exposed by the `health` endpoint depends on the
|
||
`management.endpoint.health.show-details` property. By default, the property's value is
|
||
`false` and a simple "`status`" message is returned. When the property's value is set to
|
||
`true`, additional details from the individual health indicators are also displayed.
|
||
|
||
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.
|
||
|
||
|
||
|
||
==== Auto-configured HealthIndicators
|
||
The following `HealthIndicators` are auto-configured by Spring Boot when appropriate:
|
||
|
||
[cols="4,6"]
|
||
|===
|
||
|Name |Description
|
||
|
||
|{sc-spring-boot-actuator}/cassandra/CassandraHealthIndicator.{sc-ext}[`CassandraHealthIndicator`]
|
||
|Checks that a Cassandra database is up.
|
||
|
||
|{sc-spring-boot-actuator}/system/DiskSpaceHealthIndicator.{sc-ext}[`DiskSpaceHealthIndicator`]
|
||
|Checks for low disk space.
|
||
|
||
|{sc-spring-boot-actuator}/jdbc/DataSourceHealthIndicator.{sc-ext}[`DataSourceHealthIndicator`]
|
||
|Checks that a connection to `DataSource` can be obtained.
|
||
|
||
|{sc-spring-boot-actuator}/elasticsearch/ElasticsearchHealthIndicator.{sc-ext}[`ElasticsearchHealthIndicator`]
|
||
|Checks that an Elasticsearch cluster is up.
|
||
|
||
|{sc-spring-boot-actuator}/influx/InfluxDbHealthIndicator.{sc-ext}[`InfluxDbHealthIndicator`]
|
||
|Checks that an InfluxDB server is up.
|
||
|
||
|{sc-spring-boot-actuator}/jms/JmsHealthIndicator.{sc-ext}[`JmsHealthIndicator`]
|
||
|Checks that a JMS broker is up.
|
||
|
||
|{sc-spring-boot-actuator}/mail/MailHealthIndicator.{sc-ext}[`MailHealthIndicator`]
|
||
|Checks that a mail server is up.
|
||
|
||
|{sc-spring-boot-actuator}/mongo/MongoHealthIndicator.{sc-ext}[`MongoHealthIndicator`]
|
||
|Checks that a Mongo database is up.
|
||
|
||
|{sc-spring-boot-actuator}/neo4j/Neo4jHealthIndicator.{sc-ext}[`Neo4jHealthIndicator`]
|
||
|Checks that a Neo4j server is up.
|
||
|
||
|{sc-spring-boot-actuator}/amqp/RabbitHealthIndicator.{sc-ext}[`RabbitHealthIndicator`]
|
||
|Checks that a Rabbit server is up.
|
||
|
||
|{sc-spring-boot-actuator}/redis/RedisHealthIndicator.{sc-ext}[`RedisHealthIndicator`]
|
||
|Checks that a Redis server is up.
|
||
|
||
|{sc-spring-boot-actuator}/solr/SolrHealthIndicator.{sc-ext}[`SolrHealthIndicator`]
|
||
|Checks that a Solr server is up.
|
||
|===
|
||
|
||
TIP: You can disable them all by setting 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. The following code shows a sample `HealthIndicator`
|
||
implementation:
|
||
|
||
[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 preceding example, the health information
|
||
is 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 by using
|
||
the `management.health.status.order` configuration property.
|
||
|
||
For example, assume a new `Status` with code `FATAL` is being used in one of your
|
||
`HealthIndicator` implementations. To configure the severity order, add the following
|
||
property 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 (for example,
|
||
`UP` maps to 200, while `OUT_OF_SERVICE` and `DOWN` map to 503). You might also want to
|
||
register custom status mappings if you access the health endpoint over HTTP. For example,
|
||
the following property maps `FATAL` to 503 (service unavailable):
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.health.status.http-mapping.FATAL=503
|
||
----
|
||
|
||
TIP: If you need more control, you can define your own `HealthStatusHttpMapper` bean.
|
||
|
||
The following table shows the default status mappings for the built-in statuses:
|
||
|
||
[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
|
||
|===
|
||
|
||
|
||
|
||
[[reactive-health-indicators]]
|
||
==== Reactive Health Indicators
|
||
For reactive applications, such as those using Spring WebFlux, `ReactiveHealthIndicator`
|
||
provides a non-blocking contract for getting application health. Similar to a traditional
|
||
`HealthIndicator`, health information is collected from all
|
||
{sc-spring-boot-actuator}/health/ReactiveHealthIndicator.{sc-ext}[`ReactiveHealthIndicator`]
|
||
beans defined in your `ApplicationContext`. Regular `HealthIndicator` beans that do not
|
||
check against a reactive API are included and executed on the elastic scheduler.
|
||
|
||
To provide custom health information from a reactive API, you can register Spring beans
|
||
that implement the
|
||
{sc-spring-boot-actuator}/health/ReactiveHealthIndicator.{sc-ext}[`ReactiveHealthIndicator`]
|
||
interface. The following code shows a sample `ReactiveHealthIndicator` implementation:
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
@Component
|
||
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {
|
||
|
||
@Override
|
||
public Mono<Health> health() {
|
||
return doHealthCheck() //perform some specific health check that returns a Mono<Health>
|
||
.onErrorResume(ex -> Mono.just(new Health.Builder().down(ex).build())));
|
||
}
|
||
|
||
}
|
||
----
|
||
|
||
TIP: To handle the error automatically, consider extending from
|
||
`AbstractReactiveHealthIndicator`.
|
||
|
||
|
||
|
||
==== Auto-configured ReactiveHealthIndicators
|
||
The following `ReactiveHealthIndicators` are auto-configured by Spring Boot when
|
||
appropriate:
|
||
|
||
[cols="1,4"]
|
||
|===
|
||
|Name |Description
|
||
|
||
|{sc-spring-boot-actuator}/redis/RedisReactiveHealthIndicator.{sc-ext}[`RedisReactiveHealthIndicator`]
|
||
|Checks that a Redis server is up.
|
||
|===
|
||
|
||
TIP: If necessary, reactive indicators replace the regular ones. Also, any
|
||
`HealthIndicator` that is not handled explicitly is wrapped automatically.
|
||
|
||
|
||
|
||
[[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
|
||
`InfoContributor` beans, and you can write your own.
|
||
|
||
[[production-ready-application-info-autoconfigure]]
|
||
==== Auto-configured InfoContributors
|
||
|
||
The following `InfoContributor` beans are auto-configured by Spring Boot, when
|
||
appropriate:
|
||
|
||
[cols="1,4"]
|
||
|===
|
||
|Name |Description
|
||
|
||
|{sc-spring-boot-actuator}/info/EnvironmentInfoContributor.{sc-ext}[`EnvironmentInfoContributor`]
|
||
|Exposes any key from the `Environment` under the `info` key.
|
||
|
||
|{sc-spring-boot-actuator}/info/GitInfoContributor.{sc-ext}[`GitInfoContributor`]
|
||
|Exposes git information if a `git.properties` file is available.
|
||
|
||
|{sc-spring-boot-actuator}/info/BuildInfoContributor.{sc-ext}[`BuildInfoContributor`]
|
||
|Exposes build information if a `META-INF/build-info.properties` file is available.
|
||
|===
|
||
|
||
TIP: It is possible to disable them all by setting the `management.info.defaults.enabled`
|
||
property.
|
||
|
||
[[production-ready-application-info-env]]
|
||
==== Custom Application Information
|
||
You can customize the data exposed by the `info` endpoint by setting `+info.*+` Spring
|
||
properties. All `Environment` properties under the `info` key are automatically exposed.
|
||
For example, you could add the following settings to your `application.properties` file:
|
||
|
||
[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 use Maven, you could rewrite the preceding example 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 are 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 (that is, the full content of
|
||
`git.properties`), use the `management.info.git.mode` property, as follows:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.info.git.mode=full
|
||
----
|
||
|
||
|
||
|
||
[[production-ready-application-info-build]]
|
||
==== Build Information
|
||
If a `BuildProperties` bean is available, the `info` endpoint can also publish
|
||
information about your build. 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 following example 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 reach 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 web application, Spring Boot Actuator auto-configures all
|
||
enabled endpoints to be exposed over HTTP. The default convention is to use the `id` of
|
||
the endpoint with a prefix of `/actuator` as the URL path. For example, `health` is
|
||
exposed as `/actuator/health`.
|
||
|
||
TIP: Actuator is supported natively with Spring MVC, Spring WebFlux, and Jersey.
|
||
|
||
|
||
|
||
[[production-ready-customizing-management-server-context-path]]
|
||
=== Customizing the Management Endpoint Paths
|
||
Sometimes, it is useful to customize the prefix for the management endpoints. For
|
||
example, your application might already use `/actuator` for another purpose. You can
|
||
use the `management.endpoints.web.base-path` property to change the prefix for your
|
||
management endpoint, as shown in the following example:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.web.base-path=/manage
|
||
----
|
||
|
||
The preceding `application.properties` example changes the endpoint from
|
||
`/actuator/{id}` to `/manage/{id}` (for example, `/manage/info`).
|
||
|
||
NOTE: Unless the management port has been configured to
|
||
<<production-ready-customizing-management-server-port,expose endpoints by using a
|
||
different HTTP port>>, `management.endpoints.web.base-path` is relative to
|
||
`server.servlet.context-path`. If `management.server.port` is configured,
|
||
`management.endpoints.web.base-path` is relative to
|
||
`management.server.servlet.context-path`.
|
||
|
||
|
||
|
||
[[production-ready-customizing-management-server-port]]
|
||
=== Customizing the Management Server Port
|
||
Exposing management endpoints by 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 by using a different HTTP port.
|
||
|
||
You can set the `management.server.port` property to change the HTTP port, as shown in
|
||
the following example:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.server.port=8081
|
||
----
|
||
|
||
|
||
|
||
[[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 by using the various `management.server.ssl.*` properties. For example, doing
|
||
so lets a management server be available over HTTP while the main application uses HTTPS,
|
||
as shown in the following property settings:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
server.port=8443
|
||
server.ssl.enabled=true
|
||
server.ssl.key-store=classpath:store.jks
|
||
server.ssl.key-password=secret
|
||
management.server.port=8080
|
||
management.server.ssl.enabled=false
|
||
----
|
||
|
||
Alternatively, both the main server and the management server can use SSL but with
|
||
different key stores, as follows:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
server.port=8443
|
||
server.ssl.enabled=true
|
||
server.ssl.key-store=classpath:main.jks
|
||
server.ssl.key-password=secret
|
||
management.server.port=8080
|
||
management.server.ssl.enabled=true
|
||
management.server.ssl.key-store=classpath:management.jks
|
||
management.server.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.server.address` property. Doing so can be useful if you want to listen
|
||
only on an internal or ops-facing network or to listen only for connections from
|
||
`localhost`.
|
||
|
||
NOTE: You can listen on a different address only when the port differs from the main
|
||
server port.
|
||
|
||
The following example `application.properties` does not allow remote management
|
||
connections:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.server.port=8081
|
||
management.server.address=127.0.0.1
|
||
----
|
||
|
||
|
||
|
||
[[production-ready-disabling-http-endpoints]]
|
||
=== Disabling HTTP Endpoints
|
||
If you do not want to expose endpoints over HTTP, you can set the management port to
|
||
`-1`, as shown in the following example:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.server.port=-1
|
||
----
|
||
|
||
|
||
|
||
[[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 exposes 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:type=Endpoint,name=Health`.
|
||
|
||
If your application contains more than one Spring `ApplicationContext`, you may find that
|
||
names clash. To solve this problem, you can set the
|
||
`management.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. The following
|
||
settings show an example of doing so in `application.properties`:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.jmx.domain=com.example.myapp
|
||
management.endpoints.jmx.unique-names=true
|
||
----
|
||
|
||
|
||
|
||
[[production-ready-disable-jmx-endpoints]]
|
||
=== Disabling JMX Endpoints
|
||
If you do not want to expose endpoints over JMX, you can set the
|
||
`management.endpoints.jmx.enabled` property to `false`, as shown in the following example:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoints.jmx.enabled=false
|
||
----
|
||
|
||
|
||
|
||
[[production-ready-jolokia]]
|
||
=== Using Jolokia for JMX over HTTP
|
||
Jolokia is a JMX-HTTP bridge that provides an alternative method of accessing JMX beans.
|
||
To use Jolokia, include a dependency to `org.jolokia:jolokia-core`. For example, with
|
||
Maven, you would add the following dependency:
|
||
|
||
[source,xml,indent=0]
|
||
----
|
||
<dependency>
|
||
<groupId>org.jolokia</groupId>
|
||
<artifactId>jolokia-core</artifactId>
|
||
</dependency>
|
||
----
|
||
|
||
The Jolokia endpoint can then be exposed by adding `jolokia` or `*` to the
|
||
`management.endpoints.web.expose` property. You can then be accessed it by using
|
||
`/actuator/jolokia` on your management HTTP server.
|
||
|
||
|
||
|
||
[[production-ready-customizing-jolokia]]
|
||
==== Customizing Jolokia
|
||
Jolokia has a number of settings that you would traditionally configure by setting servlet
|
||
parameters. With Spring Boot, you can use your `application.properties` file. To do so,
|
||
prefix the parameter with `management.endpont.jolokia.config.`, as shown in the following
|
||
example:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.endpoint.jolokia.config.debug=true
|
||
----
|
||
|
||
|
||
|
||
[[production-ready-disabling-jolokia]]
|
||
==== Disabling Jolokia
|
||
If you use Jolokia but do not want Spring Boot to configure it, set the
|
||
`management.endpoint.jolokia.enabled` property to `false`, as follows:
|
||
|
||
[source,properties,indent=0]
|
||
----
|
||
management.jolokia.enabled=false
|
||
----
|
||
|
||
|
||
|
||
[[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
|
||
one of:
|
||
|
||
* `TRACE`
|
||
* `DEBUG`
|
||
* `INFO`
|
||
* `WARN`
|
||
* `ERROR`
|
||
* `FATAL`
|
||
* `OFF`
|
||
* `null`
|
||
|
||
`null` indicates that there is no explicit configuration.
|
||
|
||
|
||
|
||
[[production-ready-logger-configuration]]
|
||
=== Configure a Logger
|
||
To configure a given logger, `POST` a partial entity to the resource's URI, as shown in
|
||
the following example:
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{
|
||
"configuredLevel": "DEBUG"
|
||
}
|
||
----
|
||
|
||
TIP: To "`reset`" the specific level of the logger (and use the default configuration
|
||
instead), you can pass a value of `null` as the `configuredLevel`.
|
||
|
||
|
||
|
||
[[production-ready-metrics]]
|
||
== Metrics
|
||
Spring Boot Actuator provides dependency management and auto-configuration for
|
||
https://micrometer.io[Micrometer], an application metrics facade that supports numerous
|
||
monitoring systems, including:
|
||
|
||
- https://github.com/Netflix/atlas[Atlas]
|
||
- https://www.datadoghq.com[Datadog]
|
||
- http://ganglia.sourceforge.net[Ganglia]
|
||
- https://graphiteapp.org[Graphite]
|
||
- https://www.influxdata.com[Influx]
|
||
- https://prometheus.io[Prometheus]
|
||
|
||
NOTE: At the time of this writing, the number of monitoring systems supported by
|
||
Micrometer is growing rapidly. See the https://micrometer.io[Micrometer project] for more
|
||
information.
|
||
|
||
Micrometer provides a separate module for each supported monitoring system. Depending on
|
||
one (or more) of these modules is sufficient to get started with Micrometer in your
|
||
Spring Boot application. To learn more about Micrometer's capabilities, please refer to
|
||
its https://micrometer.io/docs[reference documentation].
|
||
|
||
|
||
|
||
[[production-ready-metrics-spring-mvc]]
|
||
=== Spring MVC Metrics
|
||
Auto-configuration enables the instrumentation of requests handled by Spring MVC. When
|
||
`management.metrics.web.server.auto-time-requests` is `true`, this instrumentation occurs
|
||
for all requests. Alternatively, when set to `false`, you can enable instrumentation by
|
||
adding `@Timed` to a request-handling method.
|
||
|
||
By default, metrics are generated with the name, `http.server.requests`. The name can be
|
||
customized by setting the `management.metrics.web.server.requests-metric-name` property.
|
||
|
||
|
||
|
||
[[production-ready-metrics-spring-mvc-tags]]
|
||
==== Spring MVC Metric Tags
|
||
By default, Spring MVC-related metrics are tagged with the following information:
|
||
|
||
* The request's method.
|
||
* The request's URI (templated if possible).
|
||
* The simple class name of any exception that was thrown while handling the request.
|
||
* The response's status.
|
||
|
||
To customize the tags, provide a `@Bean` that implements `WebMvcTagsProvider`.
|
||
|
||
|
||
[[production-ready-metrics-web-flux]]
|
||
=== WebFlux Metrics
|
||
Auto-configuration enables the instrumentation of all requests handled by WebFlux
|
||
controllers. You can also use a helper class, `RouterFunctionMetrics`, to instrument
|
||
applications that use WebFlux's functional programming model.
|
||
|
||
By default, metrics are generated with the name `http.server.requests`. You can customize
|
||
the name by setting the `management.metrics.web.server.requests-metric-name` property.
|
||
|
||
|
||
|
||
[[production-ready-metrics-web-flux-tags]]
|
||
==== WebFlux Metrics Tags
|
||
By default, WebFlux-related metrics for the annotation-based programming model are tagged
|
||
with the following information:
|
||
|
||
* The request's method.
|
||
* The request's URI (templated if possible).
|
||
* The simple class name of any exception that was thrown while handling the request.
|
||
* The response's status.
|
||
|
||
To customize the tags, provide a `@Bean` that implements `WebFluxTagsProvider`.
|
||
|
||
By default, metrics for the functional programming model are tagged with the following
|
||
information:
|
||
|
||
* The request's method
|
||
* The request's URI (templated if possible).
|
||
* The response's status.
|
||
|
||
To customize the tags, use the `defaultTags` method on your `RouterFunctionMetrics`
|
||
instance.
|
||
|
||
|
||
|
||
[[production-ready-metrics-rest-template]]
|
||
=== RestTemplate Metrics
|
||
The instrumentation of any `RestTemplate` created using the auto-configured
|
||
`RestTemplateBuilder` is enabled. It is also possible to apply
|
||
`MetricsRestTemplateCustomizer` manually.
|
||
|
||
By default, metrics are generated with the name, `http.client.requests`. The name can be
|
||
customized by setting the `management.metrics.web.client.requests-metric-name` property.
|
||
|
||
|
||
|
||
[[production-ready-metrics-rest-template-tags]]
|
||
==== RestTemplate Metric Tags
|
||
By default, metrics generated by an instrumented `RestTemplate` are tagged with the
|
||
following information:
|
||
|
||
* The request's method.
|
||
* The request's URI (templated if possible).
|
||
* The response's status.
|
||
* The request URI's host.
|
||
|
||
|
||
|
||
[[production-ready-metrics-cache]]
|
||
=== Cache metrics
|
||
Auto-configuration will enable the instrumentation of all available ``Cache``s on startup
|
||
with a metric named `cache`. The prefix can be customized by using the
|
||
`management.metrics.cache.metric-name` property. Cache instrumentation is specific
|
||
to each cache library, refer to https://micrometer.io/docs[the micrometer documentation]
|
||
for more details.
|
||
|
||
The following cache libraries are supported:
|
||
|
||
* Caffeine
|
||
* EhCache 2
|
||
* Hazelcast
|
||
* Any compliant JCache (JSR-107) implementation
|
||
|
||
Metrics will also be tagged by the name of the `CacheManager` computed based on the bean
|
||
name.
|
||
|
||
NOTE: Only caches that are available on startup are bound to the registry. For 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.
|
||
|
||
|
||
|
||
[[production-ready-metrics-jdbc]]
|
||
=== DataSource Metrics
|
||
Auto-configuration enables the instrumentation of all available ``DataSource`` objects
|
||
with a metric named `data.source`. Data source instrumentation results in gauges
|
||
representing the currently active, maximum allowed, and minimum allowed connections in the
|
||
pool. Each of these gauges has a name that is prefixed by `data.source` by default. The
|
||
prefix can be customized by setting the `management.metrics.jdbc.metric-name`
|
||
property.
|
||
|
||
Metrics are also tagged by the name of the `DataSource` computed based on the bean name.
|
||
|
||
|
||
|
||
[[production-ready-metrics-rabbitmq]]
|
||
=== RabbitMQ metrics
|
||
Auto-configuration will enable the instrumentation of all available RabbitMQ connection
|
||
factories with a metric named `rabbitmq`. The prefix can be customized by using the
|
||
`management.metrics.rabbitmq.metric-name` property.
|
||
|
||
|
||
|
||
[[production-ready-metrics-integration]]
|
||
=== Spring Integration Metrics
|
||
Auto-configuration enables binding of a number of Spring Integration-related metrics:
|
||
|
||
.General metrics
|
||
|===
|
||
| Metric | Description
|
||
|
||
| `spring.integration.channelNames`
|
||
| Number of Spring Integration channels
|
||
|
||
| `spring.integration.handlerNames`
|
||
| Number of Spring Integration handlers
|
||
|
||
| `spring.integration.sourceNames`
|
||
| Number of Spring Integration sources
|
||
|===
|
||
|
||
.Channel metrics
|
||
|===
|
||
| Metric | Description
|
||
|
||
| `spring.integration.channel.receives`
|
||
| Number of receives
|
||
|
||
| `spring.integration.channel.sendErrors`
|
||
| Number of failed sends
|
||
|
||
| `spring.integration.channel.sends`
|
||
| Number of successful sends
|
||
|===
|
||
|
||
.Handler metrics
|
||
|===
|
||
| Metric | Description
|
||
|
||
| `spring.integration.handler.duration.max`
|
||
| Maximum handler duration in milliseconds
|
||
|
||
| `spring.integration.handler.duration.min`
|
||
| Minimum handler duration in milliseconds
|
||
|
||
| `spring.integration.handler.duration.mean`
|
||
| Mean handler duration in milliseconds
|
||
|
||
| `spring.integration.handler.activeCount`
|
||
| Number of active handlers
|
||
|===
|
||
|
||
.Source metrics
|
||
|===
|
||
| Metric | Description
|
||
|
||
| `spring.integration.source.messages`
|
||
| Number of successful source calls
|
||
|===
|
||
|
||
|
||
|
||
[[production-ready-auditing]]
|
||
== Auditing
|
||
Once Spring Security is in play, Spring Boot Actuator has a flexible audit framework that
|
||
publishes events (by default, "`authentication success`", "`failure`" and
|
||
"`access denied`" exceptions). This feature can be very useful for reporting and for
|
||
implementing 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 use the audit services for your own business events. To do so, either inject
|
||
the existing `AuditEventRepository` into your own components and use that directly or
|
||
publish an `AuditApplicationEvent` with the Spring `ApplicationEventPublisher` (by
|
||
implementing `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. The following listing shows
|
||
sample output:
|
||
|
||
[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,
|
||
...
|
||
}]
|
||
----
|
||
|
||
By default, the trace includes the following information:
|
||
|
||
[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 is converted to JSON
|
||
and logged.
|
||
|
||
By default, an `InMemoryTraceRepository` that stores the last 100 events is used. If you
|
||
need to expand the capacity, you can define your own instance of the
|
||
`InMemoryTraceRepository` bean. You can also create your own alternative
|
||
`TraceRepository` implementation.
|
||
|
||
|
||
|
||
[[production-ready-process-monitoring]]
|
||
== Process Monitoring
|
||
In the `spring-boot` module, you can find two classes to create files that are often
|
||
useful for process monitoring:
|
||
|
||
* `ApplicationPidFileWriter` creates a file containing the application PID (by default,
|
||
in the application directory with a file name of `application.pid`).
|
||
* `EmbeddedServerPortFileWriter` creates a file (or files) containing the ports of the
|
||
embedded server (by default, in the application directory with a file name of
|
||
`application.port`).
|
||
|
||
By default, these writers are not activated, but you can enable:
|
||
|
||
* <<production-ready-process-monitoring-configuration,By Extending Configuration>>
|
||
* <<production-ready-process-monitoring-programmatically>>
|
||
|
||
|
||
|
||
[[production-ready-process-monitoring-configuration]]
|
||
=== Extending Configuration
|
||
In the `META-INF/spring.factories` file, you can activate the listener(s) that writes a
|
||
PID file, as shown in the following example:
|
||
|
||
[indent=0]
|
||
----
|
||
org.springframework.context.ApplicationListener=\
|
||
org.springframework.boot.system.ApplicationPidFileWriter,\
|
||
org.springframework.boot.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 lets you customize
|
||
the file name and path in 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 `@Endpoint` beans.
|
||
|
||
The extended support lets Cloud Foundry management UIs (such as the web application that
|
||
you can use to view deployed applications) 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 setting 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 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 should ensure that `/cloudfoundryapplication/**` paths are open. Without a
|
||
direct open route, your Cloud Foundry application manager is not able to obtain endpoint
|
||
data.
|
||
|
||
For Spring Security, you typically include something like
|
||
`mvcMatchers("/cloudfoundryapplication/**").permitAll()` in your configuration, as shown
|
||
in the following example:
|
||
|
||
[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>>_.
|