Recommend the use of a MeterBinder when a metric depends on a bean

Closes gh-19557

Author: wilkinsona

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

@@ -1309,14 +1309,7 @@ You can apply customizations to particular registry implementations by being mor
 	}
 ----
 
-With that setup in place you can inject `MeterRegistry` in your components and register metrics:
-
-[source,java,indent=0]
-----
-include::{code-examples}/actuate/metrics/SampleBean.java[tag=example]
-----
-
-Spring Boot also <<production-ready-metrics-meter,configures built-in instrumentation>> (i.e. `MeterBinder` implementations) that you can control via configuration or dedicated annotation markers.
+Spring Boot also <<production-ready-metrics-meter,configures built-in instrumentation>> that you can control via configuration or dedicated annotation markers.
 
 
 
@@ -1916,8 +1909,16 @@ To register custom metrics, inject `MeterRegistry` into your component, as shown
 include::{code-examples}/actuate/metrics/MetricsMeterRegistryInjectionExample.java[tag=component]
 ----
 
-If you find that you repeatedly instrument a suite of metrics across components or applications, you may encapsulate this suite in a `MeterBinder` implementation.
+If you metrics depend on other beans, it is recommend that you use a `MeterBinder` to register them, as shown in the following example:
+
+[source,java,indent=0]
+----
+include::{code-examples}/actuate/metrics/SampleMeterBinderConfiguration.java[tag=example]
+----
+
+Using a `MeterBinder` ensures that the correct dependency relationships are set up and that the bean is available when the metric's value is retrieved.
 By default, metrics from all `MeterBinder` beans will be automatically bound to the Spring-managed `MeterRegistry`.
+A `MeterBinder` implementation can also be useful if you find that you repeatedly instrument a suite of metrics across components or applications..
 
 
 

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/metrics/SampleBean.java renamed to spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/metrics/SampleMeterBinderConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * 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.
@@ -16,30 +16,31 @@
 
 package org.springframework.boot.docs.actuate.metrics;
 
-import io.micrometer.core.instrument.Counter;
-import io.micrometer.core.instrument.MeterRegistry;
+import io.micrometer.core.instrument.Gauge;
+import io.micrometer.core.instrument.binder.MeterBinder;
 
-import org.springframework.stereotype.Component;
+import org.springframework.context.annotation.Bean;
 
 /**
- * Example to show manual usage of {@link MeterRegistry}.
+ * Example to show configuration of a custom {@link MeterBinder}.
  *
- * @author Stephane Nicoll
+ * @author Andy Wilkinson
  */
-// tag::example[]
-@Component
-public class SampleBean {
+public class SampleMeterBinderConfiguration {
 
-	private final Counter counter;
-
-	public SampleBean(MeterRegistry registry) {
-		this.counter = registry.counter("received.messages");
+	// tag::example[]
+	@Bean
+	MeterBinder queueSize(Queue queue) {
+		return (registry) -> Gauge.builder("queueSize", queue::size).register(registry);
 	}
+	// end::example[]
+
+	static class Queue {
+
+		int size() {
+			return 5;
+		}
 
-	public void handleMessage(String message) {
-		this.counter.increment();
-		// handle message implementation
 	}
 
 }
-// end::example[]