Spring Boot Info Actuator Tutorial

10.05.2017 by Jens in Spring Boot

The Spring Boot Actuators are a big helper and time saver when you bring your application into production. They expose different types of information, like health, metrics, dump, info, etc. out of the box and you can even expose your informations via well-defined interfaces.

Especially the health, metrics and info endpoints are invaluable, and you can plug them into your monitoring solutions.

In this article, we are going to take a closer look at the info endpoint of the Spring Boot Actuators and why you should care about it.

What is it?

The info endpoint provides arbitrary data of your application in a standardized way. You don't have to code your own API to expose those values. Just plug into Info Actuator.

Why should I care?

In larger and complex deployment situations where you have dozens of different applications and application version running in your system, the most common questions are "what app version is running on that server" and "Is change x deployed?". That's where the info actuator comes in and helps.

How to use it?

The first thing you need to do is add the Spring Boot Actuator Starter to your Maven POM (if you haven't already).

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

The info endpoint is accessible under /info. Start your application at hit the endpoint.

And probably you will get an empty result. That's fine; we are going to change that now.

The code for this tutorial is also available on github.

Providing Arbitrary Static Information

The info actuator provides a mechanism to expose arbitrary static information. Every value with the prefix info. in the application.properties (or YAML) are exposed.

info.app.info=sample of a static information

When you refresh the info endpoint, you will get a JSON like

{
    "app": {
        "info": "sample of a static information"
    }
}

Seems pretty limited, right? Nah, let's see how we can add information from a maven build.

Providing Maven Build Information

Usually, the first thing in providing same valuable data is to expose information of the maven build.

You can either use the Maven property replacement mechanism and use them in the application.properties like

info.app.name = @project.name@
info.app.groupId = @project.groupId@
info.app.artifactId = @project.artifactId@
info.app.version = @project.version@

If you run this now, the properties are replaced during the Maven build with the actual values, and /info contains now

"app": {
    "groupId": "de.codeboje.springboot.tutorials",
    "name": "spring-boot-actuator-info-tutorial",
    "version": "0.0.1-SNAPSHOT",
    "artifactId": "info-actuator",
}

However, there is a second way. We use the BuildInfoContributor which will get its values from META-INF/build-info.properties file and exposes them if the file is available.

The build-info.properties can be created by the Spring Boot Maven Plugin during build when we add the build-info to its execution like

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>build-info</goal>
            </goals>
        </execution>
    </executions>
</plugin>

When we rebuild and refresh /info,

"build": {
    "version": "0.0.1-SNAPSHOT",
    "artifact": "info-actuator",
    "name": "spring-boot-actuator-info-tutorial",
    "group": "de.codeboje.springboot.tutorials",
    "time": 1494405315000
}

The build-info also supports the configuration of additional properties to expose. Just add them like

<configuration>
    <additionalProperties>
        <encoding.source>UTF-8</encoding.source>
        <encoding.reporting>UTF-8</encoding.reporting>
        <java.source>${maven.compiler.source}</java.source>
        <java.target>${maven.compiler.target}</java.target>
    </additionalProperties>
</configuration>

and they will be available in the response too.

Providing Git Information

As with the BuildInfoContributor, Spring Boot also makes it easy to add Git information to the endpoint. GitInfoContributor exposes the values of a git-properties file when available in the classpath.

Let's provide it. The heavy lifting is done by the_git-commit-id-plugin_ Maven Plugin, and we add it to the build plugins section along with the Spring Boot Maven Plugin.

When we build our application now, Git information are stored in the properties file.

<plugin>
    <groupId>pl.project13.maven</groupId>
    <artifactId>git-commit-id-plugin</artifactId>
</plugin>

After refreshing /info you will see something like

"git": {
    "commit": {
        "time": 1494401209000,
        "id": "44100c0"
    },
    "branch": "master"
}

You will get the commits time and id and also the name of the branch.

By adding

management.info.git.mode=full

to the application.properties file, we can expose way more. Refresh /info. I spare you the long sample here.

Provide Dynamic Information During Runtime

However, the previous ways do not work if you want to expose runtime or dynamic data, like how many users you have in your database or whatever makes sense for your service. Spring Boot has us covered here too. We can plugin with our own implementations of a InfoContributor.

The interface has only one method contribute, and we receive a Builder to add our own values. Builder offers us two methods for adding new details, withDetail for adding a single key and withDetails for adding key/values from a map.

Our implementation must extend the interface and be a regular Spring Bean. Spring Boot will pick it up automatically.

@Component
public class SampleInfoContributor implements InfoContributor {

    @Override
    public void contribute(Builder builder) {
        builder.withDetail("sample", new SecureRandom().nextLong());
    }

}

Refreshing /info now will provide our value

"sample":-7287473670154715380

Conclusion

Spring Boot makes it pretty straight forward to expose custom application information in a standard way. We don't have to code this mechanism ourselves now. Exposing build data is invaluable for me and has helped countless times when maintaining and debugging applications.

Add it to your toolbox, it doesn't take long to setup and will help you in the long run.


comments powered by Disqus