Skip to content

S
spring-boot-admin
Commit 54235c8a by Johannes Edmeier
Options

Add asciidoc and remove the nested READMEs

parent a98973c4
Showing with 78 additions and 272 deletions
README.md
......@@ -15,175 +15,86 @@ This application provides a simple GUI to administrate Spring Boot applications
* Download main logfile
* Show details, like
* JVM & memory metrics
* Counter & gauge Metrics
* Datasource Metrics
* Counter & gauge metrics
* Datasource metrics
* Cache metrics
* View Java, system- & environment-properties
* Support for Spring Clouds postable /env- &/refresh-endpoint
* Easy loggerlevel management (for Logback)
* Easy loglevel management (for Logback only)
* Interact with JMX-beans
* View threaddump
* View traces
* Mail and desktop notification on status change
* Event journal of status changes (non persistent)
#### Server application
Add the following dependency to your pom.xml.
```xml
<dependency>
<groupId>de.codecentric</groupId>
<artifactId>spring-boot-admin-server</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>de.codecentric</groupId>
<artifactId>spring-boot-admin-server-ui</artifactId>
<version>1.3.0</version>
</dependency>
```
Create the Spring Boot Admin server with only one single annotation.
```java
@Configuration
@EnableAutoConfiguration
@EnableAdminServer
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
See also the [example project](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample) in this repository.
For configuring hazelcast support see [spring-boot-admin-server](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-server/README.md) or [hazelcast-example project](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-hazelcast)
#### Register / discover client applications
To get all your boot applications shown in spring boot admin you have two choices:
1) either you include the spring-boot-admin-starter-client into your applications
or
2) you add a DiscoveryClient (e.g. Eureka) to your spring boot admin server.
**Note:** If you don't include the spring-boot-admin-starter-client the logfile won't be available with spring boot 1.2.x, due to the fact that the logfile endpoint won't be exposed.
##### Register client applications via spring-boot-admin-starter-client
Each application that want to register itself to the admin application has to include the [spring-boot-admin-starter-client](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-starter-client) as dependency. This starter JAR includes some [AutoConfiguration](http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#using-boot-auto-configuration "Spring Boot documentation") features that includes registering tasks, controller, etc.
```xml
<dependency>
<groupId>de.codecentric</groupId>
<artifactId>spring-boot-admin-starter-client</artifactId>
<version>1.3.0</version>
</dependency>
```
Inside your configuration (e.g. application.properties) you also have to define the URL of the Spring Boot Admin server, e.g.
```
spring.boot.admin.url=http://localhost:8080
```
For all configuration options see [spring-boot-admin-starter-client](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-starter-client/README.md)
##### Discover client applications via DiscoveryClient
Just add spring-clouds ``@EnableDiscoveryClient`` annotation and include an appropriate implementation (e.g. Eureka) to your classpath.
```java
@Configuration
@EnableAutoConfiguration
@EnableDiscoveryClient
@EnableAdminServer
public class SpringBootAdminApplication {
public static void main(String[] args) {
SpringApplication.run(SpringBootAdminApplication.class, args);
}
}
```
```xml
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-eureka</artifactId>
<version>1.0.3.RELEASE</version>
</dependency>
```
See the sample [discovery sample project](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-discovery)
## Getting Started
#### Mail notification on status change
[A quick guide](http://codecentric.github.io/spring-boot-admin/1.3.0/#getting-started) to get started can be found in our docs.
Configure a JavaMailSender using spring-boot-starter-mail and set a recipient:
```xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-mail</artifactId>
</dependency>
```
```
spring.mail.host=smtp.example.com
spring.boot.admin.notify.mail.to=admin@example.com
```
## Reference Guide
For all configuration options see [spring-boot-admin-server](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-server/README.md)
### Snapshot builds
You can access snapshot builds from the sonatype repository:
```xml
<snapshotRepository>
<id>sonatype-nexus-snapshots</id>
<name>Sonatype Nexus Snapshots</name>
<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</snapshotRepository>
```
[Version 1.3.0](http://codecentric.github.io/spring-boot-admin/1.3.0/)
#### Screenshots
## Screenshots
##### Dashboard
### Dashboard
[](url "title")
<img src="https://raw.githubusercontent.com/codecentric/spring-boot-admin/master/screenshot.png">
##### Details
### Details
[](url "title")
<img src="https://raw.githubusercontent.com/codecentric/spring-boot-admin/master/screenshot-details.png">
##### Environment
### Environment
[](url "title")
<img src="https://raw.githubusercontent.com/codecentric/spring-boot-admin/master/screenshot-environment.png">
##### Logging
### Logging
[](url "title")
<img src="https://raw.githubusercontent.com/codecentric/spring-boot-admin/master/screenshot-logging.png">
##### JMX
### JMX
[](url "title")
<img src="https://raw.githubusercontent.com/codecentric/spring-boot-admin/master/screenshot-jmx.png">
##### Threads
### Threads
[](url "title")
<img src="https://raw.githubusercontent.com/codecentric/spring-boot-admin/master/screenshot-threads.png">
##### Trace
### Trace
[](url "title")
<img src="https://raw.githubusercontent.com/codecentric/spring-boot-admin/master/screenshot-trace.png">
##### Journal
### Journal
[](url "title")
<img src="https://raw.githubusercontent.com/codecentric/spring-boot-admin/master/screenshot-journal.png">
## Snapshot builds
You can access snapshot builds from the sonatype repository:
```xml
<snapshotRepository>
<id>sonatype-nexus-snapshots</id>
<name>Sonatype Nexus Snapshots</name>
<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</snapshotRepository>
```
#### Build
## Build
In order to build spring-boot-admin you need to have node.js and npm on your `PATH`.
```shell
mvn clean package
```
#### Set version for next release
## Set version for next release
```shell
mvn build-helper:parse-version versions:set versions:commit -DnewVersion=1.0.0-SNAPSHOT
mvn versions:set versions:commit -DnewVersion=1.0.0-SNAPSHOT
```
pom.xml
......@@ -22,12 +22,14 @@
<build-plugin.jacoco.version>0.7.5.201505241946</build-plugin.jacoco.version>
<build-plugin.coveralls.version>4.0.0</build-plugin.coveralls.version>
<build-plugin.gpg.version>1.6</build-plugin.gpg.version>
<build-plugin.asciidoctor.version>1.5.2</build-plugin.asciidoctor.version>
</properties>
<modules>
<module>spring-boot-admin-server</module>
<module>spring-boot-admin-server-ui</module>
<module>spring-boot-admin-samples</module>
<module>spring-boot-admin-starter-client</module>
<module>spring-boot-admin-docs</module>
</modules>
<organization>
<name>codecentric AG</name>
......@@ -94,6 +96,11 @@
<artifactId>maven-gpg-plugin</artifactId>
<version>${build-plugin.gpg.version}</version>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${build-plugin.asciidoctor.version}</version>
</plugin>
</plugins>
</pluginManagement>
</build>
......
spring-boot-admin-docs/pom.xml 0 → 100644
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>de.codecentric</groupId>
<artifactId>spring-boot-admin</artifactId>
<version>1.3.1-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
<groupId>de.codecentric</groupId>
<artifactId>spring-boot-admin-docs</artifactId>
<packaging>pom</packaging>
<name>Spring Boot Admin Docs</name>
<description>Spring Boot Admin Documentation</description>
<url>https://github.com/codecentric/spring-boot-admin/</url>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>index.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<revnumber>${project.version}</revnumber>
<projectversion>${project.version}</projectversion>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
spring-boot-admin-samples/pom.xml
......@@ -14,9 +14,6 @@
<name>Spring Boot Admin Samples</name>
<description>Spring Boot Admin Samples</description>
<url>https://github.com/codecentric/spring-boot-admin/</url>
<properties>
<main.basedir>${basedir}/..</main.basedir>
</properties>
<modules>
<module>spring-boot-admin-sample</module>
<module>spring-boot-admin-sample-war</module>
......
spring-boot-admin-server/README.md deleted 100644 → 0
spring-boot-admin-server
========================
## Easy Setup
Add the following dependency to your pom.xml.
```xml
<dependency>
<groupId>de.codecentric</groupId>
<artifactId>spring-boot-admin-server</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>de.codecentric</groupId>
<artifactId>spring-boot-admin-server-ui</artifactId>
<version>1.3.0</version>
</dependency>
```
Create the Spring Boot Admin Server with only one single Annotation.
Example in spring-admin-samples/spring-boot-admin-sample.
```java
@Configuration
@EnableAutoConfiguration
@EnableAdminServer
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
## Spring Cloud DiscoveryClient support
The Spring Boot Admin Server is capable of using Spring Clouds DiscoveryClient to discover applications. When you do this the clients don't have to include the spring-boot-admin-starter-client. You just have to configure a DiscoveryClient - everything else is done by AutoConfiguration.
See the [discovery sample project](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-discovery) in this repository.
One note: If you omit the Spring Boot Admin Client in you Client Applications you can't download the logfile (but hopefully my pull request will make it into Spring Boot 1.3.0);
### Further configuration
Since the DiscoveryClient doesn't tell the management.context-path you can suffix the url for all discovered clients by setting ``spring.boot.admin.discovery.management.context-path``.
Explictly disable DiscoveryClient support by setting ``spring.boot.admin.discover.enabled=false``.
## Mail notification:
To enable mail-notification you just have to add a JavaMailSender to you ApplicationContext. The simplest way to achieve this is by adding the spring-boot-mail-starter to your dependencies and setting `spring.mail.host`.
### Further options:
| Name | Description |
| --------------------- | ----------- |
|spring.boot.admin.notify.mail.enabled|enable mail notification (default: true)|
|spring.boot.admin.notify.mail.to|comma-delimited list of mail recipients (default: "root@localhost")|
|spring.boot.admin.notify.mail.cc|comma-delimited list of mail cc-recipients|
|spring.boot.admin.notify.mail.from|sender of mail|
|spring.boot.admin.notify.mail.subject|mail-subject; SpEL-expressions supported (default: "#{application.name} (#{application.id}) is #{to.status}") |
|spring.boot.admin.notify.mail.text|mail-body; SpEL-expressions supported (default: "#{application.name} (#{application.id})\nstatus changed from #{from.status} to #{to.status}\n\n#{application.healthUrl}"|
|spring.boot.admin.notify.mail.ignoreChanges|comma-delimited list of status changes to be ignored. (default: "UNKNOWN:UP")|
## Pagerduty notification:
To enable pagerduty-notifications you just have to add a generic service for your pagerduty-account and set ``spring.boot.admin.notify.pagerduty.service-keya`` to the service-key.
### Further options:
| Name | Description |
| ---------------------- | ----------- |
|spring.boot.admin.notify.pagerduty.enabled|enable mail notification (default: true)|
|spring.boot.admin.notify.pagerduty.service-key | service-key for Pagerduty |
|spring.boot.admin.notify.pagerduty.uri | The Pagerduty-rest-api url (default: 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 supported (default: #{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.clientUrl | client-url to use in the event |
|spring.boot.admin.notify.pagerduty.ignoreChanges|comma-delimited list of status changes to be ignored. (default: "UNKNOWN:UP")|
## Hazelcast Support
Spring Boot Admin Server supports cluster replication with Hazelcast. It is automatically enabled when a HazelcastConfig- or HazelcastInstance is present.
Also have a look at the [Spring Boot support for Hazelcast](http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#boot-features-hazelcast).
1. Add Hazelcast to your dependencies:
```xml
<dependency>
<groupId>com.hazelcast</groupId>
<artifactId>hazelcast</artifactId>
</dependency>
```
2. Instantiate a HazelcastConfig:
```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);
}
}
```
### Further configuration
Disable Hazelcast support by setting ``spring.boot.admin.hazelcast.enabled=false``.
To alter the name of the hazelcast-map backing the application-store set ``spring.boot.admin.hazelcast.map= my-own-map-name``.
To alter the name of the hazelcast-list backing the event-store set ``spring.boot.admin.hazelcast.event-store=my-own-list-name``
spring-boot-admin-starter-client/README.md deleted 100644 → 0
spring-boot-starter-admin-client
================================
This [Spring-Boot starter](http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#using-boot-starter-poms "Spring Boot Reference Guide") provides services and controllers that are required if an application should be able to be administrated with the [spring-boot-admin application](https://github.com/codecentric/spring-boot-admin "GitHub project").
This client uses the [AutoConfiguration](http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#using-boot-auto-configuration "Spring Boot Reference Guide") feature of Spring Boot to register service and controller beans in the application context.
The main service that is used is a registrar that registeres the application at the spring-boot-admin application by periodically calling a REST-API to perform the registration of itself.
##Configuration properties
### spring-boot-admin
| Name | Description |
| --------------------- | ----------- |
| spring.boot.admin.url | URL of the spring-boot-admin application to register at.<br>_Mandatory_. | |
| spring.boot.admin.contextPath | Context-path of registration point.<br>Default: api/applications |
| spring.boot.admin.username | Username for Http-Basic authentication. Default: empty |
| spring.boot.admin.password | Password for Http-Basic authentication. Default: empty |
| spring.boot.admin.period | Time period for registration repeat.<br>Default: 10000 |
| spring.boot.admin.autoDeregistration | Swtich to enable auto-deregistration at admin when context is closed<br>Default: false |
| spring.boot.admin.client.serviceUrl | Client-management-URL to register with. Can be overriden in case the reachable URL is different (e.g. Docker). Must be unique in registry.<br>Default: is guessed based on hostname, server.port and server.context-path |
| spring.boot.admin.client.managementUrl | Client-management-URL to register with. Can be overriden in case the reachable URL is different (e.g. Docker). Must be unique in registry.<br>Default: is guessed based on serviceUrl management.port and management.context-path|
| spring.boot.admin.client.healthUrl | Client-management-URL to register with. Can be overriden in case the reachable URL is different (e.g. Docker). Must be unique in registry.<br>Default: is guessed based on managementUrl and endpoints.health.id |
| spring.boot.admin.client.name | Name to register with. Defaults to the ApplicationContexts name. Only set when it should differ.<br>Default: _${spring.application.name}_ if set, spring-boot-application otherwise. |
| spring.boot.admin.client.preferIp | Use the ip-address rather then the hostname in the guessed urls. It's required to set `server.address` and `management.address`respectively. |
### Other configuration properties
Options from other spring boot features. These should be set to enable all features.
| Name | Description |
| ----------------------- | ----------- |
| spring.application.name | Name to be shown in the application list. Name of the ApplicationContext. |
| info.version | Version number to be shown in the application list. Also published via /info-endpoint. |
### Logging Support ([Logback](http://logback.qos.ch/))
The spring-boot-admin-server-ui allows users to manipulate logger levels dynamically. To support this, a `JMXConfigurator` must be made available by the spring boot client app. This is conveniently done by the following configuration in your logback configuration file(under the root `<configuration>` element).
```
<jmxConfigurator/>
```
Note that, the UI will intelligently try to determine the JMXConfigurator by first attempting to locate one with the application name (spring.application.name) and then falliing back to a default configuration. This is useful if you have the need to deploy multiple spring boot applications to the same JVM. In such a case, specify a context name in your logback configuration as follows:
```
<contextName>your_spring_boot_application_name</contextName>
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment