To get the version show up in the admin's application list you can use the `build-info` goal from the `spring-boot-maven-plugin`, which generates the `META-INF/build-info.properties`. See also the http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#howto-build-info[Spring Boot Reference Guide].
[source,xml]
.pom.xml
----
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>build-info</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
----
[[jmx-bean-management]]
=== JMX-bean management ===
To interact with JMX-beans in the admin UI you have to include https://jolokia.org/[Jolokia] in your application. In case you are using the `spring-boot-admin-starter-client` it will be pulled in for you, if not add Jolokia to your dependencies:
[source,xml]
.pom.xml
----
<dependency>
<groupId>org.jolokia</groupId>
<artifactId>jolokia-core</artifactId>
</dependency>
----
[[loglevel-management]]
=== Loglevel managment ===
Currently the loglevel management is only available for http://logback.qos.ch/[Logback]. It is accessed via JMX so <<jmx-bean-management, include Jolokia>> in your application. In addition you have configure Logback's `JMXConfigurator`:
NOTE: In case you are deploying multiple applications to the same JVM and multiple Logback-JMX-beans are present, the UI will select the JMXConfigurator with the context-name equals to your applications name. In this case you need to set the `contextName` in your logback-configuration.
[[spring-boot-admin-client]]
=== Spring Boot Admin Client ===
The Spring Boot Admin Client registers the application at the admin server. This is done by periodically doing a http post-request to the admin server providing informations about the application. It also adds Jolokia to your dependencies, so that JMX-beans are accessible via http, this is needed if you want to manage loglevels or JMX-beans via the admin UI.
.Spring Boot Admin Client configuration options
|===
| Property name |Description |Default value
| spring.boot.admin.client.enabled
| Enables the Spring Boot Admin Client.
| `true`
| spring.boot.admin.url
| Comma separated ordered list of URLs of the Spring Boot Admin server to register at. This triggers the AutoConfiguration. *Mandatory*.
|
| spring.boot.admin.api-path
| Http-path of registration endpoint at your admin server.
| `"api/applications"`
| spring.boot.admin.username
spring.boot.admin.password
| Username and password for http-basic authentication. If set the registration uses http-basic-authentication when registering at the admin server.
|
| spring.boot.admin.period
| Interval for repeating the registration (in ms).
| `10.000`
| spring.boot.admin.auto-registration
| If set to true the periodic task to register the application is automatically scheduled after the application is ready.
| `true`
| spring.boot.admin.auto-deregistration
| Switch to enable auto-deregistration at Spring Boot Admin server when context is closed.
| `false`
| spring.boot.admin.register-once
| If set to true the client will only register against one admin server (in order defined by `spring.boot.admin.url`); if that admin server goes down, will automatically register against the next admin server. If false, will register against all admin servers.
| `true`
| spring.boot.admin.client.health-url
| Client-health-url to register with. Can be overridden in case the reachable URL is different (e.g. Docker). Must be unique in registry.
| Guessed based on management-url and `endpoints.health.id`.
| spring.boot.admin.client.management-url
| Client-management-url to register with. Can be overridden in case the reachable url is different (e.g. Docker).
| Guessed based on service-url, `server.servlet-path`, `management.port` and `management.context-path`.
| spring.boot.admin.client.service-url
| Client-service-url to register with. Can be overridden in case the reachable url is different (e.g. Docker).
| Guessed based on hostname, `server.port` and `server.context-path`.
| spring.boot.admin.client.name
| Name to register with.
| `${spring.application.name}` if set, `"spring-boot-application"` otherwise.
| spring.boot.admin.client.prefer-ip
| Use the ip-address rather then the hostname in the guessed urls. If `server.address` / `management.address` is set, it get used. Otherwise the IP address returned from `InetAddress.getLocalHost()` gets used.
Can I include spring-boot-admin into my business application?::
*tl;dr* You can, but you shouldn't. +
You can set `spring.boot.admin.context-path` to alter the path where the UI and REST-API is served, but depending on the complexity of your application you might get in trouble. On the other hand in my opinion it makes no sense for an application to monitor itself. In case your application goes down your monitoring tool also does.
How do I customize the UI?::
You can only customize the UI by copying and modifying the source of `spring-boot-admin-ui` and adding your own module to your classpath.
NOTE: If you want to setup the Spring Boot Admin Server via war-deployment in a servlet-container, please have a look at the https://github.com/codecentric/spring-boot-admin/blob/master/spring-boot-admin-samples/spring-boot-admin-sample-war/[spring-boot-admin-sample-war].
See also the https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample/[spring-boot-admin-sample] project.
[[register-client-applications]]
=== Register client applications ===
To register your application at the admin server (next referred as "clients").
Either you can include the `spring-boot-admin` client or use http://projects.spring.io/spring-cloud/spring-cloud.html[Spring Cloud Discovery] (e.g. Eureka)
[[register-clients-via-spring-boot-admin]]
==== spring-boot-admin-starter-client ====
Each application that want to register itself to the admin has to include the Spring Boot Admin Client.
. Add spring-boot-admin-starter-client to your dependencies:
If you already using Spring Cloud Discovery for your applications you don't have to add the Spring Boot Admin Client to your applications. Just make the Spring Boot Admin Server a DiscoveryClient, the rest is done by our AutoConfiguration.
The following steps are for using Eureka, but other Spring Cloud Discovery implementations are supported as well. There are examples using https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-consul/[Consul] and https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-zookeeper/[Zookeeper].
Also have a look at the http://projects.spring.io/spring-cloud/spring-cloud.html[Spring Cloud documentation].
. Add spring-cloud-starter-eureka to you dependencies:
See also https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-eureka/[spring-boot-admin-sample-eureka].
NOTE: You can include the Spring Boot Admin to your Eureka server. Add the dependencies, add `@EnableAdminServer` to your configuration and set `spring.boot.admin.context-path` to something different than `"/"` so that the Spring Boot Admin Server UI won't clash with Eureka's one.
Spring Boot Admin Server supports cluster replication via Hazelcast. It is automatically enabled when a `HazelcastConfig`- or `HazelcastInstance`-Bean is present. You can also configure the Hazelcast instance to be persistent, to keep the status over restarts.
Also have a look at the http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#boot-features-hazelcast/[Spring Boot support for Hazelcast].
The Spring Boot Admin Server is capable of using Spring Clouds `DiscoveryClient` to discover applications. The advantage is that the clients don't have to include the `spring-boot-admin-starter-client`. You just have to add a DiscoveryClient to your admin server - everything else is done by AutoConfiguration.
The setup is explained <<discover-clients-via-spring-cloud-discovery,above>>.
==== ServiceInstanceConverter ====
The informations from the discovered services are converted by the `ServiceInstanceConverter`. Spring Boot Admin ships with a default and Eureka converter implementation. The correct one is selected by AutoConfiguration. You can use your own conversion by implementing the interface and adding the bean to your application context.
TIP: If you want to customize the default conversion of services you can either add `health.path`, `management.port` and/or `mangament.context-path` entries to the services metadata. This allows you to set the health or management path per application. In case you want to configure this for all of your discovered services, you can use the `spring.boot.admin.discovery.converter.*` properties for your Spring Boot Admin Server configuration. The services' metadata takes precedence over the server configuration. For the health-url the `EurekaServiceInstanceConverter` uses the healthCheckUrl registered in Eureka, which can be set for your client via `eureka.instance.healthCheckUrl`.
.Discovery configuration options
|===
| Property name |Description |Default value
| spring.boot.admin.discovery.enabled
| Enables the DiscoveryClient-support for the admin server.
The `RemindingNotifier` sends reminders for down/offline applications, it delegates the sending of notifications to another notifier.
By default a reminder is triggered when a registered application changes to `DOWN` or `OFFLINE`. You can alter this behaviour via `setReminderStatuses()`. The reminder ends when either the status changes to a non-triggering status or the regarding application gets deregistered.
By default the reminders are sent every 10 minutes, to change this use `setReminderPeriod()`. The `RemindingNotifier` itself doesn't start the background thread to send the reminders, you need to take care of this as shown in the given example below;
.How to configure reminders
[source,java]
----
@Configuration
@EnableScheduling
public class NotifierConfiguration {
@Autowired
private Notifier notifier;
@Bean
@Primary
public RemindingNotifier remindingNotifier() {
RemindingNotifier remindingNotifier = new RemindingNotifier(notifier);
<2> Schedules sending of due reminders every 60 seconds.
[[filtering-notifications]]
==== Filtering notifications ====
The `FilteringNotifier` allows you to filter certain notification based on rules you can add/remove at runtime. It delegates the sending of notifications to another notifier.
If you add a `FilteringNotifier` to your `ApplicationContext` a RESTful interface on `api/notifications/filter` gets available. When this happens the ui shows options to manage the filters.
This notifier is useful if you don't want recieve notifications when deploying your applications. Before stopping the application you can add an (expiring) filter either via a `POST` request or the ui.
.How to configure filtering
[source,java]
----
@Configuration
@EnableScheduling
public class NotifierConfiguration {
@Autowired
private Notifier delegate;
@Bean
public FilteringNotifier filteringNotifier() { // <1>
return new FilteringNotifier(delegate);
}
@Bean
@Primary
public RemindingNotifier remindingNotifier() { // <2>
RemindingNotifier notifier = new RemindingNotifier(filteringNotifier());
<1> Add the `FilteringNotifier` bean using a delegate (e.g. `MailNotifier` when configured)
<2> Add the `RemindingNotifier` as primary bean using the `FilteringNotifier` as delegate.
TIP: This examples combines the reminding and filtering notifiers. This allows you to get notifications after the deployed applications hasn't restarted in a certain amount of time (until the filter expires).
[[mail-notifications]]
==== Mail notifications ====
Configure a `JavaMailSender` using `spring-boot-starter-mail` and set a recipient.
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`
| spring.boot.admin.notify.mail.to
| Comma-delimited list of mail recipients
| `"root@localhost"`
| spring.boot.admin.notify.mail.cc
| Comma-delimited list of carbon-copy recipients
|
| spring.boot.admin.notify.mail.from
| Mail sender
|
| spring.boot.admin.notify.mail.subject
| Mail subject. SpEL-expressions are supported
| `+++"#{application.name} (#{application.id}) is #{to.status}"+++`
| spring.boot.admin.notify.mail.text
| Mail body. SpEL-expressions are supported
| `+++"#{application.name} (#{application.id})\nstatus changed from #{from.status} to #{to.status}\n\n#{application.healthUrl}"+++`
|===
[[pagerduty-notifications]]
==== Pagerduty notifications ====
To enable pagerduty notifications you just have to add a generic service to your pagerduty-account and set `spring.boot.admin.notify.pagerduty.service-key` to the service-key you received.
