root
/
spring-boot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

[bs-108] Feature documentation: just a list and brief description

Browse Source 
[#49502657]
pull/1/merge
Dave Syer 12 years ago
parent 7800ebbdc7
commit bff41d51ff
1 changed files with 311 additions and 0 deletions
Show Stats Download Patch File Download Diff File

311
spring-bootstrap-actuator/docs/Features.md
Unescape Escape View File

@ -0,0 +1,311 @@
# Spring Bootstrap Actuator Feature Guide
Here are some (most, hopefully all) the features of Spring Bootstrap
Actuator with some commentary to help you start using them. We
recommend you first build a project with the Actuator (e.g. the
getting started project from the main README), and then try each
feature in turn there.
TODO: some of these are features of Spring Bootstrap (or
`SpringApplication`) not the Actuator.
TODO: group things together and break them out into separate files.
## Commandline Arguments
Commandline arguments are passed on to any `CommandLineRunner` beans
found in the application. Option arguments (starting with `--`,
e.g. `--server.port=9000`) are converted to a `PropertySource` and
added to the Spring `Environment` with first priority (they always
take precedence and override values from other sources). Properties
in the `Environment` (including System properties and OS environment
variables) can always be injected into Spring components using
`@Value` with placeholders, e.g.
@Component
public class MyService {
@Value("${app.message:Hello World}")
private String message;
...
}
The default value comes after the first colon (":").
## Externalized Configuration
In addition to command line option arguments, Spring Bootstrap will
pick up a file called `application.properties` in the root of your
classpath (if there is one) and add those properties to the Spring
`Environment`. The search path for `application.properties` is
actually, 1) root or classpath, 2) current directory, 3) `/config`
package in classpath, 4) `/config` subdir of current directory. The
list is ordered by decreasing precedence (so properties can be
overridden by others with the same name defined in later locations).
The values in `application.properties` are filtered through the
existing `Environment` when they are used so you can refer back to
previously defined values (e.g. from System properties), e.g.
app.name: MyApp
app.description: ${app.name} is a Cool New App
Spring Bootstrap also binds the properties to any bean in your
application context whose type is `@ConfigurationProperties`. The
Actuator provides some of those beans out of the box, so you can
easily customize server and management properties (ports etc.),
endpoint locations and logging. See below for more detail, or inspect
the `*Properties` types in the Actuator jar.
## Setting the Default Spring Profile
Spring Profiles are a way to segregate parts of the application
configuration and make it only available in certain environments. Any
`@Component` that is marked with `@Profile` will only be loaded in the
profile specified by the latter annotation.
Spring Bootstrap takes it a stage further. If you include in your
`application.properties` a value for a property named
`spring.active.profiles` then those profiles will be active by
default. E.g.
spring.active.profiles: dev,hsqldb
## Profile-dependent configuration
Spring Bootstrap loads additional properties files if there are active
profiles using a naming convention `application-{profile}.properties`.
Property values from those files override trhe default ones.
## Custom Typesafe Externalized Configuration
If you want a strongly typed bean (or beans) to govern and validate
the configuration of your application beyond the built in properties,
all you need to do is create a `@ConfigurationProperties` class, e.g.
@ConfigurationProperties(name="my")
public class MyProperties {
}
and declare one either explicitly (with `@Bean`) or implicitly by
adding
@EnableConfigurationProperties(MyProperties.class)
to one of your `@Configuration` (or `@Component`) classes. Then you can
@Autowired
private MyProperties configuration = new MyProperties();
in any of your component classes to grab that configuration and use it.
Spring Bootstrap uses some relaxed rules for binding `Environment`
properties to `@ConfigurationProperties` beans, so there doesn't need
to be an exact match between the `Environment` property name and the
bean property name. Common examples where this is useful include
underscore separated (e.g. `context_path` binds to `contextPath`), and
capitalized (e.g. `PORT` binds to `port`) environment properties.
Spring will attempt to coerce the external application properties to
the right type when it binds to the `@ConfigurationProperties` beans.
If you need custom type conversion you can provide a
`ConversionService` bean (with bean id `conversionService`) or custom
property editors (via a `CustomEditorConfigurer` bean).
Spring will also validate the external configuration, by default using
JSR-303 if it is on the classpath. So you can add annotations from
that specification (or its implementations) to your custom properties,
e.g.
@ConfigurationProperties(name="my")
public class MyProperties {
@NotNull
private String name;
// .. getters and setters
}
You can also add a custom Spring `Validator` by creating a bean
definition called `configurationPropertiesValidator`.
## Using Project Lombok
You can safely use [Project Lombok](http://projectlombok.org) to
generate getters and setters for your `@ConfigurationProperties`.
Refer to the documentation on the Lombok for how to enable it in your
compiler or IDE.
## Using YAML instead of Properties
YAML is a superset of JSON, and as such is a very convenient format
for specifying hierarchical configuration data, such as that supported
by Spring Bootstrap Actuator. If you prefer to use
[YAML](http://yaml.org) instead of Properties files you just need to
include a file called `application.yml` in the root of your classpath
You can if you like add profile specific YAML files
(`application-${profile}.yml`), but a nicer alternative is to use YAML
documents inside `application.yml`, with profile-specific documents
containing a `spring.profiles` key. For example
server:
port: 8080
management:
port: 8080
address: 0.0.0.0
---
spring:
profiles: prod
management:
port: 8081
address: 10.2.68.12
## Customizing the location of the External Configuration
If you don't like `application.properties` or `application.yml` as the
configuration file location you can switch to another location by
specifying the `spring.config.name` (default `application`) or the
`spring.config.location` as environment properties, e.g. if launching
a jar which wraps `SpringApplication`:
$ java -jar myproject.jar --spring.config.name=myproject
## Server Configuration
The `ServerProperties` are bound to application properties, and
can be used to specify
* The port that the application listens on for the its endpoints
(`server.port` defaults to 8080)
* The address that the application endpoints are available on
(`server.address` defaults to all local addresses, making it available to connections
from all clients).
* The context root of the application endpoints (`server.context_path`
defaults to "/")
## Tomcat Container Configuration
If you want to use Tomcat as an embedded container include at least
`org.apache.tomcat.embed:tomcat-embed-core` and one of the
`org.apache.tomcat.embed:tomcat-embed-logging-*` libraries (depending
on the logging system you are using). Then, in addition to the
generic `ServerProperties`, you can also bind `server.tomcat.*`
properties in the application properties (see
`ServerProperties.Tomcat`).
* To enable the Tomcat access log valve (very common in production environments)
More fine-grained control of the Tomcat container is available if you
need it. Instead of letting Spring Bootstrap create the container for
you, just create a bean of type
`TomcatEmbeddedServletContainerFactory` and override one of its
methods, or inject some customizations, e.g.
@Configuration
public class MyContainerConfiguration {
@Bean
public TomcatEmbeddedServletContainerFactory tomcatEmbeddedContainerFactory() {
TomcatEmbeddedServletContainerFactory factory = new TomcatEmbeddedServletContainerFactory();
factory.setConnector(new Connector("AJP/1.3"));
}
}
(the default connector uses the `Http11NioProtocol` so the example if
overriding that behaviour).
## Customizing Management Endpoints
The `ManagementProperties` are bound to application properties, and
can be used to specify
* The port that the application listens on for the management
endpoints (defaults to 8080)
* The address that the management endpoints are available on (if the
port is different to the main server port). Use this to listen only
on an internal or ops-facing network, for instance, or to only
listen for connections from localhost (by specifying "127.0.0.1")
* The context root of the management endpoints (TODO: does this work?)
The `EndpointsProperties` are also bound, and you can use those to
change the paths of the management endpoints, e.g.
endpoints.error.path: /errors/generic
## Error Handling
The Actuator provides an `/error` endpoint by default that handles all
errors in a sensible way. If you want more specific error pages for
some conditions, the embedded servlet containers support a uniform
Java DSL for customizing the error handling. To do this you have to
have picked a container implementation (by including either Tomcat or
Jetty on the classpath), but then the API is the same. TODO: finish
this.
## Customizing Logging
Spring Bootstrap uses SLF4J for logging, but leaves the implementation
open. The Starter projects and the Actuator use JDK native logging by
default, purely because it is always available. A default
configuration file is provided for JDK logging, and also for log4j and
logback. In each case there is console output and file output
(rotating, 10MB file size).
The various logging systems can be activated by including the right
libraries on the classpath, and further customized by providing a
native configuration file in the root of the classpath, or in a
location specified by the Spring `Environment` property
`logging.config`.
|Logger|Activation |Customization |
|---|---|---|
|JDK |slf4j-jdk14 | logging.properties |
|Logback |logback | logback.xml |
|Log4j |slfj4-log4j12, log4j | log4j.properties or log4j.xml |
To help with the customization some other properties are transferred
from the Spring `Environment` to System properties:
|Environment|System Property |Comments |
|---|---|---|
|logging.file |LOG_FILE | Used in default log configuration if defined |
|logging.path |LOG_PATH | Used in default log configuration if defined |
|PID |PID | The current process ID is discovered if possible and not already provided |
All the logging systems supported can consult System properties when
parsing their configuration files. See the defailt configurations in
`spring-bootstrap.jar` for examples.
## Application Context Initializers
To add additional application context initializers to the Bootstrap
startup process, add a comma-delimited list of class names to the
`Environment` property `context.initializer.classes` (can be specified
via `application.properties`).
## Security - User Details
## Security - HTTPS
## XML Content
## Audit Events
## Metrics Customization
Metrics come out on the `/varz` endpoint. You can add additional
metrics by injecting a `MetricsRepository` into your application
components and adding metrics whenever you need to. To customize the
`MetricsRepository` itself, just add a bean definition of that type to
the application context (only in memory is supported out of the box
for now).
## Customizing the Health Indicator
The application always tells you if it's healthy via the `/healthz`
endpoint. By default it just responds to a GET witha 200 status and a
plain text body containing "ok". If you want to add more detailed
information (e.g. a description of the current state of the
application), just add a bean of type `HealthIndicator` to your
application context, and it will take the place of the default one.
Write Preview
Loading…
Cancel
Save