Full editing pass plus linking
I made a complete editing pass plus another pass to see where I could add more links, both within the document and to other parts of Spring. The result was a thorough edit (though I'm sure I missed things, purely due to the size of the thing).
This commit is contained in:
Jay Bryant
@@ -67,8 +67,9 @@ as the original jar in the `target` directory:
|
||||
----
|
||||
|
||||
|
||||
If you do not include the `<execution/>` configuration as shown in the prior example, you
|
||||
can run the plugin on its own (but only if the package goal is used as well). For example:
|
||||
If you do not include the `<execution/>` configuration, as shown in the prior example, you
|
||||
can run the plugin on its own (but only if the package goal is used as well), as shown in
|
||||
the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
@@ -78,7 +79,7 @@ can run the plugin on its own (but only if the package goal is used as well). Fo
|
||||
----
|
||||
|
||||
If you use a milestone or snapshot release, you also need to add the appropriate
|
||||
`pluginRepository` elements as shown in the following listing:
|
||||
`pluginRepository` elements, as shown in the following listing:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
@@ -115,7 +116,7 @@ the usual `packaging` element, as shown in the following example:
|
||||
----
|
||||
|
||||
Your existing archive is enhanced by Spring Boot during the `package` phase. The main
|
||||
class that you want to launch can either be specified by using a configuration option or
|
||||
class that you want to launch can be specified either by using a configuration option or
|
||||
by adding a `Main-Class` attribute to the manifest in the usual way. If you do not specify
|
||||
a main class, the plugin searches for a class with a
|
||||
`public static void main(String[] args)` method.
|
||||
@@ -229,7 +230,7 @@ attributes are supported by the task:
|
||||
|
||||
|`start-class`
|
||||
|The main application class to run
|
||||
|No _(default is first class found declaring a `main` method)_
|
||||
|No _(the default is the first class found that declares a `main` method)_
|
||||
|====
|
||||
|
||||
The following nested elements can be used with the task:
|
||||
@@ -252,6 +253,9 @@ of the application.
|
||||
|
||||
|
||||
==== Examples
|
||||
|
||||
This section shows two examples of Ant tasks.
|
||||
|
||||
.Specify +start-class+
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
@@ -280,7 +284,7 @@ of the application.
|
||||
[[spring-boot-ant-findmainclass]]
|
||||
=== `spring-boot:findmainclass`
|
||||
The `findmainclass` task is used internally by `exejar` to locate a class declaring a
|
||||
`main`. You can also use this task directly in your build, if needed. The following
|
||||
`main`. If necessary, you can also use this task directly in your build. The following
|
||||
attributes are supported:
|
||||
|
||||
[cols="1,2,2"]
|
||||
@@ -303,6 +307,9 @@ attributes are supported:
|
||||
|
||||
|
||||
==== Examples
|
||||
|
||||
This section contains three examples of using `findmainclass`.
|
||||
|
||||
.Find and log
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
@@ -367,7 +374,7 @@ candidate is found.
|
||||
|
||||
[[build-tool-plugins-repackage-implementation]]
|
||||
=== Example Repackage Implementation
|
||||
The following listing shows a typical example repackage:
|
||||
The following example shows a typical repackage implementation:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
|
||||
@@ -17,16 +17,16 @@ This section covers some of the more common deployment scenarios.
|
||||
Spring Boot's executable jars are ready-made for most popular cloud PaaS
|
||||
(Platform-as-a-Service) providers. These providers tend to require that you
|
||||
"`bring your own container`". They manage application processes (not Java applications
|
||||
specifically), so they need some intermediary layer that adapts _your_ application to the
|
||||
specifically), so they need an intermediary layer that adapts _your_ application to the
|
||||
_cloud's_ notion of a running process.
|
||||
|
||||
Two popular cloud providers, Heroku and Cloud Foundry, employ a "`buildpack`" approach.
|
||||
The buildpack wraps your deployed code in whatever is needed to _start_ your application:
|
||||
it might be a JDK and a call to `java`, it might be an embedded web server, or it might be
|
||||
a full-fledged application server. A buildpack is pluggable, but ideally you should be
|
||||
able to get by with as few customizations to it as possible. This reduces the footprint of
|
||||
functionality that is not under your control. It minimizes divergence between development
|
||||
and production environments.
|
||||
The buildpack wraps your deployed code in whatever is needed to _start_ your application.
|
||||
It might be a JDK and a call to `java`, an embedded web server, or a full-fledged
|
||||
application server. A buildpack is pluggable, but ideally you should be able to get by
|
||||
with as few customizations to it as possible. This reduces the footprint of functionality
|
||||
that is not under your control. It minimizes divergence between development and production
|
||||
environments.
|
||||
|
||||
Ideally, your application, like a Spring Boot executable jar, has everything that it needs
|
||||
to run packaged within it.
|
||||
@@ -148,7 +148,7 @@ extracts them and flattens the data into properties that can be accessed through
|
||||
|
||||
All Cloud Foundry properties are prefixed with `vcap`. You can use `vcap` properties to
|
||||
access application information (such as the public URL of the application) and service
|
||||
information (such as database credentials). See
|
||||
information (such as database credentials). See the
|
||||
{dc-spring-boot}/cloud/CloudFoundryVcapEnvironmentPostProcessor.html['`CloudFoundryVcapEnvironmentPostProcessor`']
|
||||
Javadoc for complete details.
|
||||
|
||||
@@ -175,7 +175,7 @@ shows the `Procfile` for our starter REST application:
|
||||
|
||||
Spring Boot makes `-D` arguments available as properties accessible from a Spring
|
||||
`Environment` instance. The `server.port` configuration property is fed to the embedded
|
||||
Tomcat, Jetty, or Undertow instance which, then uses the port when it starts up. The `$PORT`
|
||||
Tomcat, Jetty, or Undertow instance, which then uses the port when it starts up. The `$PORT`
|
||||
environment variable is assigned to us by the Heroku PaaS.
|
||||
|
||||
This should be everything you need. The most common deployment workflow for Heroku
|
||||
@@ -234,8 +234,7 @@ https://www.openshift.com/[OpenShift] is the Red Hat public (and enterprise) ext
|
||||
the Kubernetes container orchestration platform. Similarly to Kubernetes, OpenShift has
|
||||
many options for installing Spring Boot based applications.
|
||||
|
||||
OpenShift has many resources describing how to deploy Spring Boot applications, which
|
||||
include:
|
||||
OpenShift has many resources describing how to deploy Spring Boot applications, including:
|
||||
|
||||
* https://blog.openshift.com/using-openshift-enterprise-grade-spring-boot-deployments/[Using the S2I builder]
|
||||
* https://access.redhat.com/documentation/en-us/reference_architectures/2017/html-single/spring_boot_microservices_on_red_hat_openshift_container_platform_3/[Architecture guide]
|
||||
@@ -255,7 +254,7 @@ server. The options include:
|
||||
* AWS Cloud Formation
|
||||
* AWS Container Registry
|
||||
|
||||
Each has different features and pricing model. In this document, we describe only the
|
||||
Each has different features and pricing models. In this document, we describe only the
|
||||
simplest option: AWS Elastic Beanstalk.
|
||||
|
||||
|
||||
@@ -269,8 +268,8 @@ either use the "`Tomcat Platform`" or the "`Java SE platform`".
|
||||
|
||||
|
||||
===== Using the Tomcat Platform
|
||||
This option applies to Spring Boot projects that produce a war file. There is no any
|
||||
special configuration required. You need only follow the official guide.
|
||||
This option applies to Spring Boot projects that produce a war file. No
|
||||
special configuration is required. You need only follow the official guide.
|
||||
|
||||
|
||||
|
||||
@@ -290,7 +289,7 @@ your `application.properties` file:
|
||||
.Upload binaries instead of sources
|
||||
====
|
||||
By default, Elastic Beanstalk uploads sources and compiles them in AWS. However, it is
|
||||
best to upload the binaries instead. To do so, add the following lines to your
|
||||
best to upload the binaries instead. To do so, add lines similar to the following to your
|
||||
`.elasticbeanstalk/config.yml` file:
|
||||
|
||||
|
||||
@@ -355,11 +354,11 @@ more options. If there is a https://boxfuse.com/docs/commandline/#configuration
|
||||
TIP: By default, Boxfuse activates a Spring profile named `boxfuse` on startup. If your
|
||||
executable jar or war contains an
|
||||
https://boxfuse.com/docs/payloads/springboot.html#configuration
|
||||
[`application-boxfuse.properties`] file, Boxfuse bases its configuration based on the
|
||||
[`application-boxfuse.properties`] file, Boxfuse bases its configuration on the
|
||||
properties it contains.
|
||||
|
||||
At this point, `boxfuse` creates an image for your application, uploads it, and configures
|
||||
and starts the necessary resources on AWS resulting in output similar to the following
|
||||
and starts the necessary resources on AWS, resulting in output similar to the following
|
||||
example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
@@ -405,7 +404,7 @@ it empty and then use the https://cloud.google.com/sdk/downloads[Google Cloud SD
|
||||
push your Spring Boot app into that slot from the command line or CI build.
|
||||
|
||||
App Engine needs you to create an `app.yaml` file to describe the resources your app
|
||||
requires. Normally you put this file in `src/main/appengine`, and it should resemble the
|
||||
requires. Normally, you put this file in `src/main/appengine`, and it should resemble the
|
||||
following file:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
@@ -464,11 +463,11 @@ can be executed like any other executable binary or it can be
|
||||
<<deployment-service,registered with `init.d` or `systemd`>>. This makes it very easy to
|
||||
install and manage Spring Boot applications in common production environments.
|
||||
|
||||
WARNING: Fully executable jars work by embedding an extra script at the front of the file.
|
||||
CAUTION: Fully executable jars work by embedding an extra script at the front of the file.
|
||||
Currently, some tools do not accept this format, so you may not always be able to use this
|
||||
technique. For example, `jar -xf` may silently fail to extract a jar or war that has been
|
||||
made fully executable. It is recommended that you only make your jar or war fully
|
||||
executable if you intend to execute it directly, rather than running it with `java -jar`
|
||||
made fully executable. It is recommended that you make your jar or war fully executable
|
||||
only if you intend to execute it directly, rather than running it with `java -jar`
|
||||
or deploying it to a servlet container.
|
||||
|
||||
To create a '`fully executable`' jar with Maven, use the following plugin configuration:
|
||||
@@ -516,7 +515,7 @@ Spring Boot application can be easily started as Unix/Linux services by using ei
|
||||
If you configured Spring Boot's Maven or Gradle plugin to generate a <<deployment-install,
|
||||
fully executable jar>>, and you do not use a custom `embeddedLaunchScript`, your
|
||||
application can be used as an `init.d` service. To do so, symlink the jar to `init.d` to
|
||||
support the standard `start`, `stop`, `restart` and `status` commands.
|
||||
support the standard `start`, `stop`, `restart`, and `status` commands.
|
||||
|
||||
The script supports the following features:
|
||||
|
||||
@@ -533,7 +532,7 @@ Spring Boot application as an `init.d` service, create a symlink, as follows:
|
||||
----
|
||||
|
||||
Once installed, you can start and stop the service in the usual way. For example, on a
|
||||
Debian based system, you could start it with the following command:
|
||||
Debian-based system, you could start it with the following command:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@@ -638,7 +637,7 @@ place it in `/etc/systemd/system` directory. The following script offers an exam
|
||||
WantedBy=multi-user.target
|
||||
----
|
||||
|
||||
IMPORTANT: Remember to change the `Description`, `User` and `ExecStart` fields for your
|
||||
IMPORTANT: Remember to change the `Description`, `User`, and `ExecStart` fields for your
|
||||
application.
|
||||
|
||||
NOTE: The `ExecStart` field does not declare the script action command, which means that
|
||||
@@ -666,7 +665,7 @@ Refer to `man systemctl` for more details.
|
||||
The default embedded startup script written by the Maven or Gradle plugin can be
|
||||
customized in a number of ways. For most people, using the default script along with a few
|
||||
customizations is usually enough. If you find you cannot customize something that you need
|
||||
to, you can always use the `embeddedLaunchScript` option to write your own file entirely.
|
||||
to, use the `embeddedLaunchScript` option to write your own file entirely.
|
||||
|
||||
|
||||
|
||||
@@ -785,8 +784,8 @@ The following environment properties are supported with the default script:
|
||||
|The name of the log file in the `LOG_FOLDER` (`<appname>.log` by default).
|
||||
|
||||
|`APP_NAME`
|
||||
|The name of the app. If the jar is run from a symlink, the script guesses the app name if
|
||||
it is not a symlink or you want to explicitly set the app name, this can be useful.
|
||||
|The name of the app. If the jar is run from a symlink, the script guesses the app name.
|
||||
If it is not a symlink or you want to explicitly set the app name, this can be useful.
|
||||
|
||||
|`RUN_ARGS`
|
||||
|The arguments to pass to the program (the Spring Boot app).
|
||||
@@ -818,10 +817,11 @@ http://www.freedesktop.org/software/systemd/man/systemd.service.html[service uni
|
||||
configuration man page] for more details.
|
||||
|
||||
[[deployment-script-customization-conf-file]]
|
||||
With the exception of `JARFILE` and `APP_NAME`, the above settings can be configured by
|
||||
using a `.conf` file. The file is expected to be next to the jar file and have the same
|
||||
name but suffixed with `.conf` rather than `.jar`. For example, a jar named
|
||||
`/var/myapp/myapp.jar` uses the configuration file named `/var/myapp/myapp.conf`.
|
||||
With the exception of `JARFILE` and `APP_NAME`, the settings listed in the preceding
|
||||
section can be configured by using a `.conf` file. The file is expected to be next to the
|
||||
jar file and have the same name but suffixed with `.conf` rather than `.jar`. For example,
|
||||
a jar named `/var/myapp/myapp.jar` uses the configuration file named
|
||||
`/var/myapp/myapp.conf`, as shown in the following example:
|
||||
|
||||
.myapp.conf
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
@@ -842,7 +842,7 @@ To learn about securing this file appropriately, see
|
||||
A Spring Boot application can be started as a Windows service by using
|
||||
https://github.com/kohsuke/winsw[`winsw`].
|
||||
|
||||
A sample (https://github.com/snicoll-scratches/spring-boot-daemon[maintained separately])
|
||||
A (https://github.com/snicoll-scratches/spring-boot-daemon[separately maintained sample])
|
||||
describes step-by-step how you can create a Windows service for your Spring Boot
|
||||
application.
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
|
||||
[partintro]
|
||||
--
|
||||
If you are getting started with Spring Boot, or "Spring" in general, start by reading
|
||||
If you are getting started with Spring Boot, or "`Spring`" in general, start by reading
|
||||
this section. It answers the basic "`what?`", "`how?`" and "`why?`" questions. It
|
||||
includes an introduction to Spring Boot, along with installation instructions. We then
|
||||
walk you through building your first Spring Boot application, discussing some core
|
||||
@@ -14,7 +14,7 @@ principles as we go.
|
||||
|
||||
[[getting-started-introducing-spring-boot]]
|
||||
== Introducing Spring Boot
|
||||
Spring Boot makes it easy to create stand-alone, production-grade Spring based
|
||||
Spring Boot makes it easy to create stand-alone, production-grade Spring-based
|
||||
Applications that you can run. We take an opinionated view of the Spring platform and
|
||||
third-party libraries, so that you can get started with minimum fuss. Most Spring Boot
|
||||
applications need very little Spring configuration.
|
||||
@@ -25,7 +25,7 @@ runs "`spring scripts`".
|
||||
|
||||
Our primary goals are:
|
||||
|
||||
* Provide a radically faster and widely accessible getting started experience for all
|
||||
* Provide a radically faster and widely accessible getting-started experience for all
|
||||
Spring development.
|
||||
* Be opinionated out of the box but get out of the way quickly as requirements start to
|
||||
diverge from the defaults.
|
||||
@@ -38,15 +38,15 @@ configuration).
|
||||
|
||||
[[getting-started-system-requirements]]
|
||||
== System Requirements
|
||||
Spring Boot {spring-boot-version} requires http://www.java.com[Java 8] and Spring
|
||||
Framework {spring-version} or above. Explicit build support is provided for Maven 3.2+
|
||||
and Gradle 4.
|
||||
Spring Boot {spring-boot-version} requires http://www.java.com[Java 8] and
|
||||
{spring-reference}[Spring Framework {spring-version}] or above. Explicit build support is
|
||||
provided for Maven 3.2+ and Gradle 4.
|
||||
|
||||
|
||||
|
||||
[[getting-started-system-requirements-servlet-containers]]
|
||||
=== Servlet Containers
|
||||
The following embedded servlet containers are supported out of the box:
|
||||
Spring Boot supports the following embedded servlet containers:
|
||||
|
||||
|===
|
||||
|Name |Servlet Version
|
||||
@@ -78,7 +78,7 @@ begin, you should check your current Java installation by using the following co
|
||||
|
||||
If you are new to Java development or if you want to experiment with Spring Boot, you
|
||||
might want to try the <<getting-started-installing-the-cli, Spring Boot CLI>> (Command
|
||||
Line Interface) first, otherwise, read on for "`classic`" installation instructions.
|
||||
Line Interface) first. Otherwise, read on for "`classic`" installation instructions.
|
||||
|
||||
|
||||
|
||||
@@ -102,8 +102,8 @@ Maven installed, you can follow the instructions at http://maven.apache.org.
|
||||
|
||||
TIP: On many operating systems, Maven can be installed with a package manager. If you use
|
||||
OSX Homebrew, try `brew install maven`. Ubuntu users can run
|
||||
`sudo apt-get install maven`. Windows users with Chocolatey can run `choco install maven`
|
||||
from an elevated (administrator) prompt.
|
||||
`sudo apt-get install maven`. Windows users with https://chocolatey.org/[Chocolatey] can
|
||||
run `choco install maven` from an elevated (administrator) prompt.
|
||||
|
||||
Spring Boot dependencies use the `org.springframework.boot` `groupId`. Typically, your
|
||||
Maven POM file inherits from the `spring-boot-starter-parent` project and declares
|
||||
@@ -298,7 +298,7 @@ commands:
|
||||
Spring Boot v{spring-boot-version}
|
||||
----
|
||||
|
||||
If you are developing features for the CLI and want easy access to the version you built,
|
||||
If you develop features for the CLI and want easy access to the version you built,
|
||||
use the following commands:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
@@ -372,8 +372,8 @@ http://en.wikipedia.org/wiki/Zsh[zsh] shells. You can `source` the script (also
|
||||
`spring`) in any shell or put it in your personal or system-wide bash completion
|
||||
initialization. On a Debian system, the system-wide scripts are in
|
||||
`/shell-completion/bash` and all scripts in that directory are executed when a new shell
|
||||
starts. For example, to run the script manually if you have installed using SDKMAN!, use
|
||||
the following commands:
|
||||
starts. For example, to run the script manually if you have installed by using SDKMAN!,
|
||||
use the following commands:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
@@ -415,7 +415,7 @@ Then run it from a shell, as follows:
|
||||
NOTE: The first run of your application is slow, as dependencies are downloaded.
|
||||
Subsequent runs are much quicker.
|
||||
|
||||
Open http://localhost:8080 in your favorite web browser. You should see the following
|
||||
Open `http://localhost:8080` in your favorite web browser. You should see the following
|
||||
output:
|
||||
|
||||
[indent=0]
|
||||
@@ -427,13 +427,13 @@ output:
|
||||
|
||||
[[getting-started-upgrading-from-an-earlier-version]]
|
||||
=== Upgrading from an Earlier Version of Spring Boot
|
||||
If you are upgrading from an earlier release of Spring Boot check the "`release notes`"
|
||||
hosted on the {github-wiki}[project wiki]. You'll find upgrade instructions along with a
|
||||
If you are upgrading from an earlier release of Spring Boot, check the "`release notes`"
|
||||
hosted on the {github-wiki}[project wiki]. You can find upgrade instructions along with a
|
||||
list of "`new and noteworthy`" features for each release.
|
||||
|
||||
To upgrade an existing CLI installation use the appropriate package manager command (for
|
||||
To upgrade an existing CLI installation, use the appropriate package manager command (for
|
||||
example, `brew upgrade`) or, if you manually installed the CLI, follow the
|
||||
<<getting-started-manual-cli-installation, standard instructions>> remembering to update
|
||||
<<getting-started-manual-cli-installation, standard instructions>>, remembering to update
|
||||
your `PATH` environment variable to remove any older references.
|
||||
|
||||
|
||||
@@ -477,7 +477,7 @@ valid versions of Java and Maven installed:
|
||||
----
|
||||
|
||||
NOTE: This sample needs to be created in its own folder. Subsequent instructions assume
|
||||
that you have created a suitable folder and that it is your "`current directory`".
|
||||
that you have created a suitable folder and that it is your current directory.
|
||||
|
||||
|
||||
|
||||
@@ -646,7 +646,7 @@ accordingly.
|
||||
****
|
||||
Auto-configuration is designed to work well with "`Starters`", but the two concepts are
|
||||
not directly tied. You are free to pick and choose jar dependencies outside of the
|
||||
starters and Spring Boot still does its best to auto-configure your application.
|
||||
starters. Spring Boot still does its best to auto-configure your application.
|
||||
****
|
||||
|
||||
|
||||
@@ -687,7 +687,7 @@ application. You should see output similar to the following:
|
||||
........ Started Example in 2.222 seconds (JVM running for 6.514)
|
||||
----
|
||||
|
||||
If you open a web browser to http://localhost:8080, you should see the following output:
|
||||
If you open a web browser to `http://localhost:8080`, you should see the following output:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
@@ -718,7 +718,7 @@ can also be problematic if the same filename is used (but with different content
|
||||
multiple jars.
|
||||
|
||||
Spring Boot takes a <<appendix-executable-jar-format.adoc#executable-jar, different
|
||||
approach>> and allows you to actually nest jars directly.
|
||||
approach>> and lets you actually nest jars directly.
|
||||
****
|
||||
|
||||
To create an executable jar, we need to add the `spring-boot-maven-plugin` to our
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -39,15 +39,24 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
|
||||
:spring-boot-maven-plugin-site: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/maven-plugin/
|
||||
:spring-boot-gradle-plugin: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/gradle-plugin/
|
||||
:spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/
|
||||
:spring-rest-docs: http://projects.spring.io/spring-restdocs/
|
||||
:spring-integration: http://projects.spring.io/spring-integration/
|
||||
:spring-session: https://projects.spring.io/spring-session/
|
||||
:spring-framework: http://projects.spring.io/spring-framework/
|
||||
:spring-security: http://projects.spring.io/spring-security/
|
||||
:spring-data-jpa: http://projects.spring.io/spring-data-jpa/
|
||||
:spring-security-reference: http://docs.spring.io/spring-security/site/docs/{spring-security-docs-version}/reference/htmlsingle
|
||||
:spring-security-oauth2-reference: http://projects.spring.io/spring-security-oauth/docs/oauth2.html
|
||||
:spring-webservices-reference: http://docs.spring.io/spring-ws/docs/{spring-webservices-docs-version}/reference/
|
||||
:spring-javadoc: http://docs.spring.io/spring/docs/{spring-docs-version}/javadoc-api/org/springframework
|
||||
:spring-framework-javadoc: https://docs.spring.io/spring-framework/docs/{spring-docs-version}/javadoc-api/org/springframework/
|
||||
:spring-amqp-javadoc: http://docs.spring.io/spring-amqp/docs/current/api/org/springframework/amqp
|
||||
:spring-batch-javadoc: http://docs.spring.io/spring-batch/apidocs/org/springframework/batch
|
||||
:spring-data-javadoc: http://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa
|
||||
:spring-data-commons-javadoc: http://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data
|
||||
:spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb
|
||||
:spring-data-mongo: http://projects.spring.io/spring-data-mongodb/
|
||||
:spring-data: http://projects.spring.io/spring-data/
|
||||
:spring-data-rest-javadoc: http://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest
|
||||
:gradle-userguide: http://www.gradle.org/docs/current/userguide
|
||||
:propdeps-plugin: https://github.com/spring-projects/gradle-plugins/tree/master/propdeps-plugin
|
||||
|
||||
@@ -19,7 +19,7 @@ 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
|
||||
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.
|
||||
****
|
||||
@@ -71,8 +71,8 @@ The following technology-agnostic endpoints are available:
|
||||
|Displays a complete list of all the Spring beans in your application.
|
||||
|
||||
|`conditions`
|
||||
|Showing the conditions that were evaluated on configuration and auto-configuration
|
||||
classes and the reasons why they did or did not match.
|
||||
|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`.
|
||||
@@ -92,6 +92,9 @@ The following technology-agnostic endpoints are available:
|
||||
|`loggers`
|
||||
|Shows and modifies the configuration of loggers in the application.
|
||||
|
||||
// TODO "and modifies"? Why would the endpoint modify the configuration? Do we mean "shows
|
||||
// any modifications"?
|
||||
|
||||
|`liquibase`
|
||||
|Shows any Liquibase database migrations that have been applied.
|
||||
|
||||
@@ -106,7 +109,7 @@ The following technology-agnostic endpoints are available:
|
||||
|
||||
|`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.
|
||||
store. Not available when using Spring Session's support for reactive web applications.
|
||||
|
||||
|`shutdown`
|
||||
|Lets the application be gracefully shutdown (not enabled by default).
|
||||
@@ -139,21 +142,20 @@ content.
|
||||
|===
|
||||
|
||||
To learn more about the Actuator's endpoints and their request and response formats,
|
||||
please refer to the separate API documentation that is available in the following formats:
|
||||
|
||||
* {spring-boot-actuator-api}/html[HTML]
|
||||
* {spring-boot-actuator-api}/pdf/spring-boot-actuator-web-api.pdf[PDF]
|
||||
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. Out of the box, Spring Boot will expose all enabled endpoints
|
||||
over JMX, but only the `health` and `info` endpoints over HTTP.
|
||||
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 use:
|
||||
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]
|
||||
@@ -162,7 +164,7 @@ for the technology. For example, to only expose the `health` over JMX you would
|
||||
----
|
||||
|
||||
The `*` character can be used to indicate all endpoints. For example, to expose everything
|
||||
over HTTP except the `env` endpoint you would use:
|
||||
over HTTP except the `env` endpoint, you would use the following properties:
|
||||
|
||||
.application.properties
|
||||
[source,properties,indent=0]
|
||||
@@ -171,10 +173,10 @@ over HTTP except the `env` endpoint you would use:
|
||||
management.endpoints.web.exclude=env
|
||||
----
|
||||
|
||||
NOTE: If your application is exposed publicly we strongly recommend that you also
|
||||
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
|
||||
TIP: If you want to implement your own strategy for when endpoints are exposed, you can
|
||||
register an `EndpointFilter` bean.
|
||||
|
||||
|
||||
@@ -182,11 +184,11 @@ 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. Spring Boot will not apply any security on your behalf, however, it does
|
||||
provide some convenient ``RequestMatcher``s that can be used in combination with Spring
|
||||
Security.
|
||||
sensitive URL. Spring Boot does not apply any security on your behalf. However, it does
|
||||
provide some convenient RequestMatcher` objects that can be used in combination with
|
||||
Spring Security.
|
||||
|
||||
A typical Spring Security configuration could look something like this:
|
||||
A typical Spring Security configuration might look something like the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@@ -204,9 +206,11 @@ A typical Spring Security configuration could look something like this:
|
||||
}
|
||||
----
|
||||
|
||||
The above uses `EndpointRequest.toAnyEndpoint()` to match a request to any endpoint, then
|
||||
ensure that all have the `ENDPOINT_ADMIN` role. Several other matcher methods are
|
||||
also available on `EndpointRequest` (see the API documentation for details).
|
||||
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
|
||||
@@ -223,9 +227,9 @@ endpoints can be accessed without requiring authentication. You can do so by cha
|
||||
[[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 it will cache responses.
|
||||
endpoint is `enabled` and the amount of time for which it caches responses.
|
||||
|
||||
For example, the following `application.properties` changes the time-to-live of the
|
||||
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]
|
||||
@@ -248,9 +252,9 @@ disable _all_ endpoints except for `info`:
|
||||
management.endpoint.info.enabled=true
|
||||
----
|
||||
|
||||
NOTE: Disabled endpoints are removed entirely from the `ApplicationContext`. If you only
|
||||
want to change the technologies over which an endpoint is exposed you can use the `expose`
|
||||
and `exclude` properties (see <<production-ready-endpoints-exposing-endpoints>>).
|
||||
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>>).
|
||||
|
||||
|
||||
|
||||
@@ -269,13 +273,13 @@ 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 using 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. You can also use
|
||||
`management.endpoints.web.base-path` if you want change the base path.
|
||||
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`.
|
||||
|
||||
Here's an example that remaps `/actuator/health` to `/healthcheck`:
|
||||
The following example remaps `/actuator/health` to `/healthcheck`:
|
||||
|
||||
.application.properties
|
||||
[source,properties,indent=0]
|
||||
@@ -289,8 +293,8 @@ Here's an example that remaps `/actuator/health` to `/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 allows you to specify in a
|
||||
flexible way what kind of cross domain requests are authorized. If you use Spring MVC or
|
||||
(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
|
||||
@@ -303,29 +307,32 @@ configuration permits `GET` and `POST` calls from the `example.com` domain:
|
||||
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.
|
||||
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
|
||||
`@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
|
||||
You can also write technology-specific endpoints by using `@JmxEndpoint` or
|
||||
`@WebEndpoint`. These endpoints are filtered to their respective technologies. For
|
||||
example, `@WebEndpoint` will be exposed only over HTTP and not over JMX.
|
||||
example, `@WebEndpoint` is exposed only over HTTP and not over JMX.
|
||||
|
||||
Finally, it's possible to write technology specific extensions using
|
||||
`@EndpointWebExtension` and `@EndpointJmxExtension`. These annotations allow you to
|
||||
provide technology specific operations to augment an existing endpoint.
|
||||
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
|
||||
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.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
@@ -335,7 +342,7 @@ You can use health information to check the status of your running application.
|
||||
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
|
||||
`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
|
||||
@@ -393,7 +400,7 @@ The following `HealthIndicators` are auto-configured by Spring Boot when appropr
|
||||
|Checks that a Solr server is up.
|
||||
|===
|
||||
|
||||
TIP: It is possible to disable them all using the `management.health.defaults.enabled`
|
||||
TIP: You can disable them all by setting the `management.health.defaults.enabled`
|
||||
property.
|
||||
|
||||
|
||||
@@ -440,7 +447,7 @@ 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
|
||||
to your application properties:
|
||||
property to your application properties:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
@@ -482,17 +489,17 @@ The following table shows the default status mappings for the built-in statuses:
|
||||
|
||||
[[reactive-health-indicators]]
|
||||
==== Reactive Health Indicators
|
||||
For reactive applications, such as those using Spring WebFlux, ReactiveHealthIndicators
|
||||
provide a non-blocking contract for getting application health. Similar to a traditional
|
||||
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 HealthIndicators that do not check
|
||||
against a reactive API are included and executed on the elastic scheduler.
|
||||
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:
|
||||
{sc-spring-boot-actuator}/health/ReactiveHealthIndicator.{sc-ext}[`ReactiveHealthIndicator`]
|
||||
interface. The following code shows a sample `ReactiveHealthIndicator` implementation:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@@ -525,7 +532,7 @@ appropriate:
|
||||
|Checks that a Redis server is up.
|
||||
|===
|
||||
|
||||
TIP: Those reactive indicators replace the regular ones if necessary. Also, any
|
||||
TIP: If necessary, reactive indicators replace the regular ones. Also, any
|
||||
`HealthIndicator` that is not handled explicitly is wrapped automatically.
|
||||
|
||||
|
||||
@@ -535,34 +542,35 @@ TIP: Those reactive indicators replace the regular ones if necessary. Also, any
|
||||
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 write your own.
|
||||
`InfoContributor` beans, and you can write your own.
|
||||
|
||||
[[production-ready-application-info-autoconfigure]]
|
||||
==== Auto-configured InfoContributors
|
||||
|
||||
The following `InfoContributors` are auto-configured by Spring Boot, when appropriate:
|
||||
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`]
|
||||
|Expose any key from the `Environment` under the `info` key.
|
||||
|Exposes 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.
|
||||
|Exposes 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.
|
||||
|Exposes 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`
|
||||
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.
|
||||
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]
|
||||
@@ -593,7 +601,7 @@ 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
|
||||
`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
|
||||
@@ -668,7 +676,7 @@ enabled endpoints to be exposed over HTTP. The default convention is to use the
|
||||
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.
|
||||
TIP: Actuator is supported natively with Spring MVC, Spring WebFlux, and Jersey.
|
||||
|
||||
|
||||
|
||||
@@ -685,11 +693,11 @@ management endpoint, as shown in the following example:
|
||||
----
|
||||
|
||||
The preceding `application.properties` example changes the endpoint from
|
||||
`/actuator/{id}` to `/manage/{id}` (e.g. `/manage/info`).
|
||||
`/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 using a different
|
||||
HTTP port>>, `management.endpoints.web.base-path` is relative 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`.
|
||||
@@ -699,7 +707,7 @@ HTTP port>>, `management.endpoints.web.base-path` is relative to
|
||||
[[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,
|
||||
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
|
||||
@@ -713,15 +721,16 @@ the following example:
|
||||
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:
|
||||
and you can disable management security, as follows:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
management.security.enabled=false
|
||||
----
|
||||
|
||||
(If you do not have Spring Security on the classpath, there is no need to explicitly
|
||||
disable the management security in this way. Doing so might even break the application.)
|
||||
CAUTION: If you do not have Spring Security on the classpath, there is no need to
|
||||
explicitly disable the management security in this way. Doing so might even break the
|
||||
application.
|
||||
|
||||
|
||||
|
||||
@@ -729,7 +738,7 @@ disable the management security in this way. Doing so might even break the appli
|
||||
=== 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 via HTTP while the main application uses HTTPS,
|
||||
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]
|
||||
@@ -766,7 +775,7 @@ the `management.server.address` property. Doing so can be useful if you want to
|
||||
only on an internal or ops-facing network or to listen only for connections from
|
||||
`localhost`.
|
||||
|
||||
NOTE: You can only listen on a different address if the port is different from the main
|
||||
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
|
||||
@@ -802,7 +811,7 @@ 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
|
||||
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
|
||||
@@ -854,9 +863,9 @@ 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`. Prefix the
|
||||
parameter with `management.jolokia.config.`, as shown in the following example:
|
||||
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.jolokia.config.`, as shown in the following example:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
@@ -900,8 +909,8 @@ one of:
|
||||
|
||||
[[production-ready-logger-configuration]]
|
||||
=== Configure a Logger
|
||||
In order to configure a given logger, you `POST` a partial entity to the resource's URI,
|
||||
as shown in the following example:
|
||||
To configure a given logger, `POST` a partial entity to the resource's URI, as shown in
|
||||
the following example:
|
||||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
@@ -910,7 +919,7 @@ as shown in the following example:
|
||||
}
|
||||
----
|
||||
|
||||
TIP: To "reset" the specific level of the logger (and use the default configuration
|
||||
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`.
|
||||
|
||||
|
||||
@@ -919,7 +928,7 @@ instead), you can pass a value of `null` as the `configuredLevel`.
|
||||
== Metrics
|
||||
Spring Boot Actuator provides dependency management and auto-configuration for
|
||||
https://micrometer.io[Micrometer], an application metrics facade that supports numerous
|
||||
monitoring systems:
|
||||
monitoring systems, including:
|
||||
|
||||
- https://github.com/Netflix/atlas[Atlas]
|
||||
- https://www.datadoghq.com[Datadog]
|
||||
@@ -928,6 +937,10 @@ monitoring systems:
|
||||
- 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
|
||||
@@ -951,10 +964,10 @@ customized by setting the `management.metrics.web.server.requests-metrics-name`
|
||||
==== 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.
|
||||
* 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`.
|
||||
|
||||
@@ -971,23 +984,23 @@ the name by setting the `management.metrics.web.server.requests-metrics-name` pr
|
||||
|
||||
|
||||
[[production-ready-metrics-web-flux-tags]]
|
||||
==== WebFlux Metric 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.
|
||||
* 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.
|
||||
* 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.
|
||||
@@ -1010,10 +1023,10 @@ customized by setting the `management.metrics.web.client.requests-metrics-name`
|
||||
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.
|
||||
* The request's method.
|
||||
* The request's URI (templated if possible).
|
||||
* The response's status.
|
||||
* The request URI's host.
|
||||
|
||||
|
||||
|
||||
@@ -1042,15 +1055,15 @@ is required. A `CacheMetricsRegistrar` bean is made available to make that proce
|
||||
|
||||
|
||||
[[production-ready-metrics-jdbc]]
|
||||
=== DataSource metrics
|
||||
Auto-configuration will enable the instrumentation of all available ``DataSource``s 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 customized by using the `management.metrics.jdbc.datasource-metric-name` property.
|
||||
=== 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.datasource-metric-name`
|
||||
property.
|
||||
|
||||
Metrics will also be tagged by the name of the `DataSource` computed based on the bean
|
||||
name.
|
||||
Metrics are also tagged by the name of the `DataSource` computed based on the bean name.
|
||||
|
||||
|
||||
|
||||
@@ -1115,13 +1128,15 @@ Auto-configuration enables binding of a number of Spring Integration-related met
|
||||
|
||||
[[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
|
||||
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`.
|
||||
|
||||
// TODO A sample showing how to customize published security events would be good.
|
||||
|
||||
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
|
||||
@@ -1211,18 +1226,20 @@ In the `spring-boot` module, you can find two classes to create files that are o
|
||||
useful for process monitoring:
|
||||
|
||||
* `ApplicationPidFileWriter` creates a file containing the application PID (by default,
|
||||
in the application directory with the file name, `application.pid`).
|
||||
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 the file name
|
||||
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 them in one of the ways
|
||||
described in the next section.
|
||||
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]]
|
||||
=== Extend 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:
|
||||
|
||||
|
||||
@@ -79,7 +79,7 @@ using, as follows:
|
||||
[[cli-run]]
|
||||
=== Running Applications with the CLI
|
||||
You can compile and run Groovy source code by using the `run` command. The Spring Boot CLI
|
||||
is completely self-contained, so you don't need any external Groovy installation.
|
||||
is completely self-contained, so you do not need any external Groovy installation.
|
||||
|
||||
The following example shows a "`hello world`" web application written in Groovy:
|
||||
|
||||
@@ -97,14 +97,14 @@ The following example shows a "`hello world`" web application written in Groovy:
|
||||
}
|
||||
----
|
||||
|
||||
To compile and run the application type the following command:
|
||||
To compile and run the application, type the following command:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ spring run hello.groovy
|
||||
----
|
||||
|
||||
To pass command-line arguments to the application, use a `--` to separate the commands
|
||||
To pass command-line arguments to the application, use `--` to separate the commands
|
||||
from the "`spring`" command arguments, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
@@ -186,10 +186,11 @@ in the Spring Boot CLI source code to understand exactly how customizations are
|
||||
==== Deduced "`grab`" Coordinates
|
||||
Spring Boot extends Groovy's standard `@Grab` support by letting you specify a dependency
|
||||
without a group or version (for example, `@Grab('freemarker')`). Doing so consults Spring
|
||||
Boot's default dependency metadata to deduce the artifact's group and version. Note that
|
||||
the default metadata is tied to the version of the CLI that you use – it changes only when
|
||||
you move to a new version of the CLI, putting you in control of when the versions of your
|
||||
dependencies may change. A table showing the dependencies and their versions that are
|
||||
Boot's default dependency metadata to deduce the artifact's group and version.
|
||||
|
||||
NOTE: The default metadata is tied to the version of the CLI that you use. it changes only
|
||||
when you move to a new version of the CLI, putting you in control of when the versions of
|
||||
your dependencies may change. A table showing the dependencies and their versions that are
|
||||
included in the default metadata can be found in the <<appendix-dependency-versions,
|
||||
appendix>>.
|
||||
|
||||
@@ -242,8 +243,8 @@ as shown in the following example:
|
||||
"com.example.another-bom:1.0.0"])
|
||||
----
|
||||
|
||||
The preceding example indicates that dependency management in `another-bom` overrides the
|
||||
dependency management in `custom-bom`.
|
||||
The preceding example indicates that the dependency management in `another-bom` overrides
|
||||
the dependency management in `custom-bom`.
|
||||
|
||||
You can use `@DependencyManagementBom` anywhere that you can use `@Grab`. However, to
|
||||
ensure consistent ordering of the dependency management, you can use
|
||||
@@ -282,10 +283,10 @@ jar file, as shown in the following example:
|
||||
|
||||
The resulting jar contains the classes produced by compiling the application and all of
|
||||
the application's dependencies so that it can then be run by using `java -jar`. The jar
|
||||
file also contains entries from the application's classpath. You can add explicit paths to
|
||||
the jar by using `--include` and `--exclude`. Both are comma-separated, and both accept
|
||||
prefixes, in the form of "`+`" and "`-`", to signify that they should be removed from the
|
||||
defaults. The default includes are as follows:
|
||||
file also contains entries from the application's classpath. You can add and remove
|
||||
explicit paths to the jar by using `--include` and `--exclude`. Both are comma-separated,
|
||||
and both accept prefixes, in the form of "`+`" and "`-`", to signify that they should be
|
||||
removed from the defaults. The default includes are as follows:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
@@ -399,8 +400,8 @@ In addition to installing the artifacts identified by the coordinates you supply
|
||||
the artifacts' dependencies are also installed.
|
||||
|
||||
To uninstall a dependency, use the `uninstall` command. As with the `install` command, it
|
||||
takes one or more sets of artifact coordinates in the format `group:artifact:version`, as
|
||||
shown in the following example:
|
||||
takes one or more sets of artifact coordinates in the format of `group:artifact:version`,
|
||||
as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@@ -462,14 +463,14 @@ The Spring Boot CLI uses Aether, Maven's dependency resolution engine, to resolv
|
||||
dependencies. The CLI makes use of the Maven configuration found in `~/.m2/settings.xml`
|
||||
to configure Aether. The following configuration settings are honored by the CLI:
|
||||
|
||||
* Offline
|
||||
* Mirrors
|
||||
* Servers
|
||||
* Proxies
|
||||
* Profiles
|
||||
** Activation
|
||||
** Repositories
|
||||
* Active profiles
|
||||
* Offline
|
||||
* Mirrors
|
||||
* Servers
|
||||
* Proxies
|
||||
* Profiles
|
||||
** Activation
|
||||
** Repositories
|
||||
* Active profiles
|
||||
|
||||
See https://maven.apache.org/settings.html[Maven's settings documentation] for further
|
||||
information.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -30,7 +30,7 @@ systems (Ant, for example), but they are not particularly well supported.
|
||||
=== Dependency Management
|
||||
Each release of Spring Boot provides a curated list of dependencies that it supports. In
|
||||
practice, you do not need to provide a version for any of these dependencies in your
|
||||
build configuration, as Spring Boot is managing that for you. When you upgrade Spring
|
||||
build configuration, as Spring Boot manages that for you. When you upgrade Spring
|
||||
Boot itself, these dependencies are upgraded as well in a consistent way.
|
||||
|
||||
NOTE: You can still specify a version and override Spring Boot's recommendations if you
|
||||
@@ -76,8 +76,8 @@ style placeholders (`${...}`), the Maven filtering is changed to use `@..@` plac
|
||||
|
||||
[[using-boot-maven-parent-pom]]
|
||||
==== Inheriting the Starter Parent
|
||||
To configure your project to inherit from the `spring-boot-starter-parent` set the
|
||||
`parent`, as follows:
|
||||
To configure your project to inherit from the `spring-boot-starter-parent`, set the
|
||||
`parent` as follows:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
@@ -273,7 +273,7 @@ _<<howto.adoc#howto-build-an-executable-archive-with-ant>>_ "`How-to`" .
|
||||
[[using-boot-starter]]
|
||||
=== Starters
|
||||
Starters are a set of convenient dependency descriptors that you can include in your
|
||||
application. You get a one-stop shop for all the Spring and related technology that you
|
||||
application. You get a one-stop shop for all the Spring and related technologies that you
|
||||
need without having to hunt through sample code and copy-paste loads of dependency
|
||||
descriptors. For example, if you want to get started using Spring and JPA for database
|
||||
access, include the `spring-boot-starter-data-jpa` dependency in your project.
|
||||
@@ -285,9 +285,9 @@ running quickly and with a consistent, supported set of managed transitive depen
|
||||
****
|
||||
All **official** starters follow a similar naming pattern; `+spring-boot-starter-*+`,
|
||||
where `+*+` is a particular type of application. This naming structure is intended to
|
||||
help when you need to find a starter. The Maven integration in many IDEs allow you to
|
||||
help when you need to find a starter. The Maven integration in many IDEs lets you
|
||||
search dependencies by name. For example, with the appropriate Eclipse or STS plugin
|
||||
installed, you can simply hit `ctrl-space` in the POM editor and type
|
||||
installed, you can press `ctrl-space` in the POM editor and type
|
||||
"`spring-boot-starter`" for a complete list.
|
||||
|
||||
As explained in the "`<<spring-boot-features#boot-features-custom-starter,Creating Your
|
||||
@@ -636,6 +636,7 @@ following example:
|
||||
=== Using the Maven Plugin
|
||||
The Spring Boot Maven plugin includes a `run` goal that can be used to quickly compile
|
||||
and run your application. Applications run in an exploded form, as they do in your IDE.
|
||||
The following example shows a typical Maven command to run a Spring Boot application:
|
||||
|
||||
[indent=0,subs="attributes"]
|
||||
----
|
||||
@@ -682,7 +683,7 @@ http://zeroturnaround.com/software/jrebel/[JRebel] can be used.
|
||||
|
||||
The
|
||||
`spring-boot-devtools` module also includes support for quick application restarts.
|
||||
See the <<using-boot-devtools>> section below and the
|
||||
See the <<using-boot-devtools>> section later in this chapter and the
|
||||
<<howto.adoc#howto-hotswapping, Hot swapping "`How-to`">> for details.
|
||||
|
||||
|
||||
@@ -716,10 +717,10 @@ listings for Maven and Gradle:
|
||||
----
|
||||
|
||||
NOTE: Developer tools are automatically disabled when running a fully packaged
|
||||
application. If your application is launched using `java -jar` or if it is started from a
|
||||
application. If your application is launched from `java -jar` or if it is started from a
|
||||
special classloader, then it is considered a "`production application`". Flagging the
|
||||
dependency as optional is a best practice that prevents devtools from being transitively
|
||||
applied to other modules using your project. Gradle does not support `optional`
|
||||
applied to other modules that use your project. Gradle does not support `optional`
|
||||
dependencies out-of-the-box, so you may want to have a look at the
|
||||
{propdeps-plugin}[`propdeps-plugin`].
|
||||
|
||||
@@ -852,7 +853,7 @@ You may want your application to be restarted or reloaded when you make changes
|
||||
that are not on the classpath. To do so, use the
|
||||
`spring.devtools.restart.additional-paths` property to configure additional paths to
|
||||
watch for changes. You can use the `spring.devtools.restart.exclude` property
|
||||
<<using-boot-devtools-restart-exclude, described above>> to control whether changes
|
||||
<<using-boot-devtools-restart-exclude, described earlier>> to control whether changes
|
||||
beneath the additional paths trigger a full restart or a
|
||||
<<using-boot-devtools-livereload, live reload>>.
|
||||
|
||||
@@ -865,7 +866,7 @@ If you do not want to use the restart feature, you can disable it by using the
|
||||
your `application.properties` (doing so still initializes the restart classloader, but it
|
||||
does not watch for file changes).
|
||||
|
||||
If you need to _completely_ disable restart support (for example, because it doesn't work
|
||||
If you need to _completely_ disable restart support (for example, because it does not work
|
||||
with a specific library), you need to set the `spring.devtools.restart.enabled` `System`
|
||||
property to `false` before calling `SpringApplication.run(...)`, as shown in the
|
||||
following example:
|
||||
@@ -885,7 +886,7 @@ following example:
|
||||
If you work with an IDE that continuously compiles changed files, you might prefer to
|
||||
trigger restarts only at specific times. To do so, you can use a "`trigger file`", which
|
||||
is a special file that must be modified when you want to actually trigger a restart
|
||||
check. Changing the file only triggers the check and the restart will only occur if
|
||||
check. Changing the file only triggers the check and the restart only occurs if
|
||||
Devtools has detected it has to do something. The trigger file can be updated manually or
|
||||
with an IDE plugin.
|
||||
|
||||
@@ -900,9 +901,9 @@ in the same way.
|
||||
|
||||
[[using-boot-devtools-customizing-classload]]
|
||||
==== Customizing the Restart Classloader
|
||||
As described in the <<using-spring-boot-restart-vs-reload>> section above, restart
|
||||
As described earlier in the <<using-spring-boot-restart-vs-reload>> section, restart
|
||||
functionality is implemented by using two classloaders. For most applications, this
|
||||
approach works well. However, sometimes it can cause classloading issues.
|
||||
approach works well. However, it can sometimes cause classloading issues.
|
||||
|
||||
By default, any open project in your IDE is loaded with the "`restart`" classloader, and
|
||||
any regular `.jar` file is loaded with the "`base`" classloader. If you work on a
|
||||
@@ -924,7 +925,7 @@ pattern that is applied to the classpath, as shown in the following example:
|
||||
NOTE: All property keys must be unique. As long as a property starts with
|
||||
`restart.include.` or `restart.exclude.` it is considered.
|
||||
|
||||
TIP: All `META-INF/spring-devtools.properties` from the classpath will be loaded. You can
|
||||
TIP: All `META-INF/spring-devtools.properties` from the classpath are loaded. You can
|
||||
package files inside your project, or in the libraries that the project consumes.
|
||||
|
||||
|
||||
@@ -977,7 +978,7 @@ property:
|
||||
|
||||
[[using-boot-devtools-remote]]
|
||||
=== Remote Applications
|
||||
The Spring Boot developer tools are not just limited to local development. You can also
|
||||
The Spring Boot developer tools are not limited to local development. You can also
|
||||
use several features when running applications remotely. Remote support is opt-in. To
|
||||
enable it, you need to make sure that `devtools` is included in the repackaged archive,
|
||||
as shown in the following listing:
|
||||
|
||||
Reference in New Issue
Block a user