diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc index 7d9a189a53..47b8a72eea 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -2177,6 +2177,22 @@ The patterns to use can be customized using the `management.endpoint.env.keys-to +[[howto-map-health-indicators-to-metrics]] +=== Map Health Indicators to Micrometer Metrics +Spring Boot health indicators return a `Status` type to indicate the overall system health. +If you want to monitor or alert on levels of health for a particular application, you can export these statuses as metrics via Micrometer. +By default, the status codes "`up`", "`down`", "`out of service`" and "`unknown`" are used by Spring Boot. +To export these, you'll need to convert these states to some set of numbers so that they can be used with a Micrometer `Gauge`. + +The follow example shows one way to write such an exporter: + +[source,java,indent=0,subs="verbatim,quotes,attributes"] +---- +include::{code-examples}/actuate/metrics/MetricsHealthMicrometerExportExample.java[tag=configuration] +---- + + + [[howto-security]] == Security This section addresses questions about security when working with Spring Boot, including questions that arise from using Spring Security with Spring Boot. diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/metrics/MetricsHealthMicrometerExportExample.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/metrics/MetricsHealthMicrometerExportExample.java new file mode 100644 index 0000000000..ad65dd1ed7 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/metrics/MetricsHealthMicrometerExportExample.java @@ -0,0 +1,65 @@ +/* + * Copyright 2012-2020 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.actuate.metrics; + +import java.util.Map; + +import io.micrometer.core.instrument.Gauge; +import io.micrometer.core.instrument.MeterRegistry; + +import org.springframework.boot.actuate.health.CompositeHealthIndicator; +import org.springframework.boot.actuate.health.HealthAggregator; +import org.springframework.boot.actuate.health.HealthIndicator; +import org.springframework.boot.actuate.health.Status; +import org.springframework.context.annotation.Configuration; + +/** + * Example to show how to export {@link HealthIndicator} beans to a {@link MeterRegistry}. + * + * @author Phillip Webb + */ +public class MetricsHealthMicrometerExportExample { + + // tag::configuration[] + @Configuration + public class HealthMetricsConfiguration { + + public HealthMetricsConfiguration(MeterRegistry registry, HealthAggregator aggregator, + Map indicators) { + // This example presumes common tags (such as the app) are applied elsewhere + HealthIndicator health = new CompositeHealthIndicator(aggregator, indicators); + Gauge.builder("health", health, this::getStatusCode).strongReference(true).register(registry); + } + + private int getStatusCode(HealthIndicator health) { + Status status = health.health().getStatus(); + if (Status.UP.equals(status)) { + return 3; + } + if (Status.OUT_OF_SERVICE.equals(status)) { + return 2; + } + if (Status.DOWN.equals(status)) { + return 1; + } + return 0; + } + + } + // end::configuration[] + +} diff --git a/spring-boot-project/spring-boot-docs/src/test/java/org/springframework/boot/docs/actuate/metrics/MetricsHealthMicrometerExportExampleTests.java b/spring-boot-project/spring-boot-docs/src/test/java/org/springframework/boot/docs/actuate/metrics/MetricsHealthMicrometerExportExampleTests.java new file mode 100644 index 0000000000..9d964183b4 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/test/java/org/springframework/boot/docs/actuate/metrics/MetricsHealthMicrometerExportExampleTests.java @@ -0,0 +1,79 @@ +/* + * Copyright 2012-2020 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.actuate.metrics; + +import io.micrometer.core.instrument.Gauge; +import io.micrometer.core.instrument.MeterRegistry; +import io.micrometer.core.instrument.simple.SimpleMeterRegistry; +import org.junit.Test; +import org.junit.runner.RunWith; + +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.actuate.autoconfigure.health.HealthIndicatorAutoConfiguration; +import org.springframework.boot.actuate.autoconfigure.metrics.MetricsAutoConfiguration; +import org.springframework.boot.actuate.health.Health; +import org.springframework.boot.actuate.health.HealthIndicator; +import org.springframework.boot.autoconfigure.ImportAutoConfiguration; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.context.annotation.Import; +import org.springframework.test.context.junit4.SpringRunner; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * Tests for {@link MetricsHealthMicrometerExportExample}. + * + * @author Phillip Webb + */ +@RunWith(SpringRunner.class) +@SpringBootTest +public class MetricsHealthMicrometerExportExampleTests { + + @Autowired + private MeterRegistry registry; + + @Test + public void registryExportsHealth() throws Exception { + Gauge gauge = this.registry.get("health").gauge(); + assertThat(gauge.value()).isEqualTo(2); + } + + @Configuration + @Import(MetricsHealthMicrometerExportExample.HealthMetricsConfiguration.class) + @ImportAutoConfiguration(classes = { HealthIndicatorAutoConfiguration.class, MetricsAutoConfiguration.class }) + public static class Config { + + @Bean + public MetricsHealthMicrometerExportExample example() { + return new MetricsHealthMicrometerExportExample(); + } + + @Bean + public SimpleMeterRegistry simpleMeterRegistry() { + return new SimpleMeterRegistry(); + } + + @Bean + public HealthIndicator outOfService() { + return () -> new Health.Builder().outOfService().build(); + } + + } + +}