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.4.4</version>
    </dependency>
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-server-ui</artifactId>
        <version>1.4.4</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(SpringBootAdminApplication.class, args);
        }
    }
If you want to setup the Spring Boot Admin Server via war-deployment in a servlet-container, please have a look at the spring-boot-admin-sample-war.

See also the spring-boot-admin-sample project.

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. spring-boot-admin-starter-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.4.4</version>
    </dependency>
  2. Trigger the contained AutoConfiguration and tell the client where to find the admin to register at:

    application.yml
    spring.boot.admin.url: http://localhost:8080

2.2.2. 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, but other Spring Cloud Discovery implementations are supported as well. There are examples using Consul and Zookeeper.

Also have a look at the Spring Cloud documentation.

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

    pom.xml
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-eureka</artifactId>
    </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.yml
    eureka:
      instance:
        leaseRenewalIntervalInSeconds: 10
      client:
        registryFetchIntervalSeconds: 5
        serviceUrl:
          defaultZone: ${EUREKA_SERVICE_URL: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 Eureka’s one.

3. Client applications

3.1. Show version in application list

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 Spring Boot Reference Guide.

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>

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 Logback’s JMXConfigurator:

logback-spring.xml
<?xml version="1.0" encoding="UTF-8"?>
<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.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.

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 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.boot.admin.routes.endpoints

The enpoints which will be available via spring boot admin zuul proxy. If you write ui modules using other endpoints you need to add them.

"env, metrics, trace, dump, jolokia, info, configprops, trace, activiti, logfile, refresh, flyway, liquibase"

4.1. Spring Cloud Discovery

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.

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

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

spring.boot.admin.discovery.ignored-services

This services will be ignored when using discovery and not registered as application.

4.2. Clustering

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

4.3.1. Reminder notifications

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
@Configuration
@EnableScheduling
public class NotifierConfiguration {
    @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 = 60_000L) (2)
    public void remind() {
        remindingNotifier().sendReminders();
    }
}
1 The reminders will be sent every 5 minutes.
2 Schedules sending of due reminders every 60 seconds.

4.3.2. 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
@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());
    notifier.setReminderPeriod(TimeUnit.SECONDS.toMillis(10));
    return notifier;
  }

  @Scheduled(fixedRate = 1_000L)
  public void remind() {
    remindingNotifier().sendReminders();
  }
}
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.
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).

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

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

4.3.5. Hipchat notifications

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

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

4.3.6. Slack notifications

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

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

4.4. UI Modules

Additional to the core UI there are following modules which can be included by adding the jar-file to the classpath:

  • spring-boot-admin-server-ui-activiti

  • spring-boot-admin-server-ui-hystrix

  • spring-boot-admin-server-ui-turbine

4.4.1. Hystrix UI Module

The Hystrix module uses the hystrix-dashboard to display the metrics from Hystrix streams.

  1. Add the ui module to your classpath:

    pom.xml
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-server-ui-hystrix</artifactId>
        <version>1.4.4</version>
    </dependency>
  2. Add the /hystrix.stream to the proxified endpoints:

    application.yml
    spring.boot.admin.routes.endpoints: env,metrics,trace,dump,jolokia,info,configprops,trace,logfile,refresh,flyway,liquibase,heapdump,hystrix.stream

4.4.2. Turbine UI Module

The Turbine module uses the hystrix-dashboard to display the metrics from a Turbine stream. The UI module does not configure Turbine for you. Either you run Turbine as a separate application or integrate it into your Spring Boot Admin application. Please see Spring Cloud Reference on setting up Turbine.

  1. Add the ui module to your classpath:

    pom.xml
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-server-ui-turbine</artifactId>
        <version>1.4.4</version>
    </dependency>
  2. Configure the Turbine URL and clusters

    application.yml
    spring.boot.admin.turbine:
      clusters: default
      url: http://localhost:8989/turbine.stream
Table 9. Turbine UI Module configuration options
Property name Description Default value

spring.boot.admin.turbine.enabled

Enable the Spring Boot Admin backend configuration for Turbine.

true

spring.boot.admin.turbine.url

URL to the turbine.stream. Must be reachable from the admin server.

spring.boot.admin.turbine.clusters

List of available Turbine clusters.

"default"

4.4.3. Activiti UI Module

The Activiti module shows information from the /activti endpoint.

  1. Add the ui module to your classpath:

    pom.xml
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-server-ui-activiti</artifactId>
        <version>1.4.4</version>
    </dependency>
  2. Add the /activiti to the proxified endpoints:

    application.yml
    spring.boot.admin.routes.endpoints: env,metrics,trace,dump,jolokia,info,configprops,trace,logfile,refresh,flyway,liquibase,heapdump,activiti

5. Security

5.1. Securing Spring Boot Admin Server

Since there are several approaches on solving authentication and authorization in distributed web applications Spring Boot Admin doesn’t ship a default one. However you can include Spring Security to your Spring Boot Admin Server and configure it the way you like.

5.2. Securing Client’s Actuator Endpoints

The simplest way to secure your actuator endpoints is to use basic authorization and the same username/password for all applications. This way the browser asks for the credentials and if you set zuul.senstivieHeaders: the Zuul Proxy in Spring Boot Admin Server forwards them to the clients.

For more complex solutions (Spring Session, OAuth2, …​) please have a look at the samples in joshiste/spring-boot-admin-samples.

6. 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 monitoring tool also does.

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