1. What is Spring Boot Admin?

Spring Boot Admin is a simple application to manage and monitor your 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.

2. Getting started

2.1. Set up admin server

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

  1. Add Spring Boot Admin Server and the UI to your dependencies:

    pom.xml
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-server</artifactId>
        <version>1.3.2</version>
    </dependency>
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-server-ui</artifactId>
        <version>1.3.2</version>
    </dependency>
  2. Pull in the Boot Admin Server configuration via adding @EnableAdminServer to your configuration:

    @Configuration
    @EnableAutoConfiguration
    @EnableAdminServer
    public class SpringBootAdminApplication {
        public static void main(String[] args) {
            SpringApplication.run(Application.class, args);
        }
    }

2.2. 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 Spring Cloud Discovery (e.g. Eureka)

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

  1. Add spring-boot-admin-starter-client to your dependencies:

    pom.xml
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-starter-client</artifactId>
        <version>1.3.2</version>
    </dependency>
  2. Trigger the contained AutoConfiguration and tell the client where to find the admin to register at:

    application.properties
    spring.boot.admin.url=http://localhost:8080

2.2.2. 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 Spring Cloud Netflix documentation.

  1. Add spring-cloud-starter-eureka to you dependencies:

    pom.xml
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-eureka</artifactId>
        <version>1.0.4.RELEASE</version>
    </dependency>
  2. Enable discovery by adding @EnableDiscoveryClient to your configuration:

    @Configuration
    @EnableAutoConfiguration
    @EnableDiscoveryClient
    @EnableAdminServer
    public class SpringBootAdminApplication {
        public static void main(String[] args) {
            SpringApplication.run(SpringBootAdminApplication.class, args);
        }
    }
  3. Tell the Eureka client where to find the service registry:

    application.properties
    eureka.instance.client.serviceUrl.defaultZone: http://localhost:8761/eureka/
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 Eurekas one.

3. Client applications

3.1. Show version in application list

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

application.properties
info.version=@project.version@

3.2. JMX-bean management

To interact with JMX-beans in the admin UI you have to include 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:

pom.xml
<dependency>
    <groupId>org.jolokia</groupId>
    <artifactId>jolokia-core</artifactId>
</dependency>

3.3. Loglevel managment

Currently the loglevel management is only available for Logback. It is accessed via JMX so include Jolokia in your application. In addition you have configure Logbacks JMXConfigurator:

logback.xml
<configuration>
    <include resource="org/springframework/boot/logging/logback/base.xml"/>
    <jmxConfigurator/>
</configuration>
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.

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

Table 1. Spring Boot Admin Client configuration options
Property name Description Default value

spring.boot.admin.url

URL of the spring-boot-admin application 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-authetication when registering at the admin server.

spring.boot.admin.period

Interval for repeating the registration (in ms).

10.000

spring.boot.admin.auto-deregistration

Swtich to enable auto-deregistration at admin when context is closed.

false

spring.boot.admin.client.health-url

Client-health-url to register with. Can be overriden 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 overriden 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 overriden 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. It’s required to set server.address and `management.address`respectively.

false

4. Spring Boot Admin Server

Table 2. 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 Servers 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 iapplication statuses in ms. The applications /health-endpoint will not be queried until the lifetime has expired.

10.000

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

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

If set this will be appended to the service-url from the discovery information.

Currently the implementation is not specific to any DiscoveryClient implementation. Unfortunately the DiscoveryClient doesn’t expose the health- or management-url, so if you’re not sticking to the defaults and setting spring.boot.admin.discovery.management.context-path doesn’t suffice, you can add a bean extending ApplicationDiscoveryListener to your admin server and provide your own conversion.

4.2. 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 confugure the Hazelcast instance to be persistent, to keep the status over restarts. Also have a look at the Spring Boot support for Hazelcast.

  1. Add Hazelcast to your dependencies:

    pom.xml
    <dependency>
        <groupId>com.hazelcast</groupId>
        <artifactId>hazelcast</artifactId>
    </dependency>
  2. Instantiate a HazelcastConfig:

    @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);
        }
    }
Table 4. 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"

4.3. Mail notifications

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

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
Table 5. 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}"

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

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

5. FAQs

  1. 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 monitioring tool also does.

  2. How do I disable Spring Boot Admin Client for my unit tests?

    The AutoConfiguration is triggered by the presence of the spring.boot.admin.url. So if you don’t set this property for your tests, the Spring Boot Admin Client is not active.

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