mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-09-03 04:26:12 +08:00
Format production-ready-features.adoc to 90 chars
Remove extraneous white space and adjusted the length of non-code lines to be as close to 90 characters (but not over 90 characters) as possible. Update a couple things I missed in the editing pass, too. Closes gh-10897
This commit is contained in:
Jay Bryant
Phillip Webb
parent
92e0eb0230
commit
9fc9c55c90
@ -57,10 +57,10 @@ Actuator endpoints let you monitor and interact with your application. Spring Bo
|
||||
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
|
||||
`/application` is mapped to a URL. For example, by default, the `health` endpoint is
|
||||
mapped to `/application/health`.
|
||||
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 `/application` is mapped to a URL. For example, by default, the `health`
|
||||
endpoint is mapped to `/application/health`.
|
||||
|
||||
The following technology-agnostic endpoints are available:
|
||||
|
||||
@ -171,8 +171,8 @@ user authentication. When '`Spring Security`' is added, by default, '`basic`'
|
||||
authentication is used. The username is`user` and the password is a random generated
|
||||
password (which is printed on the console when the application starts).
|
||||
|
||||
TIP: Generated passwords are logged as the application starts. To find the password in the
|
||||
console, search for '`Using default security password`'.
|
||||
TIP: Generated passwords are logged as the application starts. To find the password in
|
||||
the console, 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
|
||||
@ -187,8 +187,8 @@ following properties in your `application.properties`:
|
||||
|
||||
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. Also, you need to change the `management.security.enabled`
|
||||
property to `false`.
|
||||
in your security configuration. Also, 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
|
||||
@ -203,11 +203,11 @@ additional role check.
|
||||
|
||||
[[production-ready-customizing-endpoints]]
|
||||
=== Customizing Endpoints
|
||||
Endpoints can be customized by using Spring properties. You can change whether an endpoint
|
||||
is `enabled` and its `id`.
|
||||
Endpoints can be customized by using Spring properties. You can change whether an
|
||||
endpoint is `enabled` and its `id`.
|
||||
|
||||
For example, the following `application.properties` changes the id of the `beans` endpoint
|
||||
and also enables `shutdown`:
|
||||
For example, the following `application.properties` changes the id of the `beans`
|
||||
endpoint and also enables `shutdown`:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
@ -218,9 +218,9 @@ and also enables `shutdown`:
|
||||
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.default.enabled` property. For
|
||||
example, the following settings disables _all_ endpoints except for `info`:
|
||||
By default, all endpoints except for `shutdown` are enabled. If you prefer to
|
||||
specifically "`opt-in`" endpoint enablement, you can use the `endpoints.default.enabled`
|
||||
property. For example, the following settings disables _all_ endpoints except for `info`:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
@ -272,29 +272,29 @@ application, over HTTP as well.
|
||||
|
||||
TIP: If you do 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
|
||||
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.
|
||||
`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
|
||||
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
|
||||
often used by monitoring software to alert someone when 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. 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.
|
||||
{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.
|
||||
|
||||
|
||||
|
||||
@ -373,12 +373,13 @@ NOTE: The identifier for a given `HealthIndicator` is the name of the bean witho
|
||||
`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
|
||||
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.
|
||||
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
|
||||
@ -389,8 +390,8 @@ to your application properties:
|
||||
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
|
||||
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):
|
||||
|
||||
@ -454,8 +455,8 @@ 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:
|
||||
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]
|
||||
----
|
||||
@ -485,8 +486,8 @@ Assuming you use Maven, you could rewrite the preceding example as follows:
|
||||
==== 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.
|
||||
`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
|
||||
@ -504,9 +505,9 @@ If you want to display the full git information (that is, the full content of
|
||||
|
||||
[[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.
|
||||
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.
|
||||
@ -564,10 +565,10 @@ exposed as `/application/health`.
|
||||
|
||||
[[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 `/application` 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:
|
||||
Sometimes, it is useful to customize the prefix for the management endpoints. For
|
||||
example, your application might already use `/application` 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]
|
||||
----
|
||||
@ -591,18 +592,18 @@ Exposing management endpoints by using the default HTTP port is a sensible choic
|
||||
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:
|
||||
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
|
||||
----
|
||||
|
||||
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 should have Spring Security on the classpath, and you can
|
||||
disable management security as follows:
|
||||
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 should have Spring Security on the classpath,
|
||||
and you can disable management security as follows:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
@ -682,10 +683,10 @@ If you do not want to expose endpoints over HTTP, you can set the management por
|
||||
|
||||
[[production-ready-health-access-restrictions]]
|
||||
=== HTTP Health Endpoint Format and Access Restrictions
|
||||
The information exposed by the health endpoint varies, depending on whether it is accessed
|
||||
anonymously and whether 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 indicates whether the server is up or down.
|
||||
The information exposed by the health endpoint varies, depending on whether it is
|
||||
accessed anonymously and whether 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 indicates whether the server is up or down.
|
||||
|
||||
The following example shows a summarized HTTP response (default for anonymous request):
|
||||
|
||||
@ -745,8 +746,8 @@ The following example shows a detailed HTTP response:
|
||||
[[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.
|
||||
applications. By default, Spring Boot exposes management endpoints as JMX MBeans under
|
||||
the `org.springframework.boot` domain.
|
||||
|
||||
|
||||
|
||||
@ -831,9 +832,9 @@ If you use Jolokia but do not want Spring Boot to configure it, set the
|
||||
== 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:
|
||||
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`
|
||||
@ -879,9 +880,9 @@ monitoring systems:
|
||||
- https://prometheus.io[Prometheus]
|
||||
|
||||
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].
|
||||
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].
|
||||
|
||||
|
||||
|
||||
@ -889,8 +890,8 @@ https://micrometer.io/docs[reference documentation].
|
||||
=== Spring MVC Metrics
|
||||
Auto-configuration enables the instrumentation of requests handled by Spring MVC. When
|
||||
`spring.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.
|
||||
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 `spring.metrics.web.server.requests-metrics-name` property.
|
||||
@ -970,10 +971,10 @@ following information:
|
||||
[[production-ready-metrics-jdbc]]
|
||||
=== DataSource metrics
|
||||
Auto-configuration will enable the instrumentation of all available `DataSources` 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 which is prefixed by `data.source` by default. The prefix can be
|
||||
be customized using the `spring.metrics.jdbc.datasource-metric-name` property.
|
||||
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 which is prefixed by `data.source` by default. The prefix can
|
||||
be customized by using the `spring.metrics.jdbc.datasource-metric-name` property.
|
||||
|
||||
Metrics will also be tagged by the name of the `DataSource` computed based on the bean
|
||||
name.
|
||||
@ -1126,8 +1127,8 @@ 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.
|
||||
`InMemoryTraceRepository` bean. You can also create your own alternative
|
||||
`TraceRepository` implementation.
|
||||
|
||||
|
||||
|
||||
@ -1136,11 +1137,11 @@ implementation.
|
||||
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 the file name, `application.pid`).
|
||||
* `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`).
|
||||
embedded server (by default, in the application directory with the file name
|
||||
`application.port`).
|
||||
|
||||
By default, these writers are not activated, but you can enable them in one of the ways
|
||||
described in the next section.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user