Added SpanFilter

docs/src/main/asciidoc/spring-cloud-sleuth.adoc

@@ -947,6 +947,25 @@ object, you will have to create a bean of `zipkin2.reporter.Sender` type.
 	}
 ----
 
+== Filtering out spans to report
+
+There are cases when you might not want to report a given span e.g. to Zipkin.
+In order to filter out spans, you should implement the `SpanFilter` interface
+which returns `true` if a span should be NOT be reported and `false` otherwise. Example:
+
+[source,java]
+----
+	@Bean SpanFilter mySpanFilter() {
+		return (span) -> {
+		    // true - if we want span NOT to be reported
+		    // false - otherwise
+		};
+	}
+----
+
+You can have multiple `SpanFilter`s and the whole list of them will be applied
+against the span that is to be reported.
+
 == Zipkin Stream Span Consumer
 
 IMPORTANT: We recommend using Zipkin's native support for message-based span sending.

spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanFilter.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2013-2018 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
+ *
+ *      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 org.springframework.cloud.sleuth;
+
+import zipkin2.Span;
+
+/**
+ * Adds ability to filter out spans that shouldn't be reported
+ *
+ * <b>IMPORTANT</b> - DO NOT apply filtering to child spans of an RPC
+ * call.
+ *
+ * @author Marcin Grzejszczak
+ * @since 2.1.0
+ */
+public interface SpanFilter {
+
+	/**
+	 * @param span - span to be reported
+	 * @return - {@code true} if span is to be rejected, {@code false} otherwise
+	 */
+	boolean reject(Span span);
+}

spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceAutoConfiguration.java

@@ -29,13 +29,16 @@
 import brave.propagation.ExtraFieldPropagation;
 import brave.propagation.Propagation;
 import brave.sampler.Sampler;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.cloud.sleuth.DefaultSpanNamer;
 import org.springframework.cloud.sleuth.SpanAdjuster;
+import org.springframework.cloud.sleuth.SpanFilter;
 import org.springframework.cloud.sleuth.SpanNamer;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -55,9 +58,12 @@
 @EnableConfigurationProperties(SleuthProperties.class)
 public class TraceAutoConfiguration {
 
+	private static final Log log = LogFactory.getLog(TraceAutoConfiguration.class);
+
 	public static final String TRACER_BEAN_NAME = "tracer";
 
 	@Autowired(required = false) List<SpanAdjuster> spanAdjusters = new ArrayList<>();
+	@Autowired(required = false) List<SpanFilter> spanFilters = new ArrayList<>();
 
 	@Bean
 	@ConditionalOnMissingBean
@@ -84,14 +90,26 @@ Tracing tracing(@Value("${spring.zipkin.service.name:${spring.application.name:d
 
 	private Reporter<zipkin2.Span> adjustedReporter(Reporter<zipkin2.Span> delegate) {
 		return span -> {
-			Span spanToAdjust = span;
-			for (SpanAdjuster spanAdjuster : this.spanAdjusters) {
-				spanToAdjust = spanAdjuster.adjust(spanToAdjust);
+			Span spanToAdjust = spanToAdjust(span);
+			if (this.spanFilters.stream()
+					.anyMatch(filter -> filter.reject(spanToAdjust))) {
+				if (log.isDebugEnabled()) {
+					log.debug("Span [" + spanToAdjust + "] filtered and will not be reported");
+				}
+			} else {
+				delegate.report(spanToAdjust);
 			}
-			delegate.report(spanToAdjust);
 		};
 	}
 
+	private Span spanToAdjust(Span span) {
+		Span spanToAdjust = span;
+		for (SpanAdjuster spanAdjuster : this.spanAdjusters) {
+			spanToAdjust = spanAdjuster.adjust(spanToAdjust);
+		}
+		return spanToAdjust;
+	}
+
 	@Bean(name = TRACER_BEAN_NAME)
 	@ConditionalOnMissingBean
 	Tracer tracer(Tracing tracing) {
@@ -109,6 +127,11 @@ Sampler sleuthTraceSampler() {
 		return new DefaultSpanNamer();
 	}
 
+	@Bean
+	@ConditionalOnMissingBean SpanFilter noOpSpanFilter() {
+		return (span) -> false;
+	}
+
 	@Bean
 	@ConditionalOnMissingBean
 	Propagation.Factory sleuthPropagation(SleuthProperties sleuthProperties) {

spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/TraceFilterIntegrationTests.java

@@ -41,6 +41,7 @@
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.actuate.autoconfigure.web.server.ManagementServerProperties;
 import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.cloud.sleuth.SpanFilter;
 import org.springframework.cloud.sleuth.instrument.DefaultTestAutoConfiguration;
 import org.springframework.cloud.sleuth.util.ArrayListSpanReporter;
 import org.springframework.cloud.sleuth.util.SpanUtil;
@@ -81,12 +82,14 @@ public class TraceFilterIntegrationTests extends AbstractMvcIntegrationTest {
 	@Autowired MyFilter myFilter;
 	@Autowired ArrayListSpanReporter reporter;
 	@Autowired Tracer tracer;
+	@Autowired MySpanFilter mySpanFilter;
 
 	private static Span span;
 
 	@Before
 	@After
-	public void clearSpans() {
+	public void clear() {
+		this.mySpanFilter.disableAll = false;
 		this.reporter.clear();
 	}
 
@@ -224,6 +227,18 @@ public void should_return_custom_response_headers_when_custom_trace_filter_gets_
 		then(this.reporter.getSpans().get(0).tags()).containsEntry("custom", "tag");
 	}
 
+	@Test
+	public void should_filter_out_a_span_and_not_report_it() throws Exception {
+		Long expectedTraceId = new Random().nextLong();
+		this.mySpanFilter.disableAll = true;
+		this.mySpanFilter.wasCalled = false;
+
+		whenSentPongWithTraceId(expectedTraceId);
+
+		then(this.mySpanFilter.wasCalled).isTrue();
+		then(this.reporter.getSpans()).isEmpty();
+	}
+
 	@Override
 	protected void configureMockMvcBuilder(DefaultMockMvcBuilder mockMvcBuilder) {
 		mockMvcBuilder.addFilters(this.traceFilter, this.myFilter);
@@ -239,6 +254,10 @@ private MvcResult whenSentPingWithTraceId(Long passedTraceId) throws Exception {
 		return sendPingWithTraceId(TRACE_ID_NAME, passedTraceId);
 	}
 
+	private MvcResult whenSentPongWithTraceId(Long passedTraceId) throws Exception {
+		return sendPingWithTraceId(TRACE_ID_NAME, passedTraceId);
+	}
+
 	private MvcResult whenSentInfoWithTraceId(Long passedTraceId) throws Exception {
 		return sendRequestWithTraceId("/additionalContextPath/info", TRACE_ID_NAME,
 				passedTraceId);
@@ -265,6 +284,11 @@ private MvcResult sendPingWithTraceId(String headerName, Long traceId)
 		return sendRequestWithTraceId("/ping", headerName, traceId);
 	}
 
+	private MvcResult sendPongWithTraceId(String headerName, Long traceId)
+			throws Exception {
+		return sendRequestWithTraceId("/pong", headerName, traceId);
+	}
+
 	private MvcResult sendDeferredWithTraceId(String headerName, Long traceId)
 			throws Exception {
 		return sendRequestWithTraceId("/deferred", headerName, traceId);
@@ -319,6 +343,13 @@ public String ping() {
 				return "ping";
 			}
 
+			@RequestMapping("/pong")
+			public String pong() {
+				logger.info("ping");
+				span = this.tracer.currentSpan();
+				return "pong";
+			}
+
 			@RequestMapping("/throwsException")
 			public void throwsException() {
 				throw new RuntimeException();
@@ -352,6 +383,10 @@ ManagementServerProperties managementServerProperties() {
 			}
 		}
 
+		@Bean SpanFilter spanFilter() {
+			return new MySpanFilter();
+		}
+
 		@Bean
 		public ArrayListSpanReporter testSpanReporter() {
 			return new ArrayListSpanReporter();
@@ -396,4 +431,15 @@ class MyFilter extends GenericFilterBean {
 		chain.doFilter(request, response);
 	}
 }
-//end::response_headers[]
+//end::response_headers[]
+
+class MySpanFilter implements SpanFilter {
+
+	boolean disableAll = false;
+	boolean wasCalled = false;
+
+	@Override public boolean reject(zipkin2.Span span) {
+		this.wasCalled = true;
+		return this.disableAll;
+	}
+}