diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/DefaultSpanNamer.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/DefaultSpanNamer.java index 9fdb34f9b..0aa6043e4 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/DefaultSpanNamer.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/DefaultSpanNamer.java @@ -19,7 +19,7 @@ package org.springframework.cloud.sleuth; import org.springframework.core.annotation.AnnotationUtils; /** - * Default implementation of SpanNamer that tries to get the Span name as follows: + * Default implementation of SpanNamer that tries to get the span name as follows: * *
  • * @@ -28,9 +28,10 @@ import org.springframework.core.annotation.AnnotationUtils; * *
    • * - * @see org.springframework.cloud.sleuth.SpanName - * * @author Marcin Grzejszczak + * @since 1.0.0 + * + * @see org.springframework.cloud.sleuth.SpanName */ public class DefaultSpanNamer implements SpanNamer { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Log.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Log.java index a6b05f207..c958ee781 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Log.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Log.java @@ -17,7 +17,11 @@ package org.springframework.cloud.sleuth; /** + * Represents an event in time associated with a span. Every span has zero or more Logs, + * each of which being a timestamped event name. + * * @author Spencer Gibb + * @since 1.0.0 */ public class Log { /** @@ -26,22 +30,16 @@ public class Log { private final long timestamp; /** - * Event (if not null) should be the stable name of some notable moment in the lifetime of a Span. - * For instance, a Span representing a browser page load might add an Event for each of the + * Event (if not null) should be the stable name of some notable moment in the lifetime of a span. + * For instance, a span representing a browser page load might add an Event for each of the * Performance.timing moments here: https://developer.mozilla.org/en-US/docs/Web/API/PerformanceTiming * *

    While it is not a formal requirement, Event strings will be most useful if they are *not* - * unique; rather, tracing systems should be able to use them to understand how two similar Spans + * unique; rather, tracing systems should be able to use them to understand how two similar spans * relate from an internal timing perspective. */ private final String event; - @SuppressWarnings("unused") - private Log() { - this.timestamp = 0; - this.event = null; - } - public Log(long timestamp, String event) { this.timestamp = timestamp; this.event = event; diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Sampler.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Sampler.java index 5c723db0b..e7a97592d 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Sampler.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Sampler.java @@ -18,10 +18,12 @@ package org.springframework.cloud.sleuth; /** * Extremely simple callback to determine the frequency that an action should be traced. + * + * @since 1.0.0 */ public interface Sampler { /** - * @param span the current span (or null if there is none) + * @return true if the span is not null and should be exported to the tracing system */ boolean isSampled(Span span); } diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Span.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Span.java index 04ceaaee5..445e26b12 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Span.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Span.java @@ -29,13 +29,25 @@ import org.springframework.util.StringUtils; /** * Class for gathering and reporting statistics about a block of execution. - *

    + *

    * Spans should form a directed acyclic graph structure. It should be possible to keep * following the parents of a span until you arrive at a span with no parents. - *

    + *

    + * Spans can be either annotated with tags or logs. + *

    + * An Annotation is used to record existence of an event in time. Below you can find some + * of the core annotations used to define the start and stop of a request: + *

    + *

    * * @author Spencer Gibb * @author Marcin Grzejszczak + * @since 1.0.0 */ /* * OpenTracing spans can affect the trace tree by creating children. In this way, they are @@ -186,7 +198,7 @@ public class Span { } /** - * Returns the saved span. The one that was "current" before this Span. + * Returns the saved span. The one that was "current" before this span. *

    * Might be null */ @@ -210,7 +222,7 @@ public class Span { * A pseudo-unique (random) number assigned to this span instance. *

    *

    - * The spanId is immutable and cannot be changed. It is safe to access this from + * The span id is immutable and cannot be changed. It is safe to access this from * multiple threads. */ public long getSpanId() { @@ -225,10 +237,9 @@ public class Span { } /** - * Return a unique id for the process from which this Span originated. + * Return a unique id for the process from which this span originated. *

    - *

    - * // TODO: Check when this is going to be null (cause it may be null) + * Might be null */ public String getProcessId() { return this.processId; diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanAccessor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanAccessor.java index 13c851967..19b2997a7 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanAccessor.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanAccessor.java @@ -22,7 +22,7 @@ package org.springframework.cloud.sleuth; * to specialized and cross-cutting instrumentation code). * * @author Dave Syer - * + * @since 1.0.0 */ public interface SpanAccessor { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanName.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanName.java index a7e2d75f1..e9ef5f3cb 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanName.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanName.java @@ -23,16 +23,40 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * - * Annotation to provide the name for the Span. You should annotate all your - * custom {@link java.lang.Runnable} or {@link java.util.concurrent.Callable} classes + * Annotation to provide the name for the span. You should annotate all your + * custom {@link java.lang.Runnable Runnable} or {@link java.util.concurrent.Callable Callable} classes * for the instrumentation logic to pick up how to name the span. + *

    * - * If you're using anonymous instances for those classes then you should override the - * {@code toString()} method. That way that value will be picked as a span name at - * runtime. + * Having for example the following code + * 

    {@code
+ *     @SpanName("custom-operation")
+ *     class CustomRunnable implements Runnable {
+ *         @Override
+ *         public void run() {
+ *          // latency of this method will be recorded in a span named "custom-operation"
+ *         }
+ *      }
+ * }
    + * + * Will result in creating a span with name {@code custom-operation}. + *

    + * + * When there's no @SpanName annotation, {@code toString} is used. Here's an + * example of the above, but via an anonymous instance. + * 

    {@code
+ *     return new Runnable() {
+ *          -- snip --
+ *
+ *          @Override
+ *          public String toString() {
+ *              return "custom-operation";
+ *          }
+ *     };
+ * }
    * * @author Marcin Grzejszczak + * @since 1.0.0 */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanNamer.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanNamer.java index 3dd2327bb..8da55acad 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanNamer.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/SpanNamer.java @@ -23,6 +23,7 @@ package org.springframework.cloud.sleuth; * the name of the span. * * @author Marcin Grzejszczak + * @since 1.0.0 */ public interface SpanNamer { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceCallable.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceCallable.java index f94f38566..487a9e253 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceCallable.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceCallable.java @@ -25,6 +25,7 @@ import java.util.concurrent.Callable; * * @author Spencer Gibb * @author Marcin Grzejszczak + * @since 1.0.0 */ public class TraceCallable implements Callable { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceKeys.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceKeys.java index d072414be..5c3ecd999 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceKeys.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceKeys.java @@ -45,6 +45,8 @@ import org.springframework.boot.context.properties.ConfigurationProperties; * Meanwhile, you have another system storing private data! The takeaway isn't never store * cookies, as there are valid cases for this. The takeaway is to be conscious about * what's you are storing. + * + * @since 1.0.0 */ @ConfigurationProperties("spring.sleuth.keys") public class TraceKeys { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceRunnable.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceRunnable.java index f18af615c..62ff17d51 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceRunnable.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/TraceRunnable.java @@ -23,9 +23,16 @@ package org.springframework.cloud.sleuth; * * @author Spencer Gibb * @author Marcin Grzejszczak + * @since 1.0.0 */ public class TraceRunnable implements Runnable { + /** + * Since we don't know the exact operation name we provide a default + * name for the Span + */ + private static final String DEFAULT_SPAN_NAME = "async"; + private final Tracer tracer; private final SpanNamer spanNamer; private final Runnable delegate; @@ -63,7 +70,7 @@ public class TraceRunnable implements Runnable { if (this.name != null) { return this.name; } - return this.spanNamer.name(this.delegate, "async"); + return this.spanNamer.name(this.delegate, DEFAULT_SPAN_NAME); } protected void close(Span span) { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Tracer.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Tracer.java index b312fc6e6..ec257cb13 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Tracer.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/Tracer.java @@ -21,28 +21,36 @@ import java.util.concurrent.Callable; /** * The TraceManager class is the primary way for instrumentation code (note user code) to * interact with the library. It provides methods to create and manipulate spans. + *

    * - * A 'Span' represents a length of time. It has many other attributes such as a name, ID, + * A 'span' represents a length of time. It has many other attributes such as a name, ID, * and even potentially a set of key/value strings attached to it. + *

    * * Each thread in your application has a single currently active currentSpan associated * with it. When this is non-null, it represents the current operation that the thread is - * doing. Spans are NOT thread-safe, and must never be used by multiple threads at once. - * With care, it is possible to safely pass a Span object between threads, but in most + * doing. spans are NOT thread-safe, and must never be used by multiple threads at once. + * With care, it is possible to safely pass a span object between threads, but in most * cases this is not necessary. + *

    * - * The 'startTrace' method in this class starts a new span. - * - *

  • Create a TraceSpan object to manage the new Span.
    • + * Most crucial methods in terms of span lifecycle are: + * * - * The 'joinTrace' method creates a new Span which has this thread's currentSpan as one of its parents - * * Closing a TraceScope does a few things: * + * + * @since 1.0.0 */ public interface Tracer extends SpanAccessor { @@ -72,25 +80,44 @@ public interface Tracer extends SpanAccessor { /** * Start a new span if the sampler allows it or if we are already tracing in this * thread. A sampler can be used to limit the number of traces created. - * @param name the name of the span + * + * @param name the name of the span * @param sampler a sampler to decide whether to create the span or not */ Span startTrace(String name, Sampler sampler); /** - * Pick up an existing span from another thread. + * Contributes to a span started in another thread. The returned span shares + * mutable state with the input. */ Span continueSpan(Span span); /** * Adds a tag to the current span if tracing is currently on. + *

    + * Every span may also have zero or more key/value Tags, which do not have + * timestamps and simply annotate the spans. + * + * Check {@link TraceKeys} for examples of most common tag keys */ void addTag(String key, String value); /** * Remove this span from the current thread, but don't stop it yet or send it for * collection. This is useful if the span object is then passed to another thread for - * use with Span.continueTrace(). + * use with {@link Tracer#continueSpan(Span)}. + *

    + * Example of usage: + * 

    {@code
+	 *     // Span "A" was present in thread "X". Let's assume that we're in thread "Y" to which span "A" got passed
+	 *     Span continuedSpan = tracer.continueSpan(spanA);
+	 *     // Now span "A" got continued in thread "Y".
+	 *     ... // Some work is done... state of span "A" could get mutated
+	 *     Span previouslyStoredSpan = tracer.detach(continuedSpan);
+	 *     // Span "A" got removed from the thread Y but it wasn't yet sent for collection.
+	 *     // Additional work can be done on span "A" in thread "X" and finally it can get closed and sent for collection
+	 *     tracer.close(spanA);
+	 * }
    * * @return the saved trace if there was one before the trace started (null otherwise) */ @@ -104,7 +131,15 @@ public interface Tracer extends SpanAccessor { */ Span close(Span span); + /** + * Returns a wrapped {@link Callable} which will be recorded as a span + * in the current trace. + */ Callable wrap(Callable callable); + /** + * Returns a wrapped {@link Runnable} which will be recorded as a span + * in the current trace. + */ Runnable wrap(Runnable runnable); } diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceAutoConfiguration.java index 9daf8bb2e..77042e7ea 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceAutoConfiguration.java @@ -24,8 +24,8 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties import org.springframework.cloud.sleuth.DefaultSpanNamer; import org.springframework.cloud.sleuth.Sampler; import org.springframework.cloud.sleuth.SpanNamer; -import org.springframework.cloud.sleuth.Tracer; import org.springframework.cloud.sleuth.TraceKeys; +import org.springframework.cloud.sleuth.Tracer; import org.springframework.cloud.sleuth.sampler.NeverSampler; import org.springframework.cloud.sleuth.trace.DefaultTracer; import org.springframework.context.ApplicationEventPublisher; @@ -33,7 +33,12 @@ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; /** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * to enable tracing via Spring Cloud Sleuth. + * * @author Spencer Gibb + * @author Marcin Grzejszczak + * @since 1.0.0 */ @Configuration @ConditionalOnProperty(value="spring.sleuth.enabled", matchIfMissing=true) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceEnvironmentPostProcessor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceEnvironmentPostProcessor.java index e2692405f..2760f7b86 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceEnvironmentPostProcessor.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/TraceEnvironmentPostProcessor.java @@ -27,10 +27,18 @@ import org.springframework.core.env.MutablePropertySources; import org.springframework.core.env.PropertySource; /** - * Adds a default logging pattern level that prints trace infotmation + * Adds default properties for the application: + *
      + *
    • logging pattern level that prints trace information (e.g. trace ids)
      • + *
    • enables usage of subclass-based (CGLIB) proxies are to be created as opposed + * to standard Java interface-based proxies
      • + * It's required for the tracing aspects like + * {@link org.springframework.cloud.sleuth.instrument.async.TraceAsyncAspect TraceAsyncAspect} or + * {@link org.springframework.cloud.sleuth.instrument.scheduling.TraceSchedulingAspect TraceSchedulingAspect}. + *
    * * @author Dave Syer - * + * @since 1.0.0 */ public class TraceEnvironmentPostProcessor implements EnvironmentPostProcessor { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ArrayListSpanAccumulator.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ArrayListSpanAccumulator.java index 35a8a90b4..d3671e943 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ArrayListSpanAccumulator.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ArrayListSpanAccumulator.java @@ -23,7 +23,11 @@ import org.springframework.cloud.sleuth.Span; import org.springframework.context.ApplicationListener; /** + * Accumulator of {@link org.springframework.cloud.sleuth.Tracer#close(Span) + * closed spans}. + * * @author Spencer Gibb + * @since 1.0.0 */ public class ArrayListSpanAccumulator implements ApplicationListener { private final List spans = new ArrayList<>(); diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ClientReceivedEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ClientReceivedEvent.java index 30e04714b..9b266b7a0 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ClientReceivedEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ClientReceivedEvent.java @@ -19,8 +19,14 @@ package org.springframework.cloud.sleuth.event; import org.springframework.cloud.sleuth.Span; /** - * @author Dave Syer + * cr - Client Receive. Signifies the end of the span. The client has successfully received the + * response from the server side. If one subtracts the cs timestamp from this timestamp one + * will receive the whole time needed by the client to receive the response from the server. * + * @author Dave Syer + * @since 1.0.0 + * + * @see ClientSentEvent */ @SuppressWarnings("serial") public class ClientReceivedEvent extends SpanContainingEvent { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ClientSentEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ClientSentEvent.java index c7dd43b2f..c7293be24 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ClientSentEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ClientSentEvent.java @@ -19,8 +19,12 @@ package org.springframework.cloud.sleuth.event; import org.springframework.cloud.sleuth.Span; /** - * @author Dave Syer + * cs - Client Sent. The client has made a request (a client can be e.g. + * {@link org.springframework.web.client.RestTemplate}. This annotation depicts + * the start of the span. * + * @author Dave Syer + * @since 1.0.0 */ @SuppressWarnings("serial") public class ClientSentEvent extends SpanContainingEvent { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ServerReceivedEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ServerReceivedEvent.java index a2be82b7e..5c69c37d8 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ServerReceivedEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ServerReceivedEvent.java @@ -19,7 +19,13 @@ package org.springframework.cloud.sleuth.event; import org.springframework.cloud.sleuth.Span; /** + * sr - Server Receive. The server side got the request and will start processing it. + * If one subtracts the cs timestamp from this timestamp one will receive the network latency. + * * @author Spencer Gibb + * @since 1.0.0 + * + * @see ClientSentEvent */ @SuppressWarnings("serial") public class ServerReceivedEvent extends SpanParentContainingEvent { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ServerSentEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ServerSentEvent.java index b0f0c0784..3d0a0fe92 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ServerSentEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/ServerSentEvent.java @@ -19,7 +19,14 @@ package org.springframework.cloud.sleuth.event; import org.springframework.cloud.sleuth.Span; /** + * ss - Server Send. Annotated upon completion of request processing (when the response + * got sent back to the client). If one subtracts the sr timestamp from this timestamp one + * will receive the time needed by the server side to process the request. + * * @author Spencer Gibb + * @since 1.0.0 + * + * @see ServerReceivedEvent */ @SuppressWarnings("serial") public class ServerSentEvent extends SpanParentContainingEvent { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanAcquiredEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanAcquiredEvent.java index e44148c7f..7b65d45c1 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanAcquiredEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanAcquiredEvent.java @@ -19,7 +19,10 @@ package org.springframework.cloud.sleuth.event; import org.springframework.cloud.sleuth.Span; /** + * Event emitted when a parent or a child span was created. + * * @author Spencer Gibb + * @since 1.0.0 */ @SuppressWarnings("serial") public class SpanAcquiredEvent extends SpanParentContainingEvent { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanContainingEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanContainingEvent.java index c73d9e03b..a8fdea76f 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanContainingEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanContainingEvent.java @@ -24,7 +24,7 @@ import org.springframework.context.ApplicationEvent; /** * @author Marcin Grzejszczak */ -class SpanContainingEvent extends ApplicationEvent { +abstract class SpanContainingEvent extends ApplicationEvent { private final Span span; public SpanContainingEvent(Object source, Span span) { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanContinuedEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanContinuedEvent.java index 04d76e4bb..daa2eeb8f 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanContinuedEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanContinuedEvent.java @@ -19,6 +19,8 @@ package org.springframework.cloud.sleuth.event; import org.springframework.cloud.sleuth.Span; /** + * Emitted when a span was continued. + * * @author Spencer Gibb */ @SuppressWarnings("serial") diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanParentContainingEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanParentContainingEvent.java index 38d9992b8..9a2ade0f7 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanParentContainingEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanParentContainingEvent.java @@ -24,7 +24,7 @@ import org.springframework.context.ApplicationEvent; /** * @author Marcin Grzejszczak */ -class SpanParentContainingEvent extends ApplicationEvent { +abstract class SpanParentContainingEvent extends ApplicationEvent { private final Span span; private final Span parent; diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanReleasedEvent.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanReleasedEvent.java index 82f386e53..ce30e2510 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanReleasedEvent.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/event/SpanReleasedEvent.java @@ -19,6 +19,9 @@ package org.springframework.cloud.sleuth.event; import org.springframework.cloud.sleuth.Span; /** + * Event emitted upon closing of a span. Results in preparing span for collection + * to external systems (logging, Zipkin etc.) + * * @author Spencer Gibb */ @SuppressWarnings("serial") diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/SpanExtractor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/SpanExtractor.java deleted file mode 100644 index 920792649..000000000 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/SpanExtractor.java +++ /dev/null @@ -1,32 +0,0 @@ -/* - * Copyright 2015 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.instrument; - -import org.springframework.cloud.sleuth.Span; -import org.springframework.cloud.sleuth.TraceKeys; - -/** - * @author Dave Syer - * - */ -public interface SpanExtractor { - - Span extract(T input, TraceKeys keys); - - void inject(Span span, U output, TraceKeys keys); - -} diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/AsyncCustomAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/AsyncCustomAutoConfiguration.java index a5f10ca94..ec8895e24 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/AsyncCustomAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/AsyncCustomAutoConfiguration.java @@ -28,6 +28,13 @@ import org.springframework.cloud.sleuth.instrument.scheduling.TraceSchedulingAut import org.springframework.context.annotation.Configuration; import org.springframework.scheduling.annotation.AsyncConfigurer; +/** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * that wraps an existing custom {@link AsyncConfigurer} in a {@link LazyTraceAsyncCustomizer} + * + * @author Dave Syer + * @since 1.0.0 + */ @Configuration @ConditionalOnBean(AsyncConfigurer.class) @AutoConfigureBefore(AsyncDefaultAutoConfiguration.class) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/AsyncDefaultAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/AsyncDefaultAutoConfiguration.java index f3543695b..25764982a 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/AsyncDefaultAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/AsyncDefaultAutoConfiguration.java @@ -33,20 +33,35 @@ import org.springframework.scheduling.annotation.AsyncConfigurer; import org.springframework.scheduling.annotation.AsyncConfigurerSupport; import org.springframework.scheduling.annotation.EnableAsync; +/** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enabling async related processing. + * + * @author Dave Syer + * @author Marcin Grzejszczak + * @since 1.0.0 + * + * @see LazyTraceExecutor + * @see TraceAsyncAspect + */ @EnableAsync @Configuration -@ConditionalOnMissingBean(AsyncConfigurer.class) @ConditionalOnProperty(value = "spring.sleuth.async.enabled", matchIfMissing = true) @ConditionalOnBean(Tracer.class) @AutoConfigureAfter(AsyncCustomAutoConfiguration.class) -public class AsyncDefaultAutoConfiguration extends AsyncConfigurerSupport { +public class AsyncDefaultAutoConfiguration { - @Autowired - private BeanFactory beanFactory; + @Configuration + @ConditionalOnMissingBean(AsyncConfigurer.class) + @ConditionalOnProperty(value = "spring.sleuth.async.configurer.enabled", matchIfMissing = true) + static class DefaultAsyncConfigurerSupport extends AsyncConfigurerSupport { - @Override - public Executor getAsyncExecutor() { - return new LazyTraceExecutor(this.beanFactory, new SimpleAsyncTaskExecutor()); + @Autowired private BeanFactory beanFactory; + + @Override + public Executor getAsyncExecutor() { + return new LazyTraceExecutor(this.beanFactory, new SimpleAsyncTaskExecutor()); + } } @Bean diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LazyTraceAsyncCustomizer.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LazyTraceAsyncCustomizer.java index 9a82988d6..965f4a8fa 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LazyTraceAsyncCustomizer.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LazyTraceAsyncCustomizer.java @@ -25,7 +25,7 @@ import org.springframework.scheduling.annotation.AsyncConfigurerSupport; /** * @author Dave Syer - * + * @since 1.0.0 */ public class LazyTraceAsyncCustomizer extends AsyncConfigurerSupport { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LazyTraceExecutor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LazyTraceExecutor.java index 4012cbb85..9734c2ad7 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LazyTraceExecutor.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LazyTraceExecutor.java @@ -25,12 +25,16 @@ import org.springframework.beans.factory.BeanFactory; import org.springframework.beans.factory.NoSuchBeanDefinitionException; import org.springframework.cloud.sleuth.DefaultSpanNamer; import org.springframework.cloud.sleuth.SpanNamer; -import org.springframework.cloud.sleuth.Tracer; import org.springframework.cloud.sleuth.TraceKeys; +import org.springframework.cloud.sleuth.Tracer; /** - * @author Dave Syer + * {@link Executor} that wraps {@link Runnable} in a + * {@link org.springframework.cloud.sleuth.TraceRunnable TraceRunnable} that sets a + * local component tag on the span. * + * @author Dave Syer + * @since 1.0.0 */ public class LazyTraceExecutor implements Executor { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LocalComponentTraceCallable.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LocalComponentTraceCallable.java index fc1a49881..210520e66 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LocalComponentTraceCallable.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LocalComponentTraceCallable.java @@ -25,10 +25,10 @@ import org.springframework.cloud.sleuth.Tracer; import org.springframework.cloud.sleuth.TraceKeys; /** - * * Callable that starts a span that is a local component span. * * @author Marcin Grzejszczak + * @since 1.0.0 */ public class LocalComponentTraceCallable extends TraceCallable { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LocalComponentTraceRunnable.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LocalComponentTraceRunnable.java index e3f1ab5a2..bcf406ecc 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LocalComponentTraceRunnable.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/LocalComponentTraceRunnable.java @@ -23,10 +23,10 @@ import org.springframework.cloud.sleuth.Tracer; import org.springframework.cloud.sleuth.TraceKeys; /** - * * Runnable that starts a span that is a local component span. * * @author Marcin Grzejszczak + * @since 1.0.0 */ public class LocalComponentTraceRunnable extends TraceRunnable { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceAsyncAspect.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceAsyncAspect.java index 111f3f1ee..f7ee0cf52 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceAsyncAspect.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceAsyncAspect.java @@ -28,6 +28,7 @@ import org.springframework.cloud.sleuth.TraceKeys; * {@link org.springframework.scheduling.annotation.Async} annotation. * * @author Marcin Grzejszczak + * @since 1.0.0 * * @see Tracer */ diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceContinuingCallable.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceContinuingCallable.java index e652c83bb..dc7c3cea2 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceContinuingCallable.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceContinuingCallable.java @@ -24,7 +24,8 @@ import org.springframework.cloud.sleuth.TraceCallable; import org.springframework.cloud.sleuth.Tracer; /** - * Trace Callable that continues a span instead of creating a new one + * Trace Callable that continues a span instead of creating a new one. Upon completion + * the span is not closed - it gets {@link Tracer#detach(Span) detached}. * * @author Marcin Grzejszczak */ diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceableExecutorService.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceableExecutorService.java index 62dc90480..a3fb9b7a1 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceableExecutorService.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceableExecutorService.java @@ -30,8 +30,9 @@ import org.springframework.cloud.sleuth.TraceKeys; /** * A decorator class for {@link ExecutorService} to support tracing in Executors - * @author Gaurav Rai Mazra * + * @author Gaurav Rai Mazra + * @since 1.0.0 */ public class TraceableExecutorService implements ExecutorService { final ExecutorService delegate; diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceableScheduledExecutorService.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceableScheduledExecutorService.java index d02077532..b54e727c4 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceableScheduledExecutorService.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/async/TraceableScheduledExecutorService.java @@ -27,8 +27,9 @@ import org.springframework.cloud.sleuth.TraceKeys; /** * A decorator class for {@link ScheduledExecutorService} to support tracing in Executors - * @author Gaurav Rai Mazra * + * @author Gaurav Rai Mazra + * @since 1.0.0 */ public class TraceableScheduledExecutorService extends TraceableExecutorService implements ScheduledExecutorService { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/hystrix/SleuthHystrixAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/hystrix/SleuthHystrixAutoConfiguration.java index b6977dc97..2c7d85773 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/hystrix/SleuthHystrixAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/hystrix/SleuthHystrixAutoConfiguration.java @@ -9,6 +9,15 @@ import org.springframework.context.annotation.Configuration; import com.netflix.hystrix.HystrixCommand; +/** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * that registers a custom Sleuth {@link com.netflix.hystrix.strategy.concurrency.HystrixConcurrencyStrategy}. + * + * @author Marcin Grzejszczak + * @since 1.0.0 + * + * @see SleuthHystrixConcurrencyStrategy + */ @Configuration @ConditionalOnClass(HystrixCommand.class) @ConditionalOnProperty(value = "spring.sleuth.hystrix.strategy.enabled", matchIfMissing = true) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/hystrix/SleuthHystrixConcurrencyStrategy.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/hystrix/SleuthHystrixConcurrencyStrategy.java index d3ea31692..ef37c6a11 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/hystrix/SleuthHystrixConcurrencyStrategy.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/hystrix/SleuthHystrixConcurrencyStrategy.java @@ -13,6 +13,14 @@ import org.springframework.cloud.sleuth.TraceKeys; import com.netflix.hystrix.strategy.HystrixPlugins; import com.netflix.hystrix.strategy.concurrency.HystrixConcurrencyStrategy; +/** + * A {@link HystrixConcurrencyStrategy} that wraps a {@link Callable} in a + * {@link Callable} that either starts a new span or continues one + * if the tracing was already running before the command was executed. + * + * @author Marcin Grzejszczak + * @since 1.0.0 + */ public class SleuthHystrixConcurrencyStrategy extends HystrixConcurrencyStrategy { private static final String HYSTRIX_COMPONENT = "hystrix"; diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/SpanMessageHeaders.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/SpanMessageHeaders.java index e165e2d12..1cb3d1bc2 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/SpanMessageHeaders.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/SpanMessageHeaders.java @@ -49,6 +49,15 @@ public class SpanMessageHeaders { return null; } + /** + * Adds default headers for a message. Check {@link Span} constants for + * more information what the default headers are. + * + * @param traceKeys - the global configuration for trace keys + * @param message - message to which headers will be added + * @param span - span from which headers will be taken + * @return the input message with updated headers + */ public static Message addSpanHeaders(TraceKeys traceKeys, Message message, Span span) { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/TraceChannelInterceptor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/TraceChannelInterceptor.java index 3998cce7b..797f17d75 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/TraceChannelInterceptor.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/TraceChannelInterceptor.java @@ -27,8 +27,10 @@ import org.springframework.messaging.MessageChannel; import org.springframework.messaging.MessageHandler; /** - * @author Dave Syer + * A channel interceptor that automatically starts / continues / closes and detaches spans. * + * @author Dave Syer + * @since 1.0.0 */ public class TraceChannelInterceptor extends AbstractTraceChannelInterceptor { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/TraceSpringIntegrationAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/TraceSpringIntegrationAutoConfiguration.java index c0546db00..532c5e301 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/TraceSpringIntegrationAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/TraceSpringIntegrationAutoConfiguration.java @@ -31,7 +31,13 @@ import org.springframework.context.annotation.Configuration; import org.springframework.integration.config.GlobalChannelInterceptor; /** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * that registers a Sleuth version of the {@link org.springframework.messaging.support.ChannelInterceptor}. + * * @author Spencer Gibb + * @since 1.0.0 + * + * @see TraceChannelInterceptor */ @Configuration @ConditionalOnClass(GlobalChannelInterceptor.class) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/websocket/TraceWebSocketAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/websocket/TraceWebSocketAutoConfiguration.java index 126e80bcf..48151665f 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/websocket/TraceWebSocketAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/messaging/websocket/TraceWebSocketAutoConfiguration.java @@ -14,6 +14,15 @@ import org.springframework.web.socket.config.annotation.AbstractWebSocketMessage import org.springframework.web.socket.config.annotation.DelegatingWebSocketMessageBrokerConfiguration; import org.springframework.web.socket.config.annotation.StompEndpointRegistry; +/** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * that enables tracing for WebSockets. + * + * @author Dave Syer + * @since 1.0.0 + * + * @see AbstractWebSocketMessageBrokerConfigurer + */ @Component @ConditionalOnClass(DelegatingWebSocketMessageBrokerConfiguration.class) @ConditionalOnBean(AbstractWebSocketMessageBrokerConfigurer.class) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/scheduling/TraceSchedulingAspect.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/scheduling/TraceSchedulingAspect.java index 5cc41298e..e7124e0bc 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/scheduling/TraceSchedulingAspect.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/scheduling/TraceSchedulingAspect.java @@ -25,12 +25,15 @@ import org.springframework.cloud.sleuth.Tracer; /** * Aspect that creates a new Span for running threads executing methods annotated with * {@link org.springframework.scheduling.annotation.Scheduled} annotation. - * For every execution of scheduled method a new trace will be started. + * For every execution of scheduled method a new trace will be started. The name of the + * span will be the simple name of the class annotated with + * {@link org.springframework.scheduling.annotation.Scheduled} * * @author Tomasz Nurkewicz, 4financeIT * @author Michal Chmielarz, 4financeIT - * @author Marcin Grzejszczak, 4financeIT + * @author Marcin Grzejszczak * @author Spencer Gibb + * @since 1.0.0 * * @see Tracer */ @@ -47,8 +50,9 @@ public class TraceSchedulingAspect { @Around("execution (@org.springframework.scheduling.annotation.Scheduled * *.*(..))") public Object traceBackgroundThread(final ProceedingJoinPoint pjp) throws Throwable { - String spanName = SCHEDULED_COMPONENT + ":" + pjp.getTarget().getClass().getSimpleName(); + String spanName = pjp.getTarget().getClass().getSimpleName(); Span span = this.tracer.startTrace(spanName); + this.tracer.addTag(Span.SPAN_LOCAL_COMPONENT_TAG_NAME, SCHEDULED_COMPONENT); try { return pjp.proceed(); } diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/scheduling/TraceSchedulingAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/scheduling/TraceSchedulingAutoConfiguration.java index 68e3e19cc..b72e4dd44 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/scheduling/TraceSchedulingAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/scheduling/TraceSchedulingAutoConfiguration.java @@ -34,10 +34,11 @@ import org.springframework.context.annotation.EnableAspectJAutoProxy; /** * Registers beans related to task scheduling. * - * @see TraceSchedulingAspect - * * @author Michal Chmielarz, 4financeIT * @author Spencer Gibb + * + * @see TraceSchedulingAspect + * @since 1.0.0 */ @Configuration @EnableAspectJAutoProxy diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceFilter.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceFilter.java index 2e6f7d3ab..f1411f320 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceFilter.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceFilter.java @@ -15,10 +15,6 @@ */ package org.springframework.cloud.sleuth.instrument.web; -import javax.servlet.FilterChain; -import javax.servlet.ServletException; -import javax.servlet.http.HttpServletRequest; -import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.util.ArrayList; import java.util.Collections; @@ -26,12 +22,17 @@ import java.util.Enumeration; import java.util.Random; import java.util.regex.Pattern; +import javax.servlet.FilterChain; +import javax.servlet.ServletException; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpServletResponse; + import org.springframework.cloud.sleuth.Span; import org.springframework.cloud.sleuth.Span.SpanBuilder; +import org.springframework.cloud.sleuth.TraceKeys; import org.springframework.cloud.sleuth.Tracer; import org.springframework.cloud.sleuth.event.ServerReceivedEvent; import org.springframework.cloud.sleuth.event.ServerSentEvent; -import org.springframework.cloud.sleuth.TraceKeys; import org.springframework.cloud.sleuth.sampler.NeverSampler; import org.springframework.context.ApplicationEvent; import org.springframework.context.ApplicationEventPublisher; @@ -54,15 +55,17 @@ import static org.springframework.util.StringUtils.hasText; * {@link TraceKeys}. If you need to add additional tags, such as headers subtype this and * override {@link #addRequestTags} or {@link #addResponseTags}. * + * @author Jakub Nabrdalik, 4financeIT + * @author Tomasz Nurkiewicz, 4financeIT + * @author Marcin Grzejszczak + * @author Spencer Gibb + * @author Dave Syer + * * @see Tracer * @see TraceKeys * @see TraceWebAutoConfiguration#traceFilter * - * @author Jakub Nabrdalik, 4financeIT - * @author Tomasz Nurkiewicz, 4financeIT - * @author Marcin Grzejszczak, 4financeIT - * @author Spencer Gibb - * @author Dave Syer + * @since 1.0.0 */ @Order(Ordered.HIGHEST_PRECEDENCE + 5) public class TraceFilter extends OncePerRequestFilter diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceHandlerInterceptor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceHandlerInterceptor.java deleted file mode 100644 index dd1fc955e..000000000 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceHandlerInterceptor.java +++ /dev/null @@ -1,67 +0,0 @@ -/* - * Copyright 2013-2015 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.instrument.web; - -import javax.servlet.http.HttpServletRequest; -import javax.servlet.http.HttpServletResponse; - -import org.springframework.cloud.sleuth.Span; -import org.springframework.cloud.sleuth.Tracer; -import org.springframework.web.servlet.HandlerInterceptor; -import org.springframework.web.servlet.ModelAndView; -import org.springframework.web.util.UrlPathHelper; - -/** - * @author Spencer Gibb - */ -public class TraceHandlerInterceptor implements HandlerInterceptor { - - private static final String ATTR_NAME = "__CURRENT_TRACE_HANDLER_TRACE_ATTR___"; - - private final Tracer tracer; - - private final UrlPathHelper urlPathHelper = new UrlPathHelper(); - - public TraceHandlerInterceptor(Tracer tracer) { - this.tracer = tracer; - } - - @Override - public boolean preHandle(HttpServletRequest request, HttpServletResponse response, - Object handler) throws Exception { - // TODO: get trace data from request? - // TODO: what is the description? - String uri = this.urlPathHelper.getPathWithinApplication(request); - String spanName = "http:" + uri; - Span span = this.tracer.startTrace(spanName); - request.setAttribute(ATTR_NAME, span); - return true; - } - - @Override - public void postHandle(HttpServletRequest request, HttpServletResponse response, - Object handler, ModelAndView modelAndView) throws Exception { - - } - - @Override - public void afterCompletion(HttpServletRequest request, HttpServletResponse response, - Object handler, Exception ex) throws Exception { - Span span = Span.class.cast(request.getAttribute(ATTR_NAME)); - this.tracer.close(span); - } -} diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceWebAspect.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceWebAspect.java index 43652f32c..55f033847 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceWebAspect.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceWebAspect.java @@ -31,7 +31,7 @@ import org.springframework.cloud.sleuth.instrument.async.TraceContinuingCallable import org.springframework.web.context.request.async.WebAsyncTask; /** - * Aspect that adds correlation id to + * Aspect that adds tracing to *

    *

      *
    • {@link org.springframework.web.bind.annotation.RestController} annotated classes @@ -51,17 +51,19 @@ import org.springframework.web.context.request.async.WebAsyncTask; * a new span - since the one in TraceFilter will wait until processing has been * finished * + * @author Tomasz Nurkewicz, 4financeIT + * @author Michal Chmielarz, 4financeIT + * @author Marcin Grzejszczak + * @author Spencer Gibb + * + * @since 1.0.0 + * * @see org.springframework.web.bind.annotation.RestController * @see org.springframework.stereotype.Controller * @see org.springframework.web.client.RestOperations * @see org.springframework.cloud.sleuth.TraceCallable * @see org.springframework.cloud.sleuth.Tracer * @see org.springframework.cloud.sleuth.instrument.web.TraceFilter - * - * @author Tomasz Nurkewicz, 4financeIT - * @author Marcin Grzejszczak, 4financeIT - * @author Michal Chmielarz, 4financeIT - * @author Spencer Gibb */ @Aspect public class TraceWebAspect { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceWebAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceWebAutoConfiguration.java index b7736dd7f..c4cff5fbb 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceWebAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/TraceWebAutoConfiguration.java @@ -37,12 +37,15 @@ import org.springframework.context.annotation.Configuration; import org.springframework.util.StringUtils; /** - * Registers beans that add tracing to requests + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enables tracing to HTTP requests. * * @author Tomasz Nurkewicz, 4financeIT - * @author Marcin Grzejszczak, 4financeIT * @author Michal Chmielarz, 4financeIT + * @author Marcin Grzejszczak * @author Spencer Gibb + * + * @since 1.0.0 */ @Configuration @ConditionalOnProperty(value = "spring.sleuth.web.enabled", matchIfMissing = true) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/AbstractTraceHttpRequestInterceptor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/AbstractTraceHttpRequestInterceptor.java index 744bc0258..09074ff08 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/AbstractTraceHttpRequestInterceptor.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/AbstractTraceHttpRequestInterceptor.java @@ -31,6 +31,8 @@ import org.springframework.util.StringUtils; * to enrich the request headers with trace related information. * * @author Marcin Grzejszczak + * + * @since 1.0.0 */ abstract class AbstractTraceHttpRequestInterceptor implements ApplicationEventPublisherAware { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/SleuthHystrixInvocationHandler.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/SleuthHystrixInvocationHandler.java index f4ba4987d..ea98384ff 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/SleuthHystrixInvocationHandler.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/SleuthHystrixInvocationHandler.java @@ -35,7 +35,9 @@ import feign.Target; import static feign.Util.checkNotNull; /** - * Wraps execution in Sleuth's TraceCommand + * Wraps {@link HystrixCommand} execution in Sleuth's {@link TraceCommand} + * + * @since 1.0.0 */ final class SleuthHystrixInvocationHandler implements InvocationHandler { @@ -59,7 +61,6 @@ final class SleuthHystrixInvocationHandler implements InvocationHandler { HystrixCommand.Setter setter = HystrixCommand.Setter .withGroupKey(HystrixCommandGroupKey.Factory.asKey(groupKey)) .andCommandKey(HystrixCommandKey.Factory.asKey(commandKey)); - HystrixCommand hystrixCommand = new TraceCommand(this.tracer, this.traceKeys, setter) { @Override public Object doRun() throws Exception { @@ -73,7 +74,6 @@ final class SleuthHystrixInvocationHandler implements InvocationHandler { return null; } }; - if (HystrixCommand.class.isAssignableFrom(method.getReturnType())) { return hystrixCommand; } diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceAsyncClientHttpRequestFactoryWrapper.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceAsyncClientHttpRequestFactoryWrapper.java index c00cdd8b3..940524a2b 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceAsyncClientHttpRequestFactoryWrapper.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceAsyncClientHttpRequestFactoryWrapper.java @@ -36,6 +36,8 @@ import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler; * * @author Marcin Grzejszczak * @author Spencer Gibb + * + * @since 1.0.0 */ public class TraceAsyncClientHttpRequestFactoryWrapper extends AbstractTraceHttpRequestInterceptor implements ClientHttpRequestFactory, AsyncClientHttpRequestFactory { @@ -45,7 +47,7 @@ public class TraceAsyncClientHttpRequestFactoryWrapper extends AbstractTraceHttp private final ClientHttpRequestFactory syncDelegate; /** - * According to the javadocs all Spring {@link AsyncClientHttpRequestFactory} implement + * According to the JavaDocs all Spring {@link AsyncClientHttpRequestFactory} implement * the {@link ClientHttpRequestFactory} interface. * * In case that it's not true we're setting the {@link SimpleClientHttpRequestFactory} diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceAsyncListenableTaskExecutor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceAsyncListenableTaskExecutor.java index 9cda09e6d..bf2c4865d 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceAsyncListenableTaskExecutor.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceAsyncListenableTaskExecutor.java @@ -26,6 +26,11 @@ import org.springframework.util.concurrent.ListenableFuture; /** * AsyncListenableTaskExecutor that wraps all Runnable / Callable tasks into * their trace related representation + * + * @since 1.0.0 + * + * @see Tracer#wrap(Runnable) + * @see Tracer#wrap(Callable) */ public class TraceAsyncListenableTaskExecutor implements AsyncListenableTaskExecutor { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceFeignClientAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceFeignClientAutoConfiguration.java index 1e827c5a4..a9b16b098 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceFeignClientAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceFeignClientAutoConfiguration.java @@ -63,10 +63,12 @@ import feign.codec.Decoder; import feign.hystrix.HystrixFeign; /** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enables span information propagation when using Feign. * - * Configuration for ensuring that Spans are propagated while using Feign + * @author Marcin Grzejszczak * - * @author Marcin Grzejszczak, 4financeIT + * @since 1.0.0 */ @Configuration @ConditionalOnProperty(value = "spring.sleuth.feign.enabled", matchIfMissing = true) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceHttpResponse.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceHttpResponse.java index 83cbf2c6d..30bdb50ba 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceHttpResponse.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceHttpResponse.java @@ -24,8 +24,13 @@ import org.springframework.http.HttpStatus; import org.springframework.http.client.ClientHttpResponse; /** + * Implementation of {@link ClientHttpResponse} that upon + * {@link ClientHttpResponse#close() closing the response} + * {@link TraceRestTemplateInterceptor#finish() closes the span} + * * @author Dave Syer * + * @since 1.0.0 */ public class TraceHttpResponse implements ClientHttpResponse { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceRestTemplateInterceptor.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceRestTemplateInterceptor.java index 5791f7aa6..7fbb90052 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceRestTemplateInterceptor.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceRestTemplateInterceptor.java @@ -27,11 +27,13 @@ import org.springframework.http.client.ClientHttpResponse; * Interceptor that verifies whether the trance and span id has been set on the request * and sets them if one or both of them are missing. * + * @author Marcin Grzejszczak + * @author Spencer Gibb + * * @see org.springframework.web.client.RestTemplate * @see SpanAccessor * - * @author Marcin Grzejszczak - * @author Spencer Gibb + * @since 1.0.0 */ public class TraceRestTemplateInterceptor extends AbstractTraceHttpRequestInterceptor implements ClientHttpRequestInterceptor { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceWebAsyncClientAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceWebAsyncClientAutoConfiguration.java index 7c883afc6..8b5498572 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceWebAsyncClientAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceWebAsyncClientAutoConfiguration.java @@ -30,7 +30,13 @@ import org.springframework.http.client.AsyncClientHttpRequestFactory; import org.springframework.web.client.AsyncRestTemplate; /** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enables span information propagation for {@link AsyncClientHttpRequestFactory} and + * {@link AsyncRestTemplate} + * * @author Marcin Grzejszczak + * + * @since 1.0.0 */ @Configuration @ConditionalOnProperty(value = "spring.sleuth.async.client.enabled", matchIfMissing = true) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceWebClientAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceWebClientAutoConfiguration.java index d1a231204..fd67a721b 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceWebClientAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/web/client/TraceWebClientAutoConfiguration.java @@ -36,7 +36,12 @@ import org.springframework.http.client.ClientHttpRequestInterceptor; import org.springframework.web.client.RestTemplate; /** - * @author Spencer Gibb + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enables span information propagation when using {@link RestTemplate} + * + * @author Marcin Grzejszczak + * + * @since 1.0.0 */ @Configuration @ConditionalOnProperty(value = "spring.sleuth.client.enabled", matchIfMissing = true) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TracePostZuulFilter.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TracePostZuulFilter.java index 2cd936d1c..dc399b4a9 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TracePostZuulFilter.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TracePostZuulFilter.java @@ -26,8 +26,11 @@ import org.springframework.context.ApplicationEventPublisherAware; import com.netflix.zuul.ZuulFilter; /** + * A post request {@link ZuulFilter} that publishes an event upon start of the filtering + * * @author Dave Syer * + * @since 1.0.0 */ public class TracePostZuulFilter extends ZuulFilter implements ApplicationEventPublisherAware { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TracePreZuulFilter.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TracePreZuulFilter.java index 3b72714a4..063b6e624 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TracePreZuulFilter.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TracePreZuulFilter.java @@ -25,14 +25,18 @@ import org.springframework.context.ApplicationEvent; import org.springframework.context.ApplicationEventPublisher; import org.springframework.context.ApplicationEventPublisherAware; import org.springframework.util.ReflectionUtils; +import org.springframework.util.StringUtils; import com.netflix.zuul.ZuulFilter; import com.netflix.zuul.context.RequestContext; -import org.springframework.util.StringUtils; /** + * A pre request {@link ZuulFilter} that sets tracing related headers on the request + * from the current span. We're doing so to ensure tracing propagates to the next hop. + * * @author Dave Syer * + * @since 1.0.0 */ public class TracePreZuulFilter extends ZuulFilter implements ApplicationEventPublisherAware { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TraceRestClientRibbonCommandFactory.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TraceRestClientRibbonCommandFactory.java index 3cd0f5425..f95723c22 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TraceRestClientRibbonCommandFactory.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TraceRestClientRibbonCommandFactory.java @@ -19,8 +19,6 @@ package org.springframework.cloud.sleuth.instrument.zuul; import java.io.InputStream; import java.net.URISyntaxException; -import com.netflix.client.http.HttpRequest; -import com.netflix.niws.client.http.RestClient; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.springframework.cloud.netflix.ribbon.SpringClientFactory; @@ -35,8 +33,15 @@ import org.springframework.context.ApplicationEventPublisher; import org.springframework.context.ApplicationEventPublisherAware; import org.springframework.util.MultiValueMap; +import com.netflix.client.http.HttpRequest; +import com.netflix.niws.client.http.RestClient; + /** + * Propagates traces downstream via http headers that contain trace metadata. + * * @author Spencer Gibb + * + * @since 1.0.0 */ public class TraceRestClientRibbonCommandFactory extends RestClientRibbonCommandFactory implements ApplicationEventPublisherAware { @@ -104,8 +109,10 @@ public class TraceRestClientRibbonCommandFactory extends RestClientRibbonCommand setHeader(requestBuilder, Span.TRACE_ID_NAME, Span.idToHex(span.getTraceId())); setHeader(requestBuilder, Span.SPAN_ID_NAME, Span.idToHex(span.getSpanId())); setHeader(requestBuilder, Span.SPAN_NAME_NAME, span.getName()); - setHeader(requestBuilder, Span.PARENT_ID_NAME, - Span.idToHex(getParentId(span))); + if (getParentId(span) != null) { + setHeader(requestBuilder, Span.PARENT_ID_NAME, + Span.idToHex(getParentId(span))); + } setHeader(requestBuilder, Span.PROCESS_ID_NAME, span.getProcessId()); publish(new ClientSentEvent(this, span)); diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TraceZuulAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TraceZuulAutoConfiguration.java index 6da28f402..e03dd7b9c 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TraceZuulAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/instrument/zuul/TraceZuulAutoConfiguration.java @@ -31,9 +31,12 @@ import org.springframework.context.annotation.Configuration; import com.netflix.zuul.ZuulFilter; /** - * Registers beans that add tracing to requests + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enables span information propagation when using Zuul. * * @author Dave Syer + * + * @since 1.0.0 */ @Configuration @ConditionalOnProperty(value = "spring.sleuth.zuul.enabled", matchIfMissing = true) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/log/SleuthLogAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/log/SleuthLogAutoConfiguration.java index ec4b7aa5b..8653071e0 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/log/SleuthLogAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/log/SleuthLogAutoConfiguration.java @@ -28,7 +28,14 @@ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; /** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enables a {@link Slf4jSpanListener} that prints tracing information in the logs. + *

      + * Note: this is only available for Slf4j + * * @author Spencer Gibb + * + * @since 1.0.0 */ @Configuration @ConditionalOnBean(Tracer.class) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/log/Slf4jSpanListener.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/log/Slf4jSpanListener.java index 13079279d..d53778f0e 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/log/Slf4jSpanListener.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/log/Slf4jSpanListener.java @@ -29,7 +29,12 @@ import org.springframework.core.Ordered; import org.springframework.core.annotation.Order; /** + * Span listener that logs to the console when a span got + * started / stopped / continued. + * * @author Spencer Gibb + * + * @since 1.0.0 */ public class Slf4jSpanListener { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/CounterServiceBasedSpanReporterService.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/CounterServiceBasedSpanReporterService.java index 0d89bc48a..c186ccec5 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/CounterServiceBasedSpanReporterService.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/CounterServiceBasedSpanReporterService.java @@ -4,8 +4,11 @@ import org.springframework.boot.actuate.metrics.CounterService; /** * Service to operate on accepted and dropped spans statistics. + * Operates on a {@link CounterService} underneath * * @author Marcin Grzejszczak + * + * @since 1.0.0 */ public class CounterServiceBasedSpanReporterService implements SpanReporterService { private final String acceptedSpansMetricName; diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/NoOpSpanReporterService.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/NoOpSpanReporterService.java index a01bb2655..7ce415c84 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/NoOpSpanReporterService.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/NoOpSpanReporterService.java @@ -1,9 +1,11 @@ package org.springframework.cloud.sleuth.metric; /** - * Span reporting service that does nothing + * {@link SpanReporterService} that does nothing * * @author Marcin Grzejszczak + * + * @since 1.0.0 */ public class NoOpSpanReporterService implements SpanReporterService { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/SleuthMetricProperties.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/SleuthMetricProperties.java index 56dcac1d7..f55965807 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/SleuthMetricProperties.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/SleuthMetricProperties.java @@ -6,6 +6,8 @@ import org.springframework.boot.context.properties.ConfigurationProperties; * Configuration properties for Sleuth related metrics * * @author Marcin Grzejszczak + * + * @since 1.0.0 */ @ConfigurationProperties("spring.sleuth.metric") public class SleuthMetricProperties { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/SpanReporterService.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/SpanReporterService.java index 8c2a2bb5c..4ada25e21 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/SpanReporterService.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/SpanReporterService.java @@ -1,12 +1,16 @@ package org.springframework.cloud.sleuth.metric; /** + * Contract for a service that measures the number of accepted / dropped spans. + * * @author Marcin Grzejszczak + * + * @since 1.0.0 */ public interface SpanReporterService { /** - * Called when spans are submitted to SpanCollector for processing. + * Called when spans are submitted to span collector for processing. * * @param quantity the number of spans accepted. */ diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/TraceMetricsAutoConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/TraceMetricsAutoConfiguration.java index ab9a442dd..bfb473fd8 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/TraceMetricsAutoConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/metric/TraceMetricsAutoConfiguration.java @@ -27,7 +27,12 @@ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; /** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enables Sleuth related metrics reporting + * * @author Marcin Grzejszczak + * + * @since 1.0.0 */ @Configuration @ConditionalOnProperty(value="spring.sleuth.metrics.enabled", matchIfMissing=true) diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/AlwaysSampler.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/AlwaysSampler.java index 90851b08c..2f92fecbe 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/AlwaysSampler.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/AlwaysSampler.java @@ -20,7 +20,11 @@ import org.springframework.cloud.sleuth.Sampler; import org.springframework.cloud.sleuth.Span; /** + * {@link Sampler} that traces each action + * * @author Spencer Gibb + * + * @since 1.0.0 */ public class AlwaysSampler implements Sampler { @Override diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/IsTracingSampler.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/IsTracingSampler.java index eedf79d50..a7699e9d8 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/IsTracingSampler.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/IsTracingSampler.java @@ -21,14 +21,19 @@ import org.springframework.cloud.sleuth.Span; import org.springframework.cloud.sleuth.SpanAccessor; /** + * {@link Sampler} that traces only if there is already some tracing going on. + * * @author Spencer Gibb + * + * @since 1.0.0 + * + * @see SpanAccessor#isTracing() */ public class IsTracingSampler implements Sampler { private SpanAccessor accessor; public IsTracingSampler(SpanAccessor accessor) { - super(); this.accessor = accessor; } diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/NeverSampler.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/NeverSampler.java index db6075e11..a2d8dc191 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/NeverSampler.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/NeverSampler.java @@ -20,7 +20,11 @@ import org.springframework.cloud.sleuth.Sampler; import org.springframework.cloud.sleuth.Span; /** + * {@link Sampler} that never traces + * * @author Spencer Gibb + * + * @since 1.0.0 */ public class NeverSampler implements Sampler { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSampler.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSampler.java index 03bbbdc44..fc2388275 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSampler.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSampler.java @@ -5,12 +5,15 @@ import org.springframework.cloud.sleuth.Span; /** * Sampler that based on the given percentage rate will allow sampling. + *

      * * A couple of assumptions have to take place in order for the algorithm to work properly: + *

      * *

        *
      • We're taking the TraceID into consideration for sampling to be consistent
        • - *
      • We apply the Zipkin algorithm to define whether we should sample or not (we're comparing against thresholdg) - https://github.com/openzipkin/zipkin-java/blob/master/zipkin/src/main/java/zipkin/Sampler.java
        • + *
      • We apply the Zipkin algorithm to define whether we should sample or not (we're comparing against threshold) + * - https://github.com/openzipkin/zipkin-java/blob/master/zipkin/src/main/java/zipkin/Sampler.java
        • *
      * * The value provided from SamplerConfiguration in terms of percentage is an estimation. It might occur that amount @@ -18,6 +21,8 @@ import org.springframework.cloud.sleuth.Span; * * @author Marcin Grzejszczak * @author Adrian Cole + * + * @since 1.0.0 */ public class PercentageBasedSampler implements Sampler { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerProperties.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerProperties.java index 19d506622..f5ae2383e 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerProperties.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerProperties.java @@ -3,8 +3,12 @@ package org.springframework.cloud.sleuth.sampler; import org.springframework.boot.context.properties.ConfigurationProperties; /** + * Properties related to sampling + * * @author Marcin Grzejszczak * @author Adrian Cole + * + * @since 1.0.0 */ @ConfigurationProperties("spring.sleuth.sampler") public class SamplerProperties { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/trace/DefaultTracer.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/trace/DefaultTracer.java index 09f40474b..11455089d 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/trace/DefaultTracer.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/trace/DefaultTracer.java @@ -32,7 +32,11 @@ import org.springframework.cloud.sleuth.util.ExceptionUtils; import org.springframework.context.ApplicationEventPublisher; /** + * Default implementation of {@link Tracer} + * * @author Spencer Gibb + * + * @since 1.0.0 */ public class DefaultTracer implements Tracer { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/trace/SpanContextHolder.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/trace/SpanContextHolder.java index e7b632e5e..81cab8539 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/trace/SpanContextHolder.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/trace/SpanContextHolder.java @@ -25,6 +25,8 @@ import org.springframework.core.NamedThreadLocal; * * @author Spencer Gibb * @author Dave Syer + * + * @since 1.0.0 */ class SpanContextHolder { diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/util/ExceptionUtils.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/util/ExceptionUtils.java index fb5483dd9..262d6196d 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/util/ExceptionUtils.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/util/ExceptionUtils.java @@ -19,13 +19,25 @@ package org.springframework.cloud.sleuth.util; import org.apache.commons.logging.Log; /** + * Utility class for logging exceptions. Useful for test purposes - + * when a warning message should be presented an exception can be thrown. + *

      + * The purpose of this class is not to throw exceptions from the user's code + * when there are some issues with tracing. + * * @author Spencer Gibb + * + * @since 1.0.0 */ -public abstract class ExceptionUtils { +public final class ExceptionUtils { private static final Log log = org.apache.commons.logging.LogFactory .getLog(ExceptionUtils.class); private static boolean fail = false; + private ExceptionUtils() { + throw new IllegalStateException("Utility class can't be instantiated"); + } + public static void warn(String msg) { if (fail) { throw new IllegalStateException(msg); diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/DiscoveryClientHostLocator.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/DiscoveryClientHostLocator.java index d22c21a10..f40b743ec 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/DiscoveryClientHostLocator.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/DiscoveryClientHostLocator.java @@ -29,6 +29,7 @@ import org.springframework.util.Assert; * * @author Dave Syer * + * @since 1.0.0 */ public class DiscoveryClientHostLocator implements HostLocator { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/Host.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/Host.java index f257f04fd..630829e9e 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/Host.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/Host.java @@ -23,8 +23,11 @@ import java.nio.ByteBuffer; import com.fasterxml.jackson.annotation.JsonInclude; /** + * Represents the host from which the span was sent + * * @author Dave Syer * + * @since 1.0.0 */ @JsonInclude(JsonInclude.Include.NON_NULL) public class Host { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/HostLocator.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/HostLocator.java index b1402ce31..098b4ef60 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/HostLocator.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/HostLocator.java @@ -19,11 +19,12 @@ package org.springframework.cloud.sleuth.stream; import org.springframework.cloud.sleuth.Span; /** - * Strategy for locating a "host" from a Spring Cloud Span (and whatever other + * Strategy for locating a {@link Host "host"} from a Spring Cloud Span (and whatever other * environment properties might be available). * * @author Dave Syer * + * @since 1.0.0 */ public interface HostLocator { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/ServerPropertiesHostLocator.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/ServerPropertiesHostLocator.java index ff84e0f02..f149daa31 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/ServerPropertiesHostLocator.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/ServerPropertiesHostLocator.java @@ -23,8 +23,17 @@ import org.springframework.context.event.EventListener; import org.springframework.util.Assert; /** + * A {@link HostLocator} that retrieves: + * + *

        + *
      • service name - either from {@link span#getProcessId()} or current application name
        • + *
      • address - from {@link ServerProperties}
        • + *
      • port - from lazily assigned port or {@link ServerProperties}
        • + *
      + * * @author Dave Syer * + * @since 1.0.0 */ public class ServerPropertiesHostLocator implements HostLocator { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthSink.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthSink.java index a42197773..4a064fd02 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthSink.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthSink.java @@ -28,6 +28,7 @@ import org.springframework.messaging.SubscribableChannel; * * @author Dave Syer * + * @since 1.0.0 */ public interface SleuthSink { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthSource.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthSource.java index d451d70bd..d2f86350b 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthSource.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthSource.java @@ -21,14 +21,15 @@ import org.springframework.messaging.MessageChannel; /** * Defines a message channel for instrumented applications to use to send span data to a - * message broker. The channel accepts data in the form of {@link Spans} to buffer - * multiple actual Span instances in a single message. A client app may occasionally drop + * message broker. The channel accepts data in the form of {@link spans} to buffer + * multiple actual span instances in a single message. A client app may occasionally drop * spans, and if it does it should attempt to account for and report the number dropped. * - * @see SleuthSink - * * @author Dave Syer * + * @since 1.0.0 + * + * @see SleuthSink */ public interface SleuthSource { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamAutoConfiguration.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamAutoConfiguration.java index 528a1e738..eb071e0ee 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamAutoConfiguration.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamAutoConfiguration.java @@ -44,12 +44,15 @@ import org.springframework.messaging.support.ChannelInterceptor; import org.springframework.messaging.support.ChannelInterceptorAdapter; /** - * Autoconfiguration for sending Spans over Spring Cloud Stream. This is for the producer + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * for sending spans over Spring Cloud Stream. This is for the producer * (via {@link SleuthSource}). A consumer can enable binding to {@link SleuthSink} and * receive the messages coming from the source (they have the same channel name so there * is no additional configuration to do by default). * * @author Dave Syer + * + * @since 1.0.0 */ @Configuration @EnableConfigurationProperties({SleuthStreamProperties.class, SamplerProperties.class}) diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamProperties.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamProperties.java index 0df21d393..34fff5c30 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamProperties.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamProperties.java @@ -19,7 +19,11 @@ package org.springframework.cloud.sleuth.stream; import org.springframework.boot.context.properties.ConfigurationProperties; /** + * Properties related to Sleuth Stream + * * @author Dave Syer + * + * @since 1.0.0 */ @ConfigurationProperties("spring.sleuth.stream") public class SleuthStreamProperties { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/Spans.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/Spans.java index 7c83a866d..a2c0b0fd9 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/Spans.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/Spans.java @@ -28,6 +28,7 @@ import com.fasterxml.jackson.annotation.JsonInclude; * * @author Dave Syer * + * @since 1.0.0 */ @JsonInclude(JsonInclude.Include.NON_DEFAULT) public class Spans { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/StreamEnvironmentPostProcessor.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/StreamEnvironmentPostProcessor.java index 1ba4ead0a..1920b064c 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/StreamEnvironmentPostProcessor.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/StreamEnvironmentPostProcessor.java @@ -37,8 +37,12 @@ import org.springframework.core.io.support.PathMatchingResourcePatternResolver; import org.springframework.core.io.support.PropertiesLoaderUtils; /** + * {@link EnvironmentPostProcessor} that sets the default properties for + * Sleuth Stream. + * * @author Dave Syer * + * @since 1.0.0 */ public class StreamEnvironmentPostProcessor implements EnvironmentPostProcessor { diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/StreamSpanListener.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/StreamSpanListener.java index ab972c52f..58732eed4 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/StreamSpanListener.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/StreamSpanListener.java @@ -40,6 +40,8 @@ import org.springframework.integration.annotation.MessageEndpoint; * A message source for spans. Also handles RPC flavoured annotations. * * @author Dave Syer + * + * @since 1.0.0 */ @MessageEndpoint public class StreamSpanListener { diff --git a/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/EnableZipkinStreamServer.java b/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/EnableZipkinStreamServer.java index 3d1d65b11..04ce5dfb0 100644 --- a/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/EnableZipkinStreamServer.java +++ b/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/EnableZipkinStreamServer.java @@ -25,6 +25,16 @@ import org.springframework.context.annotation.Import; import zipkin.server.EnableZipkinServer; +/** + * When enabled, instrumented apps will transport spans over a + * Spring Cloud Stream, for example RabbitMQ. + * + * @author Dave Syer + * + * @since 1.0.0 + * + * @see ZipkinMessageListener + */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @Documented diff --git a/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/SamplingZipkinSpanIterator.java b/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/SamplingZipkinSpanIterator.java index a6de8f992..7e6ff577a 100644 --- a/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/SamplingZipkinSpanIterator.java +++ b/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/SamplingZipkinSpanIterator.java @@ -32,6 +32,10 @@ import zipkin.Span.Builder; /** * This converts sleuth spans to zipkin ones, skipping invalid or unsampled. + * + * @author Adrian Cole + * + * @since 1.0.0 */ final class SamplingZipkinSpanIterator implements Iterator { diff --git a/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/ZipkinMessageListener.java b/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/ZipkinMessageListener.java index 67c1fa1d4..4446a93eb 100644 --- a/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/ZipkinMessageListener.java +++ b/spring-cloud-sleuth-zipkin-stream/src/main/java/org/springframework/cloud/sleuth/zipkin/stream/ZipkinMessageListener.java @@ -40,6 +40,16 @@ import zipkin.Sampler; import zipkin.Span.Builder; import zipkin.SpanStore; +/** + * A message listener that is turned on if Sleuth Stream is disabled. + * Asynchronously stores the received spans in a {@link SpanStore}. + * + * @author Dave Syer + * + * @since 1.0.0 + * + * @see NotSleuthStreamClient + */ @MessageEndpoint @Conditional(NotSleuthStreamClient.class) public class ZipkinMessageListener { @@ -77,9 +87,7 @@ public class ZipkinMessageListener { } /** - * Creates a list of Annotations that are present in sleuth Span object. - * - * @return list of Annotations that could be added to Zipkin Span. + * Adds binary annotations from the sleuth Span */ static void addZipkinBinaryAnnotations(Builder zipkinSpan, Span span, Endpoint endpoint) { diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/DiscoveryClientEndpointLocator.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/DiscoveryClientEndpointLocator.java index bd7abf065..f884bb69b 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/DiscoveryClientEndpointLocator.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/DiscoveryClientEndpointLocator.java @@ -28,6 +28,7 @@ import zipkin.Endpoint; * * @author Dave Syer * + * @since 1.0.0 */ public class DiscoveryClientEndpointLocator implements EndpointLocator { diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/EndpointLocator.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/EndpointLocator.java index 304bf1baf..b9d0ac810 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/EndpointLocator.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/EndpointLocator.java @@ -23,6 +23,7 @@ import zipkin.Endpoint; * * @author Dave Syer * + * @since 1.0.0 */ public interface EndpointLocator { diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/FallbackHavingEndpointLocator.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/FallbackHavingEndpointLocator.java index f22c04314..3159e238d 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/FallbackHavingEndpointLocator.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/FallbackHavingEndpointLocator.java @@ -7,6 +7,8 @@ import zipkin.Endpoint; /** * Endpoint locator that will try to call an endpoint via Discovery Client * and will fallback to Server Properties if an exception is thrown + * + * @since 1.0.0 */ public class FallbackHavingEndpointLocator implements EndpointLocator { diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporter.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporter.java index d7b4edc76..bf46da371 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporter.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporter.java @@ -25,6 +25,10 @@ import static java.util.concurrent.TimeUnit.SECONDS; /** * Submits spans using Zipkin's {@code POST /spans} endpoint. + * + * @author Adrian Cole + * + * @since 1.0.0 */ public final class HttpZipkinSpanReporter implements ZipkinSpanReporter, Flushable, Closeable { diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ServerPropertiesEndpointLocator.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ServerPropertiesEndpointLocator.java index 00b37dc22..a939f73c9 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ServerPropertiesEndpointLocator.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ServerPropertiesEndpointLocator.java @@ -24,8 +24,16 @@ import org.springframework.context.event.EventListener; import zipkin.Endpoint; /** + * {@link EndpointLocator} implementation that: + * + *
        + *
      • address - from {@link ServerProperties}
        • + *
      • port - from lazily assigned port or {@link ServerProperties}
        • + *
      + * * @author Dave Syer * + * @since 1.0.0 */ public class ServerPropertiesEndpointLocator implements EndpointLocator { diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinAutoConfiguration.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinAutoConfiguration.java index 2093e6ebf..b604f2b9a 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinAutoConfiguration.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinAutoConfiguration.java @@ -36,7 +36,13 @@ import org.springframework.context.annotation.Configuration; /** + * {@link org.springframework.boot.autoconfigure.EnableAutoConfiguration Auto-configuration} + * enables reporting to Zipkin via HTTP. Has a default {@link Sampler} set as + * {@link PercentageBasedSampler}. + * * @author Spencer Gibb + * + * @since 1.0.0 */ @Configuration @EnableConfigurationProperties({ZipkinProperties.class, SamplerProperties.class}) diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinProperties.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinProperties.java index f408f1951..eaa075beb 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinProperties.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinProperties.java @@ -19,7 +19,11 @@ package org.springframework.cloud.sleuth.zipkin; import org.springframework.boot.context.properties.ConfigurationProperties; /** + * Zipkin settings + * * @author Spencer Gibb + * + * @since 1.0.0 */ @ConfigurationProperties("spring.zipkin") public class ZipkinProperties { diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinSpanListener.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinSpanListener.java index ec7da9521..9b7aeef00 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinSpanListener.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinSpanListener.java @@ -37,7 +37,11 @@ import zipkin.Constants; import zipkin.Endpoint; /** + * Listener of Sleuth events. Reports to Zipkin via {@link ZipkinSpanReporter}. + * * @author Spencer Gibb + * + * @since 1.0.0 */ public class ZipkinSpanListener { private static final org.apache.commons.logging.Log log = org.apache.commons.logging.LogFactory @@ -171,9 +175,7 @@ public class ZipkinSpanListener { } /** - * Creates a list of Annotations that are present in sleuth Span object. - * - * @return list of Annotations that could be added to Zipkin Span. + * Adds binary annotation from the sleuth Span */ private void addZipkinBinaryAnnotations(zipkin.Span.Builder zipkinSpan, Span span, Endpoint endpoint) { diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinSpanReporter.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinSpanReporter.java index 536122291..8546449c4 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinSpanReporter.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinSpanReporter.java @@ -1,5 +1,12 @@ package org.springframework.cloud.sleuth.zipkin; +/** + * Contract for reporting Zipkin spans to Zipkin. + * + * @author Adrian Cole + * + * @since 1.0.0 + */ public interface ZipkinSpanReporter { /** * Receives completed spans from {@link ZipkinSpanListener} and submits them to a Zipkin diff --git a/spring-cloud-sleuth-zipkin/src/test/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporterTest.java b/spring-cloud-sleuth-zipkin/src/test/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporterTest.java index e8ebf0f7f..76796ae28 100644 --- a/spring-cloud-sleuth-zipkin/src/test/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporterTest.java +++ b/spring-cloud-sleuth-zipkin/src/test/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporterTest.java @@ -23,14 +23,14 @@ public class HttpZipkinSpanReporterTest { HttpZipkinSpanReporter reporter = new HttpZipkinSpanReporter( this.zipkin.httpUrl(), 0, this.spanReporterService); - @Test + @Test public void reportDoesntDoIO() throws Exception { this.reporter.report(span(1L, "foo")); assertThat(this.zipkin.httpRequestCount()).isZero(); } - @Test + @Test public void reportIncrementsAcceptedMetrics() throws Exception { this.reporter.report(span(1L, "foo")); @@ -38,7 +38,7 @@ public class HttpZipkinSpanReporterTest { assertThat(this.inMemorySpanCounter.getDroppedSpans()).isZero(); } - @Test + @Test public void dropsWhenQueueIsFull() throws Exception { for (int i = 0; i < 1001; i++) this.reporter.report(span(1L, "foo")); @@ -63,7 +63,7 @@ public class HttpZipkinSpanReporterTest { ); } - @Test + @Test public void incrementsDroppedSpansWhenServerErrors() throws Exception { this.zipkin.enqueueFailure(HttpFailure.sendErrorResponse(500, "Ouch")); @@ -75,7 +75,7 @@ public class HttpZipkinSpanReporterTest { assertThat(this.inMemorySpanCounter.getDroppedSpans()).isEqualTo(2); } - @Test + @Test public void incrementsDroppedSpansWhenServerDisconnects() throws Exception { this.zipkin.enqueueFailure(HttpFailure.disconnectDuringBody());