= Spring Boot Admin Reference Guide =
Johannes Edmeier <https://twitter.com/joshiste[@joshiste]>
:revnumber: {project-version} 
:revdate: {commit-time}
:toc: right
:doctype: book
:sectanchors:
:sectlinks:
:sectnums:
:icons: font
:hide-uri-scheme:
:last-update-label!:

== What is Spring Boot Admin? ==

Spring Boot Admin is a simple application to manage and monitor your http://projects.spring.io/spring-boot/[Spring Boot Applications].
The applications register with our Spring Boot Admin Client (via http) or are discovered using Spring Cloud (e.g. Eureka).
The UI is just an Angular.js application on top of the Spring Boot Actuator endpoints. In case you want to use the more advanced features (e.g. jmx-, loglevel-management), Jolokia must be included in the client application.

[[getting-started]]
== Getting started ==

[[set-up-admin-server]]
=== Set up admin server ===

First you need to setup your server. To do this just setup a simple boot project (using http://start.spring.io for example).

. Add Spring Boot Admin Server and the UI to your dependencies:
+
[source,xml,subs="verbatim,attributes"]
.pom.xml
----
<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-server</artifactId>
    <version>{project-version}</version>
</dependency>
<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-server-ui</artifactId>
    <version>{project-version}</version>
</dependency>
----

. Pull in the Boot Admin Server configuration via adding `@EnableAdminServer` to your configuration:
+
[source,java]
----
@Configuration
@EnableAutoConfiguration
@EnableAdminServer
public class SpringBootAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootAdminApplication.class, args);
    }
}
----

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]]
==== Register clients via spring-boot-admin-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:
+
[source,xml,subs="verbatim,attributes"]
.pom.xml
----
<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-client</artifactId>
    <version>{project-version}</version>
</dependency>
----

. Trigger the contained AutoConfiguration and tell the client where to find the admin to register at:
+
[source]
.application.properties
----
spring.boot.admin.url=http://localhost:8080
----

[[discover-clients-via-spring-cloud-discovery]]
==== Discover clients via Spring Cloud Discovery ====

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.
Also have a look at the http://projects.spring.io/spring-cloud/spring-cloud.html#_spring_cloud_netflix[Spring Cloud Netflix documentation].

. Add spring-cloud-starter-eureka to you dependencies:
+
[source,xml]
.pom.xml
----
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-eureka</artifactId>
    <version>1.0.6.RELEASE</version>
</dependency>
----

. Enable discovery by adding `@EnableDiscoveryClient` to your configuration:
+
[source,java]
----
@Configuration
@EnableAutoConfiguration
@EnableDiscoveryClient
@EnableAdminServer
public class SpringBootAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootAdminApplication.class, args);
    }
}
----

. Tell the Eureka client where to find the service registry:
+
[source]
.application.properties
----
eureka.instance.client.serviceUrl.defaultZone: http://localhost:8761/eureka/
----

See also https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-discovery/[spring-boot-admin-sample-discovery].

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.

[[client-applications]]
== Client applications ==

[[show-version-in-application-list]]
=== Show version in application list ===

To get the version show up in the admin's application list you have to set `info.version`. For example using maven filtering during the build:

[source]
.application.properties
----
info.version=@project.version@
----

[[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`:

[source,xml]
.logback.xml
----
<configuration>
    <include resource="org/springframework/boot/logging/logback/base.xml"/>
    <jmxConfigurator/>
</configuration>
----

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
| 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.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.
| `false`
|===

[[spring-boot-admin-server]]
== Spring Boot Admin Server ==

.Spring Boot Admin Server configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.context-path
| The context-path prefixes the path where the Admin Server's statics assets and API should be served. Relative to the Dispatcher-Servlet.
|

| spring.boot.admin.monitor.period
| Time interval in ms to update the status of applications with expired status-informations.
| 10.000

| spring.boot.admin.monitor.status-lifetime
| Lifetime of application statuses in ms. The applications /health-endpoint will not be queried until the lifetime has expired.
| 10.000
|===


[[spring-cloud-discovery-support]]
=== Spring Cloud Discovery support ===

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>>.

==== Usage of discovery informations ====

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: When *Eureka* discovery is active, the `EurekaServiceInstanceConverter` will use the discovered instances' `homePageUrl` and `healthCheckUrl`. In case the instances' `managment.context-path` is different from the `homePageUrl` you should add an entry `management.context-path` to the instances' `metadata`-map with the corresponding value.

TIP: When the default conversion kicks in, you can use the `spring.boot.admin.discovery.converter.*` properties to control the conversion for all your instances.

.Discovery configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.discovery.enabled
| Enables the DiscoveryClient-support for the admin server.
| `true`

| spring.boot.admin.discovery.management.context-path _(deprecated)_
| If set this will be appended to the service-url from the discovery information.
|

| spring.boot.admin.discovery.converter.management-context-path
| Will be appended to the service-url of the discovered service when the managment-url is converted by the `DefaultServiceInstanceConverter`.
|

| spring.boot.admin.discovery.converter.health-endpoint
| Will be appended to the management-url of the discovered service when the health-url is converted by the `DefaultServiceInstanceConverter`.
| `"health"`
|===

[[hazelcast-support]]
=== Hazelcast support ===
Spring Boot Admin Server supports cluster replication with 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].

. Add Hazelcast to your dependencies:
+
[source,xml]
.pom.xml
----
<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast</artifactId>
</dependency>
----

. Instantiate a HazelcastConfig:
+
[source,java]
----
@Configuration
@EnableAutoConfiguration
@EnableAdminServer
public class SpringBootAdminApplication {
    @Bean
    public Config hazelcastConfig() {
        return new Config().setProperty("hazelcast.jmx", "true")
                .addMapConfig(new MapConfig("spring-boot-admin-application-store")
                    .setBackupCount(1)
                    .setEvictionPolicy(EvictionPolicy.NONE))
                .addListConfig(new ListConfig("spring-boot-admin-event-store")
                    .setBackupCount(1)
                    .setMaxSize(1000));
    }

    public static void main(String[] args) {
        SpringApplication.run(SpringBootAdminApplication.class, args);
    }
}
----

.Hazelcast configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.hazelcast.enabled
| Enables the Hazelcast support
| `true`

| spring.boot.admin.hazelcast.application-store
| Name of the Hazelcast-map to store the applications
| `"spring-boot-admin-application-store"`

| spring.boot.admin.hazelcast.event-store
| Name of the Hazelcast-list to store the events
| `"spring-boot-admin-event-store"`
|===

=== Notifications ===

[[mail-notifications]]
==== Mail notifications ====

Configure a `JavaMailSender` using `spring-boot-starter-mail` and set a recipient.

[source,xml]
.pom.xml
----
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
</dependency>
----

.application.properties
----
spring.mail.host=smtp.example.com
spring.boot.admin.notify.mail.to=admin@example.com
----

.Mail notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.mail.enabled
| Enable mail notifications
| `true`

| spring.boot.admin.notify.mail.ignore-changes
| 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.

.Pagerduty notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.pagerduty.enabled
| Enable mail notifications
| `true`

| spring.boot.admin.notify.pagerduty.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.pagerduty.service-key
| Service-key to use for Pagerduty
|

| spring.boot.admin.notify.pagerduty.url
| The Pagerduty-rest-api url
| `+++"https://events.pagerduty.com/generic/2010-04-15/create_event.json"+++`

| spring.boot.admin.notify.pagerduty.description
| Description to use in the event. SpEL-expressions are supported
| `+++"#{application.name}/#{application.id} is #{to.status}"+++`

| spring.boot.admin.notify.pagerduty.client
| Client-name to use in the event
|

| spring.boot.admin.notify.pagerduty.client-url
| Client-url to use in the event
|
|===

[hipchat-notifications]
==== Hipchat notifications ====
To enable Hipchat notifications you need to create an API token from you Hipchat account and set the appropriate configuration properties.

.Hipchat notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.hipchat.enabled
| Enable Hipchat notifications
| `true`

| spring.boot.admin.notify.hipchat.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.hipchat.url
| The HipChat REST API (V2) URL
|

| spring.boot.admin.notify.hipchat.auth-token
| The API token with access to the notification room
|

| spring.boot.admin.notify.hipchat.room-id
| The ID or url-encoded name of the room to send notifications to
|

| spring.boot.admin.notify.hipchat.notify
| Whether the message should trigger a user notification
| `false`

| spring.boot.admin.notify.hipchat.description
| Description to use in the event. SpEL-expressions are supported
| `+++"<strong>#{application.name}</strong>/#{application.id} is <strong>#{to.status}</strong>"+++`
|
|===

[slack-notifications]
==== Slack notifications ====
To enable Slack notifications you need to add a incoming Webhook under custom integrations on your Slack
account and configure it appropriately.

.Slack notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.slack.enabled
| Enable Slack notifications
| `true`

| spring.boot.admin.notify.slack.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.slack.webhook-url
| The Slack Webhook URL to send notifications
|

| spring.boot.admin.notify.slack.channel
| Optional channel name (without # at the beginning). If different than channel in Slack Webhooks settings
|

| spring.boot.admin.notify.slack.icon
| Optional icon name (without surrounding colons). If different than icon in Slack Webhooks settings
|

| spring.boot.admin.notify.slack.username
| Optional username to send notification if different than in Slack Webhooks settings
| `Spring Boot Admin`

| spring.boot.admin.notify.slack.message
| Message to use in the event. SpEL-expressions and Slack markups are supported
| `+++"*#{application.name}* (#{application.id}) is *#{to.status}*"+++`
|
|===

[reminder-notifactaions]
==== Reminder notifications ====
To get reminders for down/offline applications you can add a `RemindingNotifier` to your `ApplicationContext`. The `RemindingNotifier` uses another `Notifier` as delegate to send the reminders.

.How to configure reminders
[source,java]
----
@Configuration
@EnableScheduling
public class ReminderConfiguration {
    @Autowired
    private Notifier notifier;

    @Bean
    @Primary
    public RemindingNotifier remindingNotifier() {
        RemindingNotifier remindingNotifier = new RemindingNotifier(notifier);
        remindingNotifier.setReminderPeriod(TimeUnit.MINUTES.toMillis(5)); // <1>
        return remindingNotifier;
    }

    @Scheduled(fixedRate = 6000L) // <2>
    public void remind() {
        remindingNotifier().sendReminders();
    }
}
----
<1> The reminders will be sent every 5 minutes.
<2> Schedules sending of due reminders every 60 seconds.

[[faqs]]
== FAQs ==
[qanda]
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.
