Info contributor documentation

This commit documents the new `InfoContributor` infrastructure.

Closes gh-2559

spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -113,6 +113,96 @@ Application code that you want to run as your business logic can be implemented
 
 
 
+[[howto-automatic-expansion]]
+=== Automatically expand properties at build time
+Rather than hardcoding some properties that are also specified in your project's build
+configuration, you can automatically expand them using the existing build configuration
+instead. This is possible in both Maven and Gradle.
+
+
+
+[[howto-automatic-expansion-maven]]
+==== Automatic property expansion using Maven
+You can automatically expand properties from the Maven project using resource
+filtering. If you use the `spring-boot-starter-parent` you can then refer to your
+Maven '`project properties`' via `@..@` placeholders, e.g.
+
+[source,properties,indent=0]
+----
+	app.encoding=@project.build.sourceEncoding@
+	app.java.version=@java.version@
+----
+
+TIP: The `spring-boot:run` can add `src/main/resources` directly to the classpath
+(for hot reloading purposes) if you enable the `addResources` flag. This circumvents
+the resource filtering and this feature. You can use the `exec:java` goal instead
+or customize the plugin's configuration, see the
+{spring-boot-maven-plugin-site}/usage.html[plugin usage page] for more details.
+
+If you don't use the starter parent, in your `pom.xml` you need (inside the `<build/>`
+element):
+
+[source,xml,indent=0]
+----
+    <resources>
+        <resource>
+            <directory>src/main/resources</directory>
+            <filtering>true</filtering>
+        </resource>
+    </resources>
+----
+
+and (inside `<plugins/>`):
+
+[source,xml,indent=0]
+----
+	<plugin>
+		<groupId>org.apache.maven.plugins</groupId>
+		<artifactId>maven-resources-plugin</artifactId>
+		<version>2.7</version>
+		<configuration>
+			<delimiters>
+				<delimiter>@</delimiter>
+			</delimiters>
+			<useDefaultDelimiters>false</useDefaultDelimiters>
+		</configuration>
+	</plugin>
+----
+
+NOTE: The `useDefaultDelimiters` property is important if you are using standard Spring
+placeholders in your configuration (e.g. `${foo}`). These may be expanded by the build if
+that property is not set to `false`.
+
+
+
+[[howto-automatic-expansion-gradle]]
+==== Automatic property expansion using Gradle
+You can automatically expand properties from the Gradle project by configuring the
+Java plugin's `processResources` task to do so:
+
+[source,groovy,indent=0]
+----
+	processResources {
+		expand(project.properties)
+	}
+----
+
+You can then refer to your Gradle project's properties via placeholders, e.g.
+
+[source,properties,indent=0]
+----
+	app.name=${name}
+	app.description=${description}
+----
+
+NOTE: Gradle's `expand` method uses Groovy's `SimpleTemplateEngine` which transforms
+`${..}` tokens. The `${..}` style conflicts with Spring's own property placeholder
+mechanism. To use Spring property placeholders together with automatic expansion
+the Spring property placeholders need to be escaped like `\${..}`.
+
+
+
+
 [[howto-externalize-configuration]]
 === Externalize the configuration of SpringApplication
 A `SpringApplication` has bean properties (mainly setters) so you can use its Java API as
@@ -2131,6 +2221,95 @@ automatically compile your code whenever a file is saved.
 
 
 
+[[howto-build-info]]
+=== Generate build information
+Both the Maven and Gradle plugin allow to generate build information containing
+the coordinates, name and version of the project. The plugin can also be configured
+to add additional properties through configuration. When such file is present,
+Spring Boot auto-configures a `BuildProperties` bean.
+
+To generate build information with Maven, add an execution for the `build-info` goal:
+
+[source,xml,indent=0,subs="verbatim,quotes,attributes"]
+----
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.springframework.boot</groupId>
+				<artifactId>spring-boot-maven-plugin</artifactId>
+				<version>{spring-boot-version}</version>
+				<executions>
+					<execution>
+						<goals>
+							<goal>build-info</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+----
+
+TIP: Check the {spring-boot-maven-plugin-site}/[Spring Boot Maven Plugin documentation]
+for more details.
+
+And to do the same with Gradle:
+
+[source,groovy,indent=0,subs="verbatim,attributes"]
+----
+	springBoot  {
+		buildInfo()
+	}
+----
+
+Additional properties can be added using the DSL:
+
+[source,groovy,indent=0,subs="verbatim,attributes"]
+----
+	springBoot  {
+		buildInfo {
+			additionalProperties = [
+				'foo': 'bar'
+			]
+		}
+	}
+----
+
+
+
+[[howto-git-info]]
+=== Generate git information
+
+Both Maven and Gradle allow to generate a `git.properties` file containing information
+about the state of your `git` source code repository when the project was built.
+
+For Maven users the `spring-boot-starter-parent` POM includes a pre-configured plugin to
+generate a `git.properties` file. Simply add the following declaration to your POM:
+
+[source,xml,indent=0]
+----
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>pl.project13.maven</groupId>
+				<artifactId>git-commit-id-plugin</artifactId>
+			</plugin>
+		</plugins>
+	</build>
+----
+
+Gradle users can achieve the same result using the
+https://plugins.gradle.org/plugin/com.gorylenko.gradle-git-properties[`gradle-git-properties`] plugin
+
+[source,groovy,indent=0]
+----
+	plugins {
+		id "com.gorylenko.gradle-git-properties" version "1.4.6"
+	}
+----
+
+
+
 [[howto-customize-dependency-versions-with-maven]]
 [[howto-customize-dependency-versions]]
 === Customize dependency versions

spring-boot-docs/src/main/asciidoc/production-ready-features.adoc

@@ -371,145 +371,138 @@ if you access the health endpoint over HTTP. For example you could map `FATAL` t
 
 
 [[production-ready-application-info]]
-=== Custom application info information
-You can customize the data exposed by the `info` endpoint by setting `+info.*+` Spring
-properties. All `Environment` properties under the info key will be automatically
-exposed. For example, you could add the following to your `application.properties`:
+=== Application information
+Application information exposes various information collected from all
+{sc-spring-boot-actuator}/info/InfoContributor.{sc-ext}[`InfoContributor`] beans defined
+in your `ApplicationContext`. Spring Boot includes a number of auto-configured
+`InfoContributors` and you can also write your own.
 
-[source,properties,indent=0]
-----
-	info.app.name=MyService
-	info.app.description=My awesome service
-	info.app.version=1.0.0
-----
+[[production-ready-application-info-autoconfigure]]
+==== Auto-configured InfoContributors
 
+The following `InfoContributors` are auto-configured by Spring Boot when appropriate:
 
+[cols="1,4"]
+|===
+|Name |Description
 
-[[production-ready-application-info-automatic-expansion]]
-==== Automatically expand info properties at build time
-Rather than hardcoding some properties that are also specified in your project's build
-configuration, you can automatically expand info properties using the existing build
-configuration instead. This is possible in both Maven and Gradle.
+|{sc-spring-boot-actuator}/info/EnvironmentInfoContributor.{sc-ext}[`EnvironmentInfoContributor`]
+|Expose any key from the `Environment` under the `info` key.
 
+|{sc-spring-boot-actuator}/info/GitInfoContributor.{sc-ext}[`GitInfoContributor`]
+|Expose git information if a `git.properties` file is available.
 
+|{sc-spring-boot-actuator}/info/BuildInfoContributor.{sc-ext}[`BuildInfoContributor`]
+|Expose build information if a `META-INF/boot/build.properties` file is available.
+|===
 
-[[production-ready-application-info-automatic-expansion-maven]]
-===== Automatic property expansion using Maven
-You can automatically expand info properties from the Maven project using resource
-filtering. If you use the `spring-boot-starter-parent` you can then refer to your
-Maven '`project properties`' via `@..@` placeholders, e.g.
+TIP: It is possible to disable them all using the `management.info.defaults.enabled`
+property.
+
+[[production-ready-application-info-env]]
+==== Custom application info information
+You can customize the data exposed by the `info` endpoint by setting `+info.*+` Spring
+properties. All `Environment` properties under the info key will be automatically
+exposed. For example, you could add the following to your `application.properties`:
 
 [source,properties,indent=0]
 ----
-	project.artifactId=myproject
-	project.name=Demo
-	project.version=X.X.X.X
-	project.description=Demo project for info endpoint
-	info.build.artifact=@project.artifactId@
-	info.build.name=@project.name@
-	info.build.description=@project.description@
-	info.build.version=@project.version@
+	info.app.encoding=UTF-8
+	info.app.java.source=1.8
+	info.app.java.target=1.8
 ----
 
-TIP: The `spring-boot:run` can add `src/main/resources` directly to the classpath
-(for hot reloading purposes) if you enable the `addResources` flag. This circumvents
-the resource filtering and this feature. You can use the `exec:java` goal instead
-or customize the plugin's configuration, see the
-{spring-boot-maven-plugin-site}/usage.html[plugin usage page] for more details.
+[TIP]
+====
+Rather than hardcoding those values you could also
+<<howto.adoc#howto-automatic-expansion,expand info properties at build time>>.
 
-If you don't use the starter parent, in your `pom.xml` you need (inside the `<build/>`
-element):
+Assuming you are using Maven, you could rewrite the example above as follows:
 
-[source,xml,indent=0]
+[source,properties,indent=0]
 ----
-    <resources>
-        <resource>
-            <directory>src/main/resources</directory>
-            <filtering>true</filtering>
-        </resource>
-    </resources>
+	info.app.encoding=@project.build.sourceEncoding@
+	info.app.java.source=@java.version@
+	info.app.java.target=@java.version@
 ----
+====
 
-and (inside `<plugins/>`):
-
-[source,xml,indent=0]
-----
-	<plugin>
-		<groupId>org.apache.maven.plugins</groupId>
-		<artifactId>maven-resources-plugin</artifactId>
-		<version>2.6</version>
-		<configuration>
-			<delimiters>
-				<delimiter>@</delimiter>
-			</delimiters>
-			<useDefaultDelimiters>false</useDefaultDelimiters>
-		</configuration>
-	</plugin>
-----
 
-NOTE: The `useDefaultDelimiters` property is important if you are using standard Spring
-placeholders in your configuration (e.g. `${foo}`). These may be expanded by the build if
-that property is not set to `false`.
 
+[[production-ready-application-info-git]]
+==== Git commit information
+Another useful feature of the `info` endpoint is its ability to publish information
+about the state of your `git` source code repository when the project was built. If a
+`GitProperties` bean is available, the `git.branch`, `git.commit.id` and
+`git.commit.time` properties will be exposed.
 
+TIP: A `GitProperties` bean is auto-configured if a `git.properties` file is available
+at the root of the classpath. See
+<<howto.adoc#howto-git-info,Generate git information>> for more details.
 
-[[production-ready-application-info-automatic-expansion-gradle]]
-===== Automatic property expansion using Gradle
-You can automatically expand info properties from the Gradle project by configuring
-the Java plugin's `processResources` task to do so:
+If you want to display the full git information (i.e. the full content of
+`git.properties`), use the `management.info.git.mode` property:
 
-[source,groovy,indent=0]
+[source,properties,indent=0]
 ----
-	processResources {
-		expand(project.properties)
-	}
+	management.info.git.mode=full
 ----
 
-You can then refer to your Gradle project's properties via placeholders, e.g.
+
+
+[[production-ready-application-info-build]]
+==== Build information
+The `info` endpoint can also publish information about your build if a `BuildProperties`
+bean is available. This happens if a `META-INF/boot/build.properties` file is available
+in the classpath.
+
+TIP: The Maven and Gradle plugins can both generate that file, see
+<<howto.adoc#howto-build-info,Generate build information>> for more details.
+
+If additional properties are present they are not exposed unless configured explicitly:
 
 [source,properties,indent=0]
 ----
-	info.build.name=${name}
-	info.build.description=${description}
-	info.build.version=${version}
+	management.info.build.mode=full
 ----
 
-NOTE: Gradle's `expand` method uses Groovy's `SimpleTemplateEngine` which transforms
-`${..}` tokens. The `${..}` style conflicts with Spring's own property placeholder
-mechanism. To use Spring property placeholders together with automatic expansion
-the Spring property placeholders need to be escaped like `\${..}`.
 
+[[production-ready-application-info-custom]]
+==== Writing custom InfoContributors
+To provide custom application information you can register Spring beans that implement
+the {sc-spring-boot-actuator}/info/InfoContributor.{sc-ext}[`InfoContributor`] interface.
 
+The example below contributes an `example` entry with a single value:
 
-[[production-ready-git-commit-information]]
-==== Git commit information
-Another useful feature of the `info` endpoint is its ability to publish information
-about the state of your `git` source code repository when the project was built. If a
-`git.properties` file is contained in your jar the `git.branch` and `git.commit`
-properties will be loaded.
+[source,java,indent=0]
+----
+	import java.util.Collections;
 
-For Maven users the `spring-boot-starter-parent` POM includes a pre-configured plugin to
-generate a `git.properties` file. Simply add the following declaration to your POM:
+	import org.springframework.boot.actuate.info.Info;
+	import org.springframework.boot.actuate.info.InfoContributor;
+	import org.springframework.stereotype.Component;
 
-[source,xml,indent=0]
-----
-	<build>
-		<plugins>
-			<plugin>
-				<groupId>pl.project13.maven</groupId>
-				<artifactId>git-commit-id-plugin</artifactId>
-			</plugin>
-		</plugins>
-	</build>
+	@Component
+	public class ExampleInfoContributor implements InfoContributor {
+
+		@Override
+		public void contribute(Info.Builder builder) {
+			builder.withDetail("example",
+					Collections.singletonMap("key", "value"));
+		}
+
+	}
 ----
 
-Gradle users can achieve the same result using the
-https://plugins.gradle.org/plugin/com.gorylenko.gradle-git-properties[`gradle-git-properties`] plugin
+if you hit the `info` endpoint you should see a response that contains the following
+additional entry:
 
-[source,groovy,indent=0]
+[source,json,indent=0]
 ----
-	plugins {
-		id "com.gorylenko.gradle-git-properties" version "1.4.6"
+	{
+		"example": {
+			"key" : "value"
+		}
 	}
 ----