Adds TracingCustomizer and HttpTracingCustomizer

brave/src/main/java/brave/TracingCustomizer.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2013-2019 The OpenZipkin 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
+ *
+ * http://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 brave;
+
+import brave.handler.FinishedSpanHandler;
+import zipkin2.reporter.Reporter;
+
+/**
+ * This allows configuration plugins to collaborate on building an instance of {@link Tracing}.
+ *
+ * <p>For example a customizer can configure {@link Tracing.Builder#addFinishedSpanHandler(FinishedSpanHandler)
+ * finished span handlers} without having to also configure {@link Tracing.Builder#spanReporter(Reporter)
+ * span reporting}.
+ *
+ * <h3>Integration examples</h3>
+ *
+ * <p>In practice, a dependency injection tool applies a collection of these instances prior to
+ * {@link Tracing.Builder#build() building the tracing instance}. For example, an injected {@code
+ * List<TracingCustomizer>} parameter to a provider of {@link Tracing}.
+ *
+ * <p>Here are some examples, in alphabetical order:
+ * <pre><ul>
+ *   <li><a href="https://dagger.dev/multibindings.html">Dagger Set Multibindings</a></li>
+ *   <li><a href="http://google.github.io/guice/api-docs/latest/javadoc/com/google/inject/multibindings/Multibinder.html">Guice Set Multibinder</a></li>
+ *   <li><a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-autowired-annotation">Spring Autowired Collections</a></li>
+ * </ul></pre>
+ *
+ * @since 5.7
+ */
+public interface TracingCustomizer {
+  void customize(Tracing.Builder builder);
+}

instrumentation/http/src/main/java/brave/http/HttpTracingCustomizer.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2013-2019 The OpenZipkin 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
+ *
+ * http://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 brave.http;
+
+import brave.Tracing;
+import brave.TracingCustomizer;
+
+/**
+ * This allows configuration plugins to collaborate on building an instance of {@link HttpTracing}.
+ *
+ * <p>For example, a customizer can setup {@link HttpTracing.Builder#clientParser(HttpClientParser)
+ * http parsers} without a reference to the {@link HttpTracing.Builder#Builder(Tracing) tracing
+ * component}.
+ *
+ * <p>This also allows one object to customize both {@link Tracing}, via {@link TracingCustomizer},
+ * and the http layer {@link HttpTracing}, by implementing both customizer interfaces.
+ *
+ * <h3>Integration examples</h3>
+ *
+ * <p>In practice, a dependency injection tool applies a collection of these instances prior to
+ * {@link HttpTracing.Builder#build() building the tracing instance}. For example, an injected
+ * {@code List<HttpTracingCustomizer>} parameter to a provider of {@link HttpTracing}.
+ *
+ * <p>Here are some examples, in alphabetical order:
+ * <pre><ul>
+ *   <li><a href="https://dagger.dev/multibindings.html">Dagger Set Multibindings</a></li>
+ *   <li><a href="http://google.github.io/guice/api-docs/latest/javadoc/com/google/inject/multibindings/Multibinder.html">Guice Set Multibinder</a></li>
+ *   <li><a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-autowired-annotation">Spring Autowired Collections</a></li>
+ * </ul></pre>
+ *
+ * @see TracingCustomizer
+ * @since 5.7
+ */
+public interface HttpTracingCustomizer {
+  void customize(HttpTracing.Builder builder);
+}

spring-beans/src/main/java/brave/spring/beans/HttpTracingFactoryBean.java

@@ -18,6 +18,8 @@
 import brave.http.HttpSampler;
 import brave.http.HttpServerParser;
 import brave.http.HttpTracing;
+import brave.http.HttpTracingCustomizer;
+import java.util.List;
 import org.springframework.beans.factory.FactoryBean;
 
 /** Spring XML config does not support chained builders. This converts accordingly */
@@ -28,13 +30,17 @@ public class HttpTracingFactoryBean implements FactoryBean {
   HttpServerParser serverParser;
   HttpSampler clientSampler;
   HttpSampler serverSampler;
+  List<HttpTracingCustomizer> customizers;
 
   @Override public HttpTracing getObject() {
     HttpTracing.Builder builder = HttpTracing.newBuilder(tracing);
     if (clientParser != null) builder.clientParser(clientParser);
     if (serverParser != null) builder.serverParser(serverParser);
     if (clientSampler != null) builder.clientSampler(clientSampler);
     if (serverSampler != null) builder.serverSampler(serverSampler);
+    if (customizers != null) {
+      for (HttpTracingCustomizer customizer : customizers) customizer.customize(builder);
+    }
     return builder.build();
   }
 
@@ -65,4 +71,8 @@ public void setClientSampler(HttpSampler clientSampler) {
   public void setServerSampler(HttpSampler serverSampler) {
     this.serverSampler = serverSampler;
   }
+
+  public void setCustomizers(List<HttpTracingCustomizer> customizers) {
+    this.customizers = customizers;
+  }
 }

spring-beans/src/main/java/brave/spring/beans/TracingFactoryBean.java

@@ -16,6 +16,7 @@
 import brave.Clock;
 import brave.ErrorParser;
 import brave.Tracing;
+import brave.TracingCustomizer;
 import brave.handler.FinishedSpanHandler;
 import brave.propagation.CurrentTraceContext;
 import brave.propagation.Propagation;
@@ -40,6 +41,7 @@ public class TracingFactoryBean extends AbstractFactoryBean {
   Propagation.Factory propagationFactory;
   Boolean traceId128Bit;
   Boolean supportsJoin;
+  List<TracingCustomizer> customizers;
 
   @Override protected Tracing createInstance() {
     Tracing.Builder builder = Tracing.newBuilder();
@@ -59,6 +61,9 @@ public class TracingFactoryBean extends AbstractFactoryBean {
     if (propagationFactory != null) builder.propagationFactory(propagationFactory);
     if (traceId128Bit != null) builder.traceId128Bit(traceId128Bit);
     if (supportsJoin != null) builder.supportsJoin(supportsJoin);
+    if (customizers != null) {
+      for (TracingCustomizer customizer : customizers) customizer.customize(builder);
+    }
     return builder.build();
   }
 
@@ -114,10 +119,6 @@ public void setCurrentTraceContext(CurrentTraceContext currentTraceContext) {
     this.currentTraceContext = currentTraceContext;
   }
 
-  public Propagation.Factory getPropagationFactory() {
-    return propagationFactory;
-  }
-
   public void setPropagationFactory(Propagation.Factory propagationFactory) {
     this.propagationFactory = propagationFactory;
   }
@@ -126,11 +127,11 @@ public void setTraceId128Bit(boolean traceId128Bit) {
     this.traceId128Bit = traceId128Bit;
   }
 
-  public Boolean getSupportsJoin() {
-    return supportsJoin;
-  }
-
   public void setSupportsJoin(Boolean supportsJoin) {
     this.supportsJoin = supportsJoin;
   }
+
+  public void setCustomizers(List<TracingCustomizer> customizers) {
+    this.customizers = customizers;
+  }
 }

spring-beans/src/test/java/brave/spring/beans/CurrentTraceContextFactoryBeanTest.java

@@ -31,7 +31,9 @@ public class CurrentTraceContextFactoryBeanTest {
     context = new XmlBeans(""
       + "<bean id=\"currentTraceContext\" class=\"brave.spring.beans.CurrentTraceContextFactoryBean\">\n"
       + "  <property name=\"scopeDecorators\">\n"
-      + "    <bean class=\"brave.propagation.StrictScopeDecorator\" factory-method=\"create\"/>\n"
+      + "    <list>\n"
+      + "      <bean class=\"brave.propagation.StrictScopeDecorator\" factory-method=\"create\"/>\n"
+      + "    </list>\n"
       + "  </property>"
       + "</bean>"
     );

spring-beans/src/test/java/brave/spring/beans/HttpTracingFactoryBeanTest.java

@@ -14,15 +14,19 @@
 package brave.spring.beans;
 
 import brave.Tracing;
+import brave.TracingCustomizer;
 import brave.http.HttpClientParser;
 import brave.http.HttpSampler;
 import brave.http.HttpServerParser;
 import brave.http.HttpTracing;
+import brave.http.HttpTracingCustomizer;
 import org.junit.After;
 import org.junit.Test;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
 
 public class HttpTracingFactoryBeanTest {
 
@@ -117,4 +121,28 @@ public class HttpTracingFactoryBeanTest {
       .extracting("serverSampler")
       .isEqualTo(HttpSampler.NEVER_SAMPLE);
   }
+
+  public static final HttpTracingCustomizer CUSTOMIZER_ONE = mock(HttpTracingCustomizer.class);
+  public static final HttpTracingCustomizer CUSTOMIZER_TWO = mock(HttpTracingCustomizer.class);
+
+  @Test public void customizers() {
+    context = new XmlBeans(""
+      + "<bean id=\"httpTracing\" class=\"brave.spring.beans.HttpTracingFactoryBean\">\n"
+      + "  <property name=\"tracing\">\n"
+      + "    <util:constant static-field=\"" + getClass().getName() + ".TRACING\"/>\n"
+      + "  </property>\n"
+      + "  <property name=\"customizers\">\n"
+      + "    <list>\n"
+      + "      <util:constant static-field=\"" + getClass().getName() + ".CUSTOMIZER_ONE\"/>\n"
+      + "      <util:constant static-field=\"" + getClass().getName() + ".CUSTOMIZER_TWO\"/>\n"
+      + "    </list>\n"
+      + "  </property>"
+      + "</bean>"
+    );
+
+    context.getBean("httpTracing", HttpTracing.class);
+
+    verify(CUSTOMIZER_ONE).customize(any(HttpTracing.Builder.class));
+    verify(CUSTOMIZER_TWO).customize(any(HttpTracing.Builder.class));
+  }
 }

spring-beans/src/test/java/brave/spring/beans/TracingFactoryBeanTest.java

@@ -16,17 +16,22 @@
 import brave.Clock;
 import brave.ErrorParser;
 import brave.Tracing;
+import brave.TracingCustomizer;
 import brave.handler.FinishedSpanHandler;
+import brave.propagation.CurrentTraceContext;
 import brave.propagation.ExtraFieldPropagation;
 import brave.propagation.ThreadLocalCurrentTraceContext;
 import brave.sampler.Sampler;
+import java.util.List;
 import org.junit.After;
 import org.junit.Test;
 import zipkin2.Endpoint;
 import zipkin2.reporter.Reporter;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
 
 public class TracingFactoryBeanTest {
   public static final Clock CLOCK = mock(Clock.class);
@@ -243,4 +248,25 @@ public class TracingFactoryBeanTest {
       .extracting("tracer.supportsJoin")
       .isEqualTo(true);
   }
+
+  public static final TracingCustomizer CUSTOMIZER_ONE = mock(TracingCustomizer.class);
+  public static final TracingCustomizer CUSTOMIZER_TWO = mock(TracingCustomizer.class);
+
+  @Test public void customizers() {
+    context = new XmlBeans(""
+      + "<bean id=\"tracing\" class=\"brave.spring.beans.TracingFactoryBean\">\n"
+      + "  <property name=\"customizers\">\n"
+      + "    <list>\n"
+      + "      <util:constant static-field=\"" + getClass().getName() + ".CUSTOMIZER_ONE\"/>\n"
+      + "      <util:constant static-field=\"" + getClass().getName() + ".CUSTOMIZER_TWO\"/>\n"
+      + "    </list>\n"
+      + "  </property>"
+      + "</bean>"
+    );
+
+    context.getBean("tracing", Tracing.class);
+
+    verify(CUSTOMIZER_ONE).customize(any(Tracing.Builder.class));
+    verify(CUSTOMIZER_TWO).customize(any(Tracing.Builder.class));
+  }
 }