86 lines
5.0 KiB
Plaintext
86 lines
5.0 KiB
Plaintext
[[howto.actuator]]
|
|
== Actuator
|
|
Spring Boot includes the Spring Boot Actuator.
|
|
This section answers questions that often arise from its use.
|
|
|
|
|
|
|
|
[[howto.actuator.change-http-port-or-address]]
|
|
=== Change the HTTP Port or Address of the Actuator Endpoints
|
|
In a standalone application, the Actuator HTTP port defaults to the same as the main HTTP port.
|
|
To make the application listen on a different port, set the external property: configprop:management.server.port[].
|
|
To listen on a completely different network address (such as when you have an internal network for management and an external one for user applications), you can also set `management.server.address` to a valid IP address to which the server is able to bind.
|
|
|
|
For more detail, see the {spring-boot-actuator-autoconfigure-module-code}/web/server/ManagementServerProperties.java[`ManagementServerProperties`] source code and "`<<actuator#actuator.monitoring.customizing-management-server-port>>`" in the "`Production-ready features`" section.
|
|
|
|
|
|
|
|
[[howto.actuator.customize-whitelabel-error-page]]
|
|
=== Customize the '`whitelabel`' Error Page
|
|
Spring Boot installs a '`whitelabel`' error page that you see in a browser client if you encounter a server error (machine clients consuming JSON and other media types should see a sensible response with the right error code).
|
|
|
|
NOTE: Set `server.error.whitelabel.enabled=false` to switch the default error page off.
|
|
Doing so restores the default of the servlet container that you are using.
|
|
Note that Spring Boot still tries to resolve the error view, so you should probably add your own error page rather than disabling it completely.
|
|
|
|
Overriding the error page with your own depends on the templating technology that you use.
|
|
For example, if you use Thymeleaf, you can add an `error.html` template.
|
|
If you use FreeMarker, you can add an `error.ftlh` template.
|
|
In general, you need a `View` that resolves with a name of `error` or a `@Controller` that handles the `/error` path.
|
|
Unless you replaced some of the default configuration, you should find a `BeanNameViewResolver` in your `ApplicationContext`, so a `@Bean` named `error` would be one way of doing that.
|
|
See {spring-boot-autoconfigure-module-code}/web/servlet/error/ErrorMvcAutoConfiguration.java[`ErrorMvcAutoConfiguration`] for more options.
|
|
|
|
See also the section on "`<<web#web.servlet.spring-mvc.error-handling, Error Handling>>`" for details of how to register handlers in the servlet container.
|
|
|
|
|
|
|
|
[[howto.actuator.sanitize-sensitive-values]]
|
|
=== Sanitize Sensitive Values
|
|
Information returned by the `/env`, `/configprops` and `/quartz` endpoints can be somewhat sensitive.
|
|
All values are sanitized by default (that is replaced by `+******+`).
|
|
Viewing original values in the unsanitized form can be configured per endpoint using the `showValues` property for that endpoint.
|
|
This property can be configured to have the following values:
|
|
|
|
- `ALWAYS` - all values are shown in their unsanitized form to all users
|
|
- `NEVER` - all values are always sanitized (that is replaced by `+******+`)
|
|
- `WHEN_AUTHORIZED` - all values are shown in their unsanitized form to authorized users
|
|
|
|
For HTTP endpoints, a user is considered to be authorized if they have authenticated and have the roles configured by the endpoint's roles property.
|
|
By default, any authenticated user is authorized.
|
|
For JMX endpoints, all users are always authorized.
|
|
|
|
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
|
----
|
|
management:
|
|
endpoint:
|
|
env:
|
|
show-values: WHEN_AUTHORIZED
|
|
roles: "admin"
|
|
----
|
|
|
|
The configuration above enables the ability for all users with the `admin` role to view all values in their original form from the `/env` endpoint.
|
|
|
|
NOTE: When `show-values` is set to `ALWAYS` or `WHEN_AUTHORIZED` any sanitization applied by a `<<howto#howto.actuator.sanitize-sensitive-values.customizing-sanitization, SanitizingFunction>>` will still be applied.
|
|
|
|
|
|
|
|
[[howto.actuator.sanitize-sensitive-values.customizing-sanitization]]
|
|
==== Customizing Sanitization
|
|
To take control over the sanitization, define a `SanitizingFunction` bean.
|
|
The `SanitizableData` with which the function is called provides access to the key and value as well as the `PropertySource` from which they came.
|
|
This allows you to, for example, sanitize every value that comes from a particular property source.
|
|
Each `SanitizingFunction` is called in order until a function changes the value of the sanitizable data.
|
|
|
|
|
|
|
|
[[howto.actuator.map-health-indicators-to-metrics]]
|
|
=== Map Health Indicators to Micrometer Metrics
|
|
Spring Boot health indicators return a `Status` type to indicate the overall system health.
|
|
If you want to monitor or alert on levels of health for a particular application, you can export these statuses as metrics with Micrometer.
|
|
By default, the status codes "`UP`", "`DOWN`", "`OUT_OF_SERVICE`" and "`UNKNOWN`" are used by Spring Boot.
|
|
To export these, you will need to convert these states to some set of numbers so that they can be used with a Micrometer `Gauge`.
|
|
|
|
The following example shows one way to write such an exporter:
|
|
|
|
include::code:MyHealthMetricsExportConfiguration[]
|