Managing spans with annotations (#526)

The main arguments for these features are

* api-agnostic means to collaborate with a span
    - use of annotations allows users to add to a span with no library dependency on a span api.
    This allows Sleuth to change its core api less impact to user code.
* reduced surface area for basic span operations.
    - without this feature one has to use the span api, which has lifecycle commands that
    could be used incorrectly. By only exposing scope, tag and log functionality, users can
    collaborate without accidentally breaking span lifecycle.
* collaboration with runtime generated code
    - with libraries such as Spring Data / Feign the implementations of interfaces are generated
    at runtime thus span wrapping of objects was tedious. Now you can provide annotations
     over interfaces and arguments of those interfaces

This PR is an adoption of @Koizumi85 work started here - https://github.com/Koizumi85/spring-cloud-sleuth-annotation

fixes #182

benchmarks/src/main/java/org/springframework/cloud/sleuth/benchmarks/app/SleuthBenchmarkingSpringApp.java

@@ -26,6 +26,7 @@ import javax.annotation.PreDestroy;
 
 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.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
@@ -33,8 +34,15 @@ import org.springframework.boot.context.embedded.EmbeddedServletContainerFactory
 import org.springframework.boot.context.embedded.EmbeddedServletContainerInitializedEvent;
 import org.springframework.boot.context.embedded.tomcat.TomcatEmbeddedServletContainerFactory;
 import org.springframework.cloud.sleuth.Sampler;
+import org.springframework.cloud.sleuth.Span;
+import org.springframework.cloud.sleuth.Tracer;
+import org.springframework.cloud.sleuth.annotation.ContinueSpan;
+import org.springframework.cloud.sleuth.annotation.NewSpan;
+import org.springframework.cloud.sleuth.annotation.SpanTag;
 import org.springframework.cloud.sleuth.sampler.AlwaysSampler;
+import org.springframework.cloud.sleuth.util.ArrayListSpanAccumulator;
 import org.springframework.context.ApplicationListener;
+import org.springframework.context.ConfigurableApplicationContext;
 import org.springframework.context.annotation.Bean;
 import org.springframework.scheduling.annotation.Async;
 import org.springframework.scheduling.annotation.EnableAsync;
@@ -57,6 +65,9 @@ public class SleuthBenchmarkingSpringApp implements
 
 	public int port;
 
+	@Autowired(required = false) Tracer tracer;
+	@Autowired AClass aClass;
+
 	@RequestMapping("/foo")
 	public String foo() {
 		return "foo";
@@ -77,6 +88,14 @@ public class SleuthBenchmarkingSpringApp implements
 		return this.pool.submit(() -> "async");
 	}
 
+	public String manualSpan() {
+		return this.aClass.manualSpan();
+	}
+
+	public String newSpan() {
+		return this.aClass.newSpan();
+	}
+
 	@Override
 	public void onApplicationEvent(EmbeddedServletContainerInitializedEvent event) {
 		this.port = event.getEmbeddedServletContainer().getPort();
@@ -93,11 +112,18 @@ public class SleuthBenchmarkingSpringApp implements
 		this.pool.shutdownNow();
 	}
 
-	@Bean
-	public Sampler alwaysSampler() {
+ 	@Bean Sampler alwaysSampler() {
 		return new AlwaysSampler();
 	}
 
+	@Bean AnotherClass anotherClass() {
+		return new AnotherClass(this.tracer);
+	}
+
+	@Bean AClass aClass() {
+		return new AClass(this.tracer, anotherClass());
+	}
+
 	public ExecutorService getPool() {
 		return this.pool;
 	}
@@ -106,3 +132,48 @@ public class SleuthBenchmarkingSpringApp implements
 		SpringApplication.run(SleuthBenchmarkingSpringApp.class, args);
 	}
 }
+class AClass {
+	private final Tracer tracer;
+	private final AnotherClass anotherClass;
+
+	AClass(Tracer tracer, AnotherClass anotherClass) {
+		this.tracer = tracer;
+		this.anotherClass = anotherClass;
+	}
+
+	public String manualSpan() {
+		Span manual = this.tracer.createSpan("span-name");
+		try {
+			return this.anotherClass.continuedSpan();
+		} finally {
+			this.tracer.close(manual);
+		}
+	}
+
+	@NewSpan
+	public String newSpan() {
+		return this.anotherClass.continuedAnnotation("bar");
+	}
+}
+
+class AnotherClass {
+	private final Tracer tracer;
+
+	AnotherClass(Tracer tracer) {
+		this.tracer = tracer;
+	}
+
+	@ContinueSpan(log = "continuedspan")
+	public String continuedAnnotation(@SpanTag("foo") String tagValue) {
+		return "continued";
+	}
+
+	public String continuedSpan() {
+		Span continuedSpan = this.tracer.continueSpan(this.tracer.getCurrentSpan());
+		this.tracer.addTag("foo", "bar");
+		continuedSpan.logEvent("continuedspan.before");
+		String response = "continued";
+		continuedSpan.logEvent("continuedspan.after");
+		return response;
+	}
+}

benchmarks/src/main/java/org/springframework/cloud/sleuth/benchmarks/jmh/benchmarks/AnnotationBenchmarks.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2013-2016 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.benchmarks.jmh.benchmarks;
+
+import java.util.concurrent.TimeUnit;
+
+import org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Fork;
+import org.openjdk.jmh.annotations.Measurement;
+import org.openjdk.jmh.annotations.Mode;
+import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.annotations.Scope;
+import org.openjdk.jmh.annotations.Setup;
+import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.annotations.TearDown;
+import org.openjdk.jmh.annotations.Threads;
+import org.openjdk.jmh.annotations.Warmup;
+import org.springframework.boot.SpringApplication;
+import org.springframework.cloud.sleuth.benchmarks.app.SleuthBenchmarkingSpringApp;
+import org.springframework.cloud.sleuth.util.ExceptionUtils;
+import org.springframework.context.ConfigurableApplicationContext;
+
+import static org.assertj.core.api.BDDAssertions.then;
+
+@Measurement(iterations = 5)
+@Warmup(iterations = 10)
+@Fork(3)
+@BenchmarkMode(Mode.SampleTime)
+@OutputTimeUnit(TimeUnit.MICROSECONDS)
+@Threads(Threads.MAX)
+public class AnnotationBenchmarks {
+
+	@State(Scope.Benchmark)
+	public static class BenchmarkContext {
+		volatile ConfigurableApplicationContext withSleuth;
+		volatile SleuthBenchmarkingSpringApp sleuth;
+
+		@Setup public void setup() {
+			this.withSleuth = new SpringApplication(
+					SleuthBenchmarkingSpringApp.class)
+					.run("--spring.jmx.enabled=false",
+							"--spring.application.name=withSleuth");
+			this.sleuth = this.withSleuth.getBean(
+					SleuthBenchmarkingSpringApp.class);
+		}
+
+		@TearDown public void clean() {
+			this.sleuth.clean();
+			this.withSleuth.close();
+		}
+	}
+
+	@Benchmark
+	public void manuallyCreatedSpans(BenchmarkContext context)
+			throws Exception {
+		then(context.sleuth.manualSpan()).isEqualTo("continued");
+		then(ExceptionUtils.getLastException()).isNull();
+	}
+
+	@Benchmark
+	public void spanCreatedWithAnnotations(BenchmarkContext context)
+			throws Exception {
+		then(context.sleuth.newSpan()).isEqualTo("continued");
+		then(ExceptionUtils.getLastException()).isNull();
+	}
+}

benchmarks/src/main/java/org/springframework/cloud/sleuth/benchmarks/jmh/benchmarks/HttpFilterBenchmarks.java

@@ -18,7 +18,6 @@ package org.springframework.cloud.sleuth.benchmarks.jmh.benchmarks;
 import java.io.IOException;
 import java.util.concurrent.Callable;
 import java.util.concurrent.TimeUnit;
-
 import javax.servlet.Filter;
 import javax.servlet.FilterChain;
 import javax.servlet.FilterConfig;

benchmarks/src/main/java/org/springframework/cloud/sleuth/benchmarks/jmh/benchmarks/RestTemplateBenchmark.java

@@ -18,7 +18,6 @@ package org.springframework.cloud.sleuth.benchmarks.jmh.benchmarks;
 import java.io.IOException;
 import java.util.Collections;
 import java.util.concurrent.TimeUnit;
-
 import javax.servlet.ServletException;
 
 import org.openjdk.jmh.annotations.Benchmark;