From f99fdab879046bad0acebef326279c4558ca0069 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Mon, 16 Jan 2017 15:48:32 -0500 Subject: [PATCH 01/17] Add retrolambda and update to brave 4 --- pom.xml | 39 +++++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/pom.xml b/pom.xml index 7442c62..bf924f4 100644 --- a/pom.xml +++ b/pom.xml @@ -30,6 +30,14 @@ UTF-8 UTF-8 + + 1.7 + java17 + + + 1.8 + 1.8 + ${project.basedir} @@ -86,12 +94,12 @@ io.zipkin.brave brave-core - 3.17.0 + 4.0.3 io.zipkin.brave brave-http - 3.17.0 + 4.0.3 junit @@ -113,9 +121,10 @@ true maven-compiler-plugin + 3.6.0 - 1.8 - 1.8 + ${maven.compiler.source} + ${maven.compiler.target} @@ -125,12 +134,30 @@ compile - 1.8 - 1.8 + ${maven.compiler.source} + ${maven.compiler.target} + + + + + + + net.orfjackal.retrolambda + retrolambda-maven-plugin + 2.4.0 + + + + process-main + + + ${main.java.version} + false + org.codehaus.mojo From b6848dbaf01548815fefcb0a2e5ee976db5f8e2d Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Mon, 16 Jan 2017 17:21:47 -0500 Subject: [PATCH 02/17] Adding stup classes using plain interfaces instead of abstract classes from opentracing-impl --- .../brave/features/opentracing/BraveSpan.java | 245 ++++++++++++++++++ .../opentracing/BraveSpanBuilder.java | 118 +++++++++ .../features/opentracing/BraveTracer.java | 94 +++++++ 3 files changed, 457 insertions(+) create mode 100644 src/main/java/brave/features/opentracing/BraveSpan.java create mode 100644 src/main/java/brave/features/opentracing/BraveSpanBuilder.java create mode 100644 src/main/java/brave/features/opentracing/BraveTracer.java diff --git a/src/main/java/brave/features/opentracing/BraveSpan.java b/src/main/java/brave/features/opentracing/BraveSpan.java new file mode 100644 index 0000000..31b0e65 --- /dev/null +++ b/src/main/java/brave/features/opentracing/BraveSpan.java @@ -0,0 +1,245 @@ +/** + * Copyright 2016-2017 The OpenZipkin Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License + * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + * or implied. See the License for the specific language governing permissions and limitations under + * the License. + */ +package brave.features.opentracing; + +import io.opentracing.Span; +import io.opentracing.SpanContext; + +import java.util.Map; + +public class BraveSpan implements Span { + /** + * Retrieve the associated SpanContext. + *

+ * This may be called at any time, including after calls to finish(). + * + * @return the SpanContext that encapsulates Span state that should propagate across process boundaries. + */ + @Override + public SpanContext context() { + return null; + } + + /** + * Sets the end timestamp to now and records the span. + *

+ *

With the exception of calls to Span.context(), this should be the last call made to the span instance, and to + * do otherwise leads to undefined behavior. + * + * @see Span#context() + */ + @Override + public void finish() { + + } + + /** + * Sets an explicit end timestamp and records the span. + *

+ *

With the exception of calls to Span.context(), this should be the last call made to the span instance, and to + * do otherwise leads to undefined behavior. + * + * @param finishMicros an explicit finish time, in microseconds since the epoch + * @see Span#context() + */ + @Override + public void finish(long finishMicros) { + + } + + @Override + public void close() { + + } + + /** + * Set a key:value tag on the Span. + * + * @param key + * @param value + */ + @Override + public Span setTag(String key, String value) { + return null; + } + + /** + * Same as {@link #setTag(String, String)}, but for boolean values. + * + * @param key + * @param value + */ + @Override + public Span setTag(String key, boolean value) { + return null; + } + + /** + * Same as {@link #setTag(String, String)}, but for numeric values. + * + * @param key + * @param value + */ + @Override + public Span setTag(String key, Number value) { + return null; + } + + /** + * Log key:value pairs to the Span with the current walltime timestamp. + *

+ *

CAUTIONARY NOTE: not all Tracer implementations support key:value log fields end-to-end. + * Caveat emptor. + *

+ *

A contrived example (using Guava, which is not required): + * 

{@code
+     * span.log(
+     * ImmutableMap.Builder()
+     * .put("event", "soft error")
+     * .put("type", "cache timeout")
+     * .put("waited.millis", 1500)
+     * .build());
+     * }
+ * + * @param fields key:value log fields. Tracer implementations should support String, numeric, and boolean values; + * some may also support arbitrary Objects. + * @return the Span, for chaining + * @see Span#log(String) + */ + @Override + public Span log(Map fields) { + return null; + } + + /** + * Like log(Map<String, Object>), but with an explicit timestamp. + *

+ *

CAUTIONARY NOTE: not all Tracer implementations support key:value log fields end-to-end. + * Caveat emptor. + * + * @param timestampMicroseconds The explicit timestamp for the log record. Must be greater than or equal to the + * Span's start timestamp. + * @param fields key:value log fields. Tracer implementations should support String, numeric, and boolean values; + * some may also support arbitrary Objects. + * @return the Span, for chaining + * @see Span#log(long, String) + */ + @Override + public Span log(long timestampMicroseconds, Map fields) { + return null; + } + + /** + * Record an event at the current walltime timestamp. + *

+ * Shorthand for + *

+ * 

{@code
+     * span.log(Collections.singletonMap("event", event));
+     * }
+ * + * @param event the event value; often a stable identifier for a moment in the Span lifecycle + * @return the Span, for chaining + */ + @Override + public Span log(String event) { + return null; + } + + /** + * Record an event at a specific timestamp. + *

+ * Shorthand for + *

+ * 

{@code
+     * span.log(timestampMicroseconds, Collections.singletonMap("event", event));
+     * }
+ * + * @param timestampMicroseconds The explicit timestamp for the log record. Must be greater than or equal to the + * Span's start timestamp. + * @param event the event value; often a stable identifier for a moment in the Span lifecycle + * @return the Span, for chaining + */ + @Override + public Span log(long timestampMicroseconds, String event) { + return null; + } + + /** + * Sets a baggage item in the Span (and its SpanContext) as a key/value pair. + *

+ * Baggage enables powerful distributed context propagation functionality where arbitrary application data can be + * carried along the full path of request execution throughout the system. + *

+ * Note 1: Baggage is only propagated to the future (recursive) children of this SpanContext. + *

+ * Note 2: Baggage is sent in-band with every subsequent local and remote calls, so this feature must be used with + * care. + * + * @param key + * @param value + * @return this Span instance, for chaining + */ + @Override + public Span setBaggageItem(String key, String value) { + return null; + } + + /** + * @param key + * @return the value of the baggage item identified by the given key, or null if no such item could be found + */ + @Override + public String getBaggageItem(String key) { + return null; + } + + /** + * Sets the string name for the logical operation this span represents. + * + * @param operationName + * @return this Span instance, for chaining + */ + @Override + public Span setOperationName(String operationName) { + return null; + } + + /** + * @param eventName + * @param payload + * @deprecated use {@link #log(Map)} like this + * {@code span.log(Map.of("event", "timeout"))} + * or + * {@code span.log(timestampMicroseconds, Map.of("event", "exception", "payload", stackTrace))} + */ + @Override + public Span log(String eventName, Object payload) { + return null; + } + + /** + * @param timestampMicroseconds + * @param eventName + * @param payload + * @deprecated use {@link #log(Map)} like this + * {@code span.log(timestampMicroseconds, Map.of("event", "timeout"))} + * or + * {@code span.log(timestampMicroseconds, Map.of("event", "exception", "payload", stackTrace))} + */ + @Override + public Span log(long timestampMicroseconds, String eventName, Object payload) { + return null; + } +} diff --git a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java new file mode 100644 index 0000000..488d6e8 --- /dev/null +++ b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java @@ -0,0 +1,118 @@ +/** + * Copyright 2016-2017 The OpenZipkin Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License + * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + * or implied. See the License for the specific language governing permissions and limitations under + * the License. + */ +package brave.features.opentracing; + +import io.opentracing.References; +import io.opentracing.Span; +import io.opentracing.SpanContext; +import io.opentracing.Tracer; + +import java.util.Map; + +public class BraveSpanBuilder implements Tracer.SpanBuilder { + /** + * A shorthand for addReference(References.CHILD_OF, parent). + * + * @param parent + */ + @Override + public Tracer.SpanBuilder asChildOf(SpanContext parent) { + return null; + } + + /** + * A shorthand for addReference(References.CHILD_OF, parent.context()). + * + * @param parent + */ + @Override + public Tracer.SpanBuilder asChildOf(Span parent) { + return null; + } + + /** + * Add a reference from the Span being built to a distinct (usually parent) Span. May be called multiple times to + * represent multiple such References. + * + * @param referenceType the reference type, typically one of the constants defined in References + * @param referencedContext the SpanContext being referenced; e.g., for a References.CHILD_OF referenceType, the + * referencedContext is the parent + * @see References + */ + @Override + public Tracer.SpanBuilder addReference(String referenceType, SpanContext referencedContext) { + return null; + } + + /** + * Same as {@link Span#setTag(String, String)}, but for the span being built. + * + * @param key + * @param value + */ + @Override + public Tracer.SpanBuilder withTag(String key, String value) { + return null; + } + + /** + * Same as {@link Span#setTag(String, String)}, but for the span being built. + * + * @param key + * @param value + */ + @Override + public Tracer.SpanBuilder withTag(String key, boolean value) { + return null; + } + + /** + * Same as {@link Span#setTag(String, String)}, but for the span being built. + * + * @param key + * @param value + */ + @Override + public Tracer.SpanBuilder withTag(String key, Number value) { + return null; + } + + /** + * Specify a timestamp of when the Span was started, represented in microseconds since epoch. + * + * @param microseconds + */ + @Override + public Tracer.SpanBuilder withStartTimestamp(long microseconds) { + return null; + } + + /** + * Returns the started Span. + */ + @Override + public Span start() { + return null; + } + + /** + * @return all zero or more baggage items propagating along with the associated Span + * @see Span#setBaggageItem(String, String) + * @see Span#getBaggageItem(String) + */ + @Override + public Iterable> baggageItems() { + return null; + } +} diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java new file mode 100644 index 0000000..02cc39e --- /dev/null +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -0,0 +1,94 @@ +/** + * Copyright 2016-2017 The OpenZipkin Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License + * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + * or implied. See the License for the specific language governing permissions and limitations under + * the License. + */ +package brave.features.opentracing; + +import io.opentracing.SpanContext; +import io.opentracing.Tracer; +import io.opentracing.propagation.Format; + +public class BraveTracer implements Tracer { + /** + * Return a new SpanBuilder for a Span with the given `operationName`. + *

+ *

You can override the operationName later via {@link Span#setOperationName(String)}. + *

+ *

A contrived example: + * 

{@code
+     * Tracer tracer = ...
+     *
+     * Span parentSpan = tracer.buildSpan("DoWork")
+     * .start();
+     *
+     * Span http = tracer.buildSpan("HandleHTTPRequest")
+     * .asChildOf(parentSpan.context())
+     * .withTag("user_agent", req.UserAgent)
+     * .withTag("lucky_number", 42)
+     * .start();
+     * }
+ * + * @param operationName + */ + @Override + public SpanBuilder buildSpan(String operationName) { + return null; + } + + /** + * Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries. + *

+ *

Example: + * 

{@code
+     * Tracer tracer = ...
+     * Span clientSpan = ...
+     * TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
+     * tracer.inject(span.context(), Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
+     * }
+ * + * @param spanContext the SpanContext instance to inject into the carrier + * @param format the Format of the carrier + * @param carrier the carrier for the SpanContext state. All Tracer.inject() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer. + * @see Format + * @see Format.Builtin + */ + @Override + public void inject(SpanContext spanContext, Format format, C carrier) { + + } + + /** + * Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary. + *

+ *

Example: + * 

{@code
+     * Tracer tracer = ...
+     * TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
+     * SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
+     * tracer.buildSpan('...').asChildOf(spanCtx).start();
+     * }
+ *

+ * If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an + * IllegalArgumentException. + * + * @param format the Format of the carrier + * @param carrier the carrier for the SpanContext state. All Tracer.extract() implementations must support + * io.opentracing.propagation.TextMap and java.nio.ByteBuffer. + * @return the SpanContext instance holding context to create a Span. + * @see Format + * @see Format.Builtin + */ + @Override + public SpanContext extract(Format format, C carrier) { + return null; + } +} From 886455f3c198be808cbdd1bbadf7734ac4cf77e4 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 12:00:52 -0500 Subject: [PATCH 03/17] Javadoc fixes. TODOs. BraveTracer calling BraveSpanBuilder. --- pom.xml | 7 +- .../brave/features/opentracing/BraveSpan.java | 133 +++--------------- .../opentracing/BraveSpanBuilder.java | 48 +++---- .../features/opentracing/BraveTracer.java | 79 ++++------- 4 files changed, 60 insertions(+), 207 deletions(-) diff --git a/pom.xml b/pom.xml index bf924f4..8558e72 100644 --- a/pom.xml +++ b/pom.xml @@ -88,7 +88,7 @@ io.opentracing - opentracing-impl + opentracing-api 0.20.7 @@ -96,11 +96,6 @@ brave-core 4.0.3 - - io.zipkin.brave - brave-http - 4.0.3 - junit junit diff --git a/src/main/java/brave/features/opentracing/BraveSpan.java b/src/main/java/brave/features/opentracing/BraveSpan.java index 31b0e65..48e0359 100644 --- a/src/main/java/brave/features/opentracing/BraveSpan.java +++ b/src/main/java/brave/features/opentracing/BraveSpan.java @@ -19,12 +19,9 @@ import java.util.Map; public class BraveSpan implements Span { + /** - * Retrieve the associated SpanContext. - *

- * This may be called at any time, including after calls to finish(). - * - * @return the SpanContext that encapsulates Span state that should propagate across process boundaries. + * {@inheritDoc} */ @Override public SpanContext context() { @@ -32,12 +29,7 @@ public SpanContext context() { } /** - * Sets the end timestamp to now and records the span. - *

- *

With the exception of calls to Span.context(), this should be the last call made to the span instance, and to - * do otherwise leads to undefined behavior. - * - * @see Span#context() + * {@inheritDoc} */ @Override public void finish() { @@ -45,29 +37,23 @@ public void finish() { } /** - * Sets an explicit end timestamp and records the span. - *

- *

With the exception of calls to Span.context(), this should be the last call made to the span instance, and to - * do otherwise leads to undefined behavior. - * - * @param finishMicros an explicit finish time, in microseconds since the epoch - * @see Span#context() + * {@inheritDoc} */ @Override public void finish(long finishMicros) { } + /** + * {@inheritDoc} + */ @Override public void close() { } /** - * Set a key:value tag on the Span. - * - * @param key - * @param value + * {@inheritDoc} */ @Override public Span setTag(String key, String value) { @@ -75,10 +61,7 @@ public Span setTag(String key, String value) { } /** - * Same as {@link #setTag(String, String)}, but for boolean values. - * - * @param key - * @param value + * {@inheritDoc} */ @Override public Span setTag(String key, boolean value) { @@ -86,10 +69,7 @@ public Span setTag(String key, boolean value) { } /** - * Same as {@link #setTag(String, String)}, but for numeric values. - * - * @param key - * @param value + * {@inheritDoc} */ @Override public Span setTag(String key, Number value) { @@ -97,25 +77,7 @@ public Span setTag(String key, Number value) { } /** - * Log key:value pairs to the Span with the current walltime timestamp. - *

- *

CAUTIONARY NOTE: not all Tracer implementations support key:value log fields end-to-end. - * Caveat emptor. - *

- *

A contrived example (using Guava, which is not required): - * 

{@code
-     * span.log(
-     * ImmutableMap.Builder()
-     * .put("event", "soft error")
-     * .put("type", "cache timeout")
-     * .put("waited.millis", 1500)
-     * .build());
-     * }
- * - * @param fields key:value log fields. Tracer implementations should support String, numeric, and boolean values; - * some may also support arbitrary Objects. - * @return the Span, for chaining - * @see Span#log(String) + * {@inheritDoc} */ @Override public Span log(Map fields) { @@ -123,17 +85,7 @@ public Span log(Map fields) { } /** - * Like log(Map<String, Object>), but with an explicit timestamp. - *

- *

CAUTIONARY NOTE: not all Tracer implementations support key:value log fields end-to-end. - * Caveat emptor. - * - * @param timestampMicroseconds The explicit timestamp for the log record. Must be greater than or equal to the - * Span's start timestamp. - * @param fields key:value log fields. Tracer implementations should support String, numeric, and boolean values; - * some may also support arbitrary Objects. - * @return the Span, for chaining - * @see Span#log(long, String) + * {@inheritDoc} */ @Override public Span log(long timestampMicroseconds, Map fields) { @@ -141,16 +93,7 @@ public Span log(long timestampMicroseconds, Map fields) { } /** - * Record an event at the current walltime timestamp. - *

- * Shorthand for - *

- * 

{@code
-     * span.log(Collections.singletonMap("event", event));
-     * }
- * - * @param event the event value; often a stable identifier for a moment in the Span lifecycle - * @return the Span, for chaining + * {@inheritDoc} */ @Override public Span log(String event) { @@ -158,18 +101,7 @@ public Span log(String event) { } /** - * Record an event at a specific timestamp. - *

- * Shorthand for - *

- * 

{@code
-     * span.log(timestampMicroseconds, Collections.singletonMap("event", event));
-     * }
- * - * @param timestampMicroseconds The explicit timestamp for the log record. Must be greater than or equal to the - * Span's start timestamp. - * @param event the event value; often a stable identifier for a moment in the Span lifecycle - * @return the Span, for chaining + * {@inheritDoc} */ @Override public Span log(long timestampMicroseconds, String event) { @@ -177,19 +109,7 @@ public Span log(long timestampMicroseconds, String event) { } /** - * Sets a baggage item in the Span (and its SpanContext) as a key/value pair. - *

- * Baggage enables powerful distributed context propagation functionality where arbitrary application data can be - * carried along the full path of request execution throughout the system. - *

- * Note 1: Baggage is only propagated to the future (recursive) children of this SpanContext. - *

- * Note 2: Baggage is sent in-band with every subsequent local and remote calls, so this feature must be used with - * care. - * - * @param key - * @param value - * @return this Span instance, for chaining + * {@inheritDoc} */ @Override public Span setBaggageItem(String key, String value) { @@ -197,8 +117,7 @@ public Span setBaggageItem(String key, String value) { } /** - * @param key - * @return the value of the baggage item identified by the given key, or null if no such item could be found + * {@inheritDoc} */ @Override public String getBaggageItem(String key) { @@ -206,10 +125,7 @@ public String getBaggageItem(String key) { } /** - * Sets the string name for the logical operation this span represents. - * - * @param operationName - * @return this Span instance, for chaining + * {@inheritDoc} */ @Override public Span setOperationName(String operationName) { @@ -217,12 +133,7 @@ public Span setOperationName(String operationName) { } /** - * @param eventName - * @param payload - * @deprecated use {@link #log(Map)} like this - * {@code span.log(Map.of("event", "timeout"))} - * or - * {@code span.log(timestampMicroseconds, Map.of("event", "exception", "payload", stackTrace))} + * {@inheritDoc} */ @Override public Span log(String eventName, Object payload) { @@ -230,13 +141,7 @@ public Span log(String eventName, Object payload) { } /** - * @param timestampMicroseconds - * @param eventName - * @param payload - * @deprecated use {@link #log(Map)} like this - * {@code span.log(timestampMicroseconds, Map.of("event", "timeout"))} - * or - * {@code span.log(timestampMicroseconds, Map.of("event", "exception", "payload", stackTrace))} + * {@inheritDoc} */ @Override public Span log(long timestampMicroseconds, String eventName, Object payload) { diff --git a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java index 488d6e8..7f151eb 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java +++ b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java @@ -21,10 +21,15 @@ import java.util.Map; public class BraveSpanBuilder implements Tracer.SpanBuilder { + + private String operationName; + + public BraveSpanBuilder(String operationName) { + this.operationName = operationName; + } + /** - * A shorthand for addReference(References.CHILD_OF, parent). - * - * @param parent + * {@inheritDoc} */ @Override public Tracer.SpanBuilder asChildOf(SpanContext parent) { @@ -32,9 +37,7 @@ public Tracer.SpanBuilder asChildOf(SpanContext parent) { } /** - * A shorthand for addReference(References.CHILD_OF, parent.context()). - * - * @param parent + * {@inheritDoc} */ @Override public Tracer.SpanBuilder asChildOf(Span parent) { @@ -42,13 +45,7 @@ public Tracer.SpanBuilder asChildOf(Span parent) { } /** - * Add a reference from the Span being built to a distinct (usually parent) Span. May be called multiple times to - * represent multiple such References. - * - * @param referenceType the reference type, typically one of the constants defined in References - * @param referencedContext the SpanContext being referenced; e.g., for a References.CHILD_OF referenceType, the - * referencedContext is the parent - * @see References + * {@inheritDoc} */ @Override public Tracer.SpanBuilder addReference(String referenceType, SpanContext referencedContext) { @@ -56,10 +53,7 @@ public Tracer.SpanBuilder addReference(String referenceType, SpanContext referen } /** - * Same as {@link Span#setTag(String, String)}, but for the span being built. - * - * @param key - * @param value + * {@inheritDoc} */ @Override public Tracer.SpanBuilder withTag(String key, String value) { @@ -67,10 +61,7 @@ public Tracer.SpanBuilder withTag(String key, String value) { } /** - * Same as {@link Span#setTag(String, String)}, but for the span being built. - * - * @param key - * @param value + * {@inheritDoc} */ @Override public Tracer.SpanBuilder withTag(String key, boolean value) { @@ -78,10 +69,7 @@ public Tracer.SpanBuilder withTag(String key, boolean value) { } /** - * Same as {@link Span#setTag(String, String)}, but for the span being built. - * - * @param key - * @param value + * {@inheritDoc} */ @Override public Tracer.SpanBuilder withTag(String key, Number value) { @@ -89,9 +77,7 @@ public Tracer.SpanBuilder withTag(String key, Number value) { } /** - * Specify a timestamp of when the Span was started, represented in microseconds since epoch. - * - * @param microseconds + * {@inheritDoc} */ @Override public Tracer.SpanBuilder withStartTimestamp(long microseconds) { @@ -99,7 +85,7 @@ public Tracer.SpanBuilder withStartTimestamp(long microseconds) { } /** - * Returns the started Span. + * {@inheritDoc} */ @Override public Span start() { @@ -107,9 +93,7 @@ public Span start() { } /** - * @return all zero or more baggage items propagating along with the associated Span - * @see Span#setBaggageItem(String, String) - * @see Span#getBaggageItem(String) + * {@inheritDoc} */ @Override public Iterable> baggageItems() { diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java index 02cc39e..ac3124b 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -13,82 +13,51 @@ */ package brave.features.opentracing; +import com.github.kristofa.brave.Brave; +import com.github.kristofa.brave.InheritableServerClientAndLocalSpanState; +import com.twitter.zipkin.gen.Endpoint; import io.opentracing.SpanContext; import io.opentracing.Tracer; import io.opentracing.propagation.Format; public class BraveTracer implements Tracer { + + final Brave brave; + + public BraveTracer() { + this(Endpoint.create("unknown", 0)); + } + + public BraveTracer(Endpoint endpoint) { + this(new Brave.Builder(new InheritableServerClientAndLocalSpanState(endpoint))); + } + + public BraveTracer(Brave.Builder builder) { + brave = builder.build(); + } + /** - * Return a new SpanBuilder for a Span with the given `operationName`. - *

- *

You can override the operationName later via {@link Span#setOperationName(String)}. - *

- *

A contrived example: - * 

{@code
-     * Tracer tracer = ...
-     *
-     * Span parentSpan = tracer.buildSpan("DoWork")
-     * .start();
-     *
-     * Span http = tracer.buildSpan("HandleHTTPRequest")
-     * .asChildOf(parentSpan.context())
-     * .withTag("user_agent", req.UserAgent)
-     * .withTag("lucky_number", 42)
-     * .start();
-     * }
- * - * @param operationName + * {@inheritDoc} */ @Override public SpanBuilder buildSpan(String operationName) { - return null; + return new BraveSpanBuilder(operationName); } /** - * Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries. - *

- *

Example: - * 

{@code
-     * Tracer tracer = ...
-     * Span clientSpan = ...
-     * TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
-     * tracer.inject(span.context(), Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
-     * }
- * - * @param spanContext the SpanContext instance to inject into the carrier - * @param format the Format of the carrier - * @param carrier the carrier for the SpanContext state. All Tracer.inject() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer. - * @see Format - * @see Format.Builtin + * {@inheritDoc} */ @Override public void inject(SpanContext spanContext, Format format, C carrier) { - + // TODO How to handle `Formats` and `Carriers` for brave } /** - * Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary. - *

- *

Example: - * 

{@code
-     * Tracer tracer = ...
-     * TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
-     * SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
-     * tracer.buildSpan('...').asChildOf(spanCtx).start();
-     * }
- *

- * If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an - * IllegalArgumentException. - * - * @param format the Format of the carrier - * @param carrier the carrier for the SpanContext state. All Tracer.extract() implementations must support - * io.opentracing.propagation.TextMap and java.nio.ByteBuffer. - * @return the SpanContext instance holding context to create a Span. - * @see Format - * @see Format.Builtin + * {@inheritDoc} */ @Override public SpanContext extract(Format format, C carrier) { + // TODO How to handle `Formats` and `Carriers` for brave return null; } } From d9d6cf78fd651afb1e7f6ed5c1bbbf89f311a31b Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 12:50:46 -0500 Subject: [PATCH 04/17] I like this better --- pom.xml | 2 +- .../opentracing/BraveSpanBuilder.java | 8 ++-- .../opentracing/BraveSpanContext.java | 43 +++++++++++++++++++ .../features/opentracing/BraveTracer.java | 36 +++++++--------- 4 files changed, 65 insertions(+), 24 deletions(-) create mode 100644 src/main/java/brave/features/opentracing/BraveSpanContext.java diff --git a/pom.xml b/pom.xml index 8558e72..4dbba4d 100644 --- a/pom.xml +++ b/pom.xml @@ -93,7 +93,7 @@ io.zipkin.brave - brave-core + brave 4.0.3 diff --git a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java index 7f151eb..3fbe2a9 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java +++ b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java @@ -13,7 +13,6 @@ */ package brave.features.opentracing; -import io.opentracing.References; import io.opentracing.Span; import io.opentracing.SpanContext; import io.opentracing.Tracer; @@ -22,9 +21,11 @@ public class BraveSpanBuilder implements Tracer.SpanBuilder { + private brave.Tracer brave; private String operationName; - public BraveSpanBuilder(String operationName) { + public BraveSpanBuilder(brave.Tracer brave, String operationName) { + this.brave = brave; this.operationName = operationName; } @@ -33,7 +34,7 @@ public BraveSpanBuilder(String operationName) { */ @Override public Tracer.SpanBuilder asChildOf(SpanContext parent) { - return null; + return this; } /** @@ -89,6 +90,7 @@ public Tracer.SpanBuilder withStartTimestamp(long microseconds) { */ @Override public Span start() { + String component = "unknown"; return null; } diff --git a/src/main/java/brave/features/opentracing/BraveSpanContext.java b/src/main/java/brave/features/opentracing/BraveSpanContext.java new file mode 100644 index 0000000..b64fdb2 --- /dev/null +++ b/src/main/java/brave/features/opentracing/BraveSpanContext.java @@ -0,0 +1,43 @@ +package brave.features.opentracing; + +import brave.propagation.TraceContext; +import io.opentracing.SpanContext; + +import java.util.Collections; +import java.util.Map; + +/** + * Created by ddcbdevins on 1/24/17. + */ +public class BraveSpanContext implements SpanContext { + + private TraceContext traceContext; + private boolean extracted; + + static SpanContext wrap(TraceContext traceContext) { + return new BraveSpanContext(); + } + + public TraceContext unwrap() { + return traceContext; + } + + /** + * @return all zero or more baggage items propagating along with the associated Span + * @see Span#setBaggageItem(String, String) + * @see Span#getBaggageItem(String) + */ + @Override + public Iterable> baggageItems() { + // TODO brave doesn't seem to support baggage yet + return Collections.EMPTY_LIST; + } + + public boolean isExtracted() { + return extracted; + } + + public void setExtracted(boolean extracted) { + this.extracted = extracted; + } +} diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java index ac3124b..22c1d61 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -13,35 +13,24 @@ */ package brave.features.opentracing; -import com.github.kristofa.brave.Brave; -import com.github.kristofa.brave.InheritableServerClientAndLocalSpanState; -import com.twitter.zipkin.gen.Endpoint; +import brave.propagation.TraceContext; +import brave.propagation.TraceContextOrSamplingFlags; import io.opentracing.SpanContext; import io.opentracing.Tracer; import io.opentracing.propagation.Format; public class BraveTracer implements Tracer { - final Brave brave; - - public BraveTracer() { - this(Endpoint.create("unknown", 0)); - } - - public BraveTracer(Endpoint endpoint) { - this(new Brave.Builder(new InheritableServerClientAndLocalSpanState(endpoint))); - } - - public BraveTracer(Brave.Builder builder) { - brave = builder.build(); - } + private brave.Tracer brave; + private TraceContext.Injector injector; + private TraceContext.Extractor extractor; /** * {@inheritDoc} */ @Override public SpanBuilder buildSpan(String operationName) { - return new BraveSpanBuilder(operationName); + return new BraveSpanBuilder(brave, operationName); } /** @@ -49,7 +38,9 @@ public SpanBuilder buildSpan(String operationName) { */ @Override public void inject(SpanContext spanContext, Format format, C carrier) { - // TODO How to handle `Formats` and `Carriers` for brave + // TODO select an injector for the specific FORMAT + + injector.inject(((BraveSpanContext) spanContext).unwrap(), carrier); } /** @@ -57,7 +48,12 @@ public void inject(SpanContext spanContext, Format format, C carrier) { */ @Override public SpanContext extract(Format format, C carrier) { - // TODO How to handle `Formats` and `Carriers` for brave - return null; + // TODO select an extractor for the specific FORMAT + + TraceContextOrSamplingFlags contextOrSamplingFlags = extractor.extract(carrier); + + return contextOrSamplingFlags.context() != null + ? BraveSpanContext.wrap(contextOrSamplingFlags.context()) + : null; } } From ebd389215fbf8d44b7a6ec79b2a3a4de77211516 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 14:20:08 -0500 Subject: [PATCH 05/17] Copied the existing impl out of the io.zipkin.brave:brave tests --- pom.xml | 7 + .../brave/features/opentracing/BraveSpan.java | 17 ++ .../opentracing/BraveSpanBuilder.java | 45 +++-- .../opentracing/BraveSpanContext.java | 28 +-- .../features/opentracing/BraveTracer.java | 81 +++++++-- .../java/io/opentracing/impl/BraveSpan.java | 93 ---------- .../io/opentracing/impl/BraveSpanBuilder.java | 160 ------------------ .../io/opentracing/impl/BraveSpanContext.java | 23 --- .../java/io/opentracing/impl/BraveTracer.java | 143 ---------------- 9 files changed, 136 insertions(+), 461 deletions(-) delete mode 100644 src/main/java/io/opentracing/impl/BraveSpan.java delete mode 100644 src/main/java/io/opentracing/impl/BraveSpanBuilder.java delete mode 100644 src/main/java/io/opentracing/impl/BraveSpanContext.java delete mode 100644 src/main/java/io/opentracing/impl/BraveTracer.java diff --git a/pom.xml b/pom.xml index 4dbba4d..9ee4496 100644 --- a/pom.xml +++ b/pom.xml @@ -91,11 +91,18 @@ opentracing-api 0.20.7 + io.zipkin.brave brave 4.0.3 + + io.zipkin.brave + brave-core + 4.0.3 + + junit junit diff --git a/src/main/java/brave/features/opentracing/BraveSpan.java b/src/main/java/brave/features/opentracing/BraveSpan.java index 48e0359..d994508 100644 --- a/src/main/java/brave/features/opentracing/BraveSpan.java +++ b/src/main/java/brave/features/opentracing/BraveSpan.java @@ -20,6 +20,23 @@ public class BraveSpan implements Span { + static BraveSpan wrap(brave.Span span) { + if (span == null) throw new NullPointerException("span == null"); + return new BraveSpan(span); + } + + final brave.Span unwrap() { + return delegate; + } + + final brave.Span delegate; + final SpanContext context; + + private BraveSpan(brave.Span delegate) { + this.delegate = delegate; + this.context = BraveSpanContext.wrap(delegate.context()); + } + /** * {@inheritDoc} */ diff --git a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java index 3fbe2a9..ca7aa0c 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java +++ b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java @@ -13,16 +13,25 @@ */ package brave.features.opentracing; +import brave.propagation.TraceContext; +import io.opentracing.References; import io.opentracing.Span; import io.opentracing.SpanContext; import io.opentracing.Tracer; +import java.util.Collections; +import java.util.LinkedHashMap; import java.util.Map; public class BraveSpanBuilder implements Tracer.SpanBuilder { private brave.Tracer brave; + private String operationName; + private final Map tags = new LinkedHashMap<>(); + + long timestamp; + private TraceContext parent; public BraveSpanBuilder(brave.Tracer brave, String operationName) { this.brave = brave; @@ -34,7 +43,7 @@ public BraveSpanBuilder(brave.Tracer brave, String operationName) { */ @Override public Tracer.SpanBuilder asChildOf(SpanContext parent) { - return this; + return addReference(References.CHILD_OF, parent); } /** @@ -42,7 +51,7 @@ public Tracer.SpanBuilder asChildOf(SpanContext parent) { */ @Override public Tracer.SpanBuilder asChildOf(Span parent) { - return null; + return asChildOf(parent.context()); } /** @@ -50,7 +59,13 @@ public Tracer.SpanBuilder asChildOf(Span parent) { */ @Override public Tracer.SpanBuilder addReference(String referenceType, SpanContext referencedContext) { - return null; + if (parent != null) { + return this; + } + if (References.CHILD_OF.equals(referenceType) || References.FOLLOWS_FROM.equals(referenceType)) { + this.parent = ((BraveSpanContext) referencedContext).unwrap(); + } + return this; } /** @@ -58,7 +73,8 @@ public Tracer.SpanBuilder addReference(String referenceType, SpanContext referen */ @Override public Tracer.SpanBuilder withTag(String key, String value) { - return null; + tags.put(key, value); + return this; } /** @@ -66,7 +82,7 @@ public Tracer.SpanBuilder withTag(String key, String value) { */ @Override public Tracer.SpanBuilder withTag(String key, boolean value) { - return null; + return withTag(key, Boolean.toString(value)); } /** @@ -74,7 +90,7 @@ public Tracer.SpanBuilder withTag(String key, boolean value) { */ @Override public Tracer.SpanBuilder withTag(String key, Number value) { - return null; + return withTag(key, value.toString()); } /** @@ -82,7 +98,8 @@ public Tracer.SpanBuilder withTag(String key, Number value) { */ @Override public Tracer.SpanBuilder withStartTimestamp(long microseconds) { - return null; + this.timestamp = microseconds; + return this; } /** @@ -90,8 +107,15 @@ public Tracer.SpanBuilder withStartTimestamp(long microseconds) { */ @Override public Span start() { - String component = "unknown"; - return null; + brave.Span span = parent == null ? brave.newTrace() : brave.newChild(parent); + if (operationName != null) span.name(operationName); + for (Map.Entry tag : tags.entrySet()) { + span.tag(tag.getKey(), tag.getValue()); + } + if (timestamp != 0) { + return BraveSpan.wrap(span.start(timestamp)); + } + return BraveSpan.wrap(span.start()); } /** @@ -99,6 +123,7 @@ public Span start() { */ @Override public Iterable> baggageItems() { - return null; + // brave doesn't support baggage + return Collections.EMPTY_SET; } } diff --git a/src/main/java/brave/features/opentracing/BraveSpanContext.java b/src/main/java/brave/features/opentracing/BraveSpanContext.java index b64fdb2..ea7e7ad 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanContext.java +++ b/src/main/java/brave/features/opentracing/BraveSpanContext.java @@ -6,38 +6,26 @@ import java.util.Collections; import java.util.Map; -/** - * Created by ddcbdevins on 1/24/17. - */ public class BraveSpanContext implements SpanContext { private TraceContext traceContext; - private boolean extracted; - static SpanContext wrap(TraceContext traceContext) { - return new BraveSpanContext(); + static BraveSpanContext wrap(TraceContext traceContext) { + BraveSpanContext context = new BraveSpanContext(); + context.traceContext = traceContext; + return context; } - public TraceContext unwrap() { + final TraceContext unwrap() { return traceContext; } /** - * @return all zero or more baggage items propagating along with the associated Span - * @see Span#setBaggageItem(String, String) - * @see Span#getBaggageItem(String) + * {@inheritDoc} */ @Override public Iterable> baggageItems() { - // TODO brave doesn't seem to support baggage yet - return Collections.EMPTY_LIST; - } - - public boolean isExtracted() { - return extracted; - } - - public void setExtracted(boolean extracted) { - this.extracted = extracted; + // brave doesn't support baggage + return Collections.EMPTY_SET; } } diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java index 22c1d61..c09ba52 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -13,24 +13,47 @@ */ package brave.features.opentracing; +import brave.internal.Nullable; +import brave.propagation.Propagation; import brave.propagation.TraceContext; import brave.propagation.TraceContextOrSamplingFlags; +import com.github.kristofa.brave.Brave; +import com.github.kristofa.brave.TracerAdapter; import io.opentracing.SpanContext; import io.opentracing.Tracer; import io.opentracing.propagation.Format; +import io.opentracing.propagation.TextMap; + +import java.util.Iterator; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; public class BraveTracer implements Tracer { - private brave.Tracer brave; - private TraceContext.Injector injector; - private TraceContext.Extractor extractor; + static final List PROPAGATION_KEYS = Propagation.B3_STRING.keys(); + static final TraceContext.Injector INJECTOR = Propagation.B3_STRING.injector(TextMap::put); + static final TraceContext.Extractor EXTRACTOR = Propagation.B3_STRING.extractor(TextMapView::get); + + private brave.Tracer brave4; + private Brave brave3; + + static BraveTracer wrap(brave.Tracer brave4) { + if (brave4 == null) throw new NullPointerException("brave tracer == null"); + return new BraveTracer(brave4); + } + + BraveTracer(brave.Tracer brave4) { + this.brave4 = brave4; + this.brave3 = TracerAdapter.newBrave(this.brave4); + } /** * {@inheritDoc} */ @Override public SpanBuilder buildSpan(String operationName) { - return new BraveSpanBuilder(brave, operationName); + return new BraveSpanBuilder(brave4, operationName); } /** @@ -38,9 +61,11 @@ public SpanBuilder buildSpan(String operationName) { */ @Override public void inject(SpanContext spanContext, Format format, C carrier) { - // TODO select an injector for the specific FORMAT - - injector.inject(((BraveSpanContext) spanContext).unwrap(), carrier); + if (format != Format.Builtin.HTTP_HEADERS) { + throw new UnsupportedOperationException(format + " != Format.Builtin.HTTP_HEADERS"); + } + TraceContext traceContext = ((BraveSpanContext) spanContext).unwrap(); + INJECTOR.inject(traceContext, (TextMap) carrier); } /** @@ -48,12 +73,44 @@ public void inject(SpanContext spanContext, Format format, C carrier) { */ @Override public SpanContext extract(Format format, C carrier) { - // TODO select an extractor for the specific FORMAT + if (format != Format.Builtin.HTTP_HEADERS) { + throw new UnsupportedOperationException(format.toString()); + } + TraceContextOrSamplingFlags result = + EXTRACTOR.extract(new TextMapView(PROPAGATION_KEYS, (TextMap) carrier)); + TraceContext context = result.context() != null + ? result.context().toBuilder().shared(true).build() + : brave4.newTrace(result.samplingFlags()).context(); + return BraveSpanContext.wrap(context); + } + + + /** + * Eventhough TextMap is named like Map, it doesn't have a retrieve-by-key method + */ + static final class TextMapView { + final Iterator> input; + final Map cache = new LinkedHashMap<>(); + final List fields; - TraceContextOrSamplingFlags contextOrSamplingFlags = extractor.extract(carrier); + TextMapView(List fields, TextMap input) { + this.fields = fields; + this.input = input.iterator(); + } - return contextOrSamplingFlags.context() != null - ? BraveSpanContext.wrap(contextOrSamplingFlags.context()) - : null; + @Nullable + String get(String key) { + String result = cache.get(key); + if (result != null) return result; + while (input.hasNext()) { + Map.Entry next = input.next(); + if (next.getKey().equals(key)) { + return next.getValue(); + } else if (fields.contains(next.getKey())) { + cache.put(next.getKey(), next.getValue()); + } + } + return null; + } } } diff --git a/src/main/java/io/opentracing/impl/BraveSpan.java b/src/main/java/io/opentracing/impl/BraveSpan.java deleted file mode 100644 index 480c8e2..0000000 --- a/src/main/java/io/opentracing/impl/BraveSpan.java +++ /dev/null @@ -1,93 +0,0 @@ -/** - * Copyright 2016-2017 The OpenZipkin Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under the License - * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express - * or implied. See the License for the specific language governing permissions and limitations under - * the License. - */ -package io.opentracing.impl; - -import java.time.Instant; -import java.util.Optional; -import java.util.concurrent.TimeUnit; - -import com.github.kristofa.brave.Brave; -import com.github.kristofa.brave.ClientTracer; -import com.github.kristofa.brave.ServerTracer; -import com.github.kristofa.brave.SpanId; - - -final class BraveSpan extends AbstractSpan implements BraveSpanContext { - - final SpanId spanId; - final Optional parent; - final Optional serverTracer; - - private final Brave brave; - private Optional clientTracer = Optional.empty(); - - public static BraveSpan create( - Brave brave, - String operationName, - Optional parent, - Instant start, - Optional serverTracer) { - - return new BraveSpan(brave, operationName, parent, start, serverTracer); - } - - private BraveSpan( - Brave brave, - String operationName, - Optional parent, - Instant start, - Optional serverTracer) { - - super(operationName, start); - this.brave = brave; - this.parent = parent; - this.serverTracer = serverTracer; - - this.spanId = brave.localTracer().startNewSpan( - "jvm", - operationName, - TimeUnit.SECONDS.toMicros(start.getEpochSecond()) + TimeUnit.NANOSECONDS.toMicros(start.getNano())); - } - - @Override - public void finish() { - super.finish(); - brave.localTracer().finishSpan(); - if (clientTracer.isPresent()) { - clientTracer.get().setClientReceived(); - } - if (serverTracer.isPresent()) { - serverTracer.get().setServerSend(); - } - } - - void setClientTracer(ClientTracer clientTracer) { - this.clientTracer = Optional.of(clientTracer); - } - - @Override - public long getContextTraceId() { - return spanId.traceId; - } - - @Override - public long getContextSpanId() { - return spanId.spanId; - } - - @Override - public Long getContextParentSpanId() { - return spanId.parentId; - } -} diff --git a/src/main/java/io/opentracing/impl/BraveSpanBuilder.java b/src/main/java/io/opentracing/impl/BraveSpanBuilder.java deleted file mode 100644 index 5d58654..0000000 --- a/src/main/java/io/opentracing/impl/BraveSpanBuilder.java +++ /dev/null @@ -1,160 +0,0 @@ -/** - * Copyright 2016-2017 The OpenZipkin Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under the License - * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express - * or implied. See the License for the specific language governing permissions and limitations under - * the License. - */ -package io.opentracing.impl; - -import java.util.Optional; - -import com.github.kristofa.brave.Brave; -import com.github.kristofa.brave.IdConversion; -import com.github.kristofa.brave.ServerTracer; -import com.github.kristofa.brave.http.BraveHttpHeaders; -import io.opentracing.References; - - -final class BraveSpanBuilder extends AbstractSpanBuilder implements BraveSpanContext { - - Long traceId = null; - Long parentSpanId = null; - ServerTracer serverTracer = null; - - private final Brave brave; - - static BraveSpanBuilder create(Brave brave, String operationName) { - return new BraveSpanBuilder(brave, operationName); - } - - private BraveSpanBuilder(Brave brave, String operationName) { - super(operationName); - this.brave = brave; - } - - @Override - protected BraveSpan createSpan() { - BraveSpanContext parent = getParent(); - if (null != parent) { - traceId = parent.getContextTraceId(); - parentSpanId = parent.getContextSpanId(); - Long parentParentId = parent.getContextParentSpanId(); - - // push this into the serverSpanState as the current span as that is where new localSpans find their parents - brave.serverTracer().setStateCurrentTrace(traceId, parentSpanId, parentParentId, operationName); - } - if (null == traceId && null == parentSpanId) { - brave.localSpanThreadBinder().setCurrentSpan(null); - brave.serverTracer().clearCurrentSpan(); - } - - BraveSpan span = BraveSpan.create( - brave, - operationName, - Optional.ofNullable(parent), - start, - Optional.ofNullable(serverTracer)); - - // push this into the serverSpanState as the current span as that is where new localSpans find their parents - brave.serverTracer().setStateCurrentTrace( - span.spanId.traceId, - span.spanId.spanId, - span.spanId.parentId, - span.getOperationName()); - - assert (null == traceId && null == parentSpanId) || (null != traceId && null != parentSpanId); - assert null == traceId || span.spanId.traceId == traceId; - assert null == parentSpanId || parentSpanId.equals(span.spanId.nullableParentId()); - - if (null == traceId && null == parentSpanId) { - // called through tracer.buildSpan(..), as opposed to builder.extract(..) - brave.serverTracer().setStateCurrentTrace( - span.spanId.traceId, - span.spanId.spanId, - span.spanId.nullableParentId(), - operationName); - } - - return span; - } - - BraveSpanBuilder withServerTracer(ServerTracer serverTracer) { - this.serverTracer = serverTracer; - return this; - } - - /** @Nullable **/ - private BraveSpanContext getParent() { - for (Reference reference : references) { - if (References.CHILD_OF.equals(reference.getReferenceType())) { - return (BraveSpanContext) reference.getReferredTo(); - } - } - return null; - } - - @Override - boolean isTraceState(String key, Object value) { - return null != valueOf(key); - } - - private static BraveHttpHeaders valueOf(String key) { - for (BraveHttpHeaders header : BraveHttpHeaders.values()) { - if (header.getName().equalsIgnoreCase(key)) { - return header; - } - } - return null; - } - - @Override - BraveSpanBuilder withStateItem(String key, Object value) { - BraveHttpHeaders header = valueOf(key); - if (null == header) { - throw new IllegalArgumentException(key + " is not a valid brave header"); - } - switch (header) { - case TraceId: - traceId = value instanceof Number - ? ((Number)value).longValue() - : IdConversion.convertToLong(value.toString()); - break; - case SpanId: - parentSpanId = value instanceof Number - ? ((Number)value).longValue() - : IdConversion.convertToLong(value.toString()); - break; - case ParentSpanId: - if (null == parentSpanId) { - parentSpanId = value instanceof Number - ? ((Number)value).longValue() - : IdConversion.convertToLong(value.toString()); - } - break; - } - return this; - } - - @Override - public long getContextTraceId() { - return traceId; - } - - @Override - public long getContextSpanId() { - return parentSpanId; - } - - /** null **/ - @Override - public Long getContextParentSpanId() { - return null; - } -} diff --git a/src/main/java/io/opentracing/impl/BraveSpanContext.java b/src/main/java/io/opentracing/impl/BraveSpanContext.java deleted file mode 100644 index 25008ee..0000000 --- a/src/main/java/io/opentracing/impl/BraveSpanContext.java +++ /dev/null @@ -1,23 +0,0 @@ -/** - * Copyright 2016 The OpenZipkin Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under the License - * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express - * or implied. See the License for the specific language governing permissions and limitations under - * the License. - */ -package io.opentracing.impl; - -import io.opentracing.SpanContext; - - -interface BraveSpanContext extends SpanContext { - long getContextTraceId(); - long getContextSpanId(); - Long getContextParentSpanId(); -} diff --git a/src/main/java/io/opentracing/impl/BraveTracer.java b/src/main/java/io/opentracing/impl/BraveTracer.java deleted file mode 100644 index 20c69c8..0000000 --- a/src/main/java/io/opentracing/impl/BraveTracer.java +++ /dev/null @@ -1,143 +0,0 @@ -/** - * Copyright 2016-2017 The OpenZipkin Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under the License - * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express - * or implied. See the License for the specific language governing permissions and limitations under - * the License. - */ -package io.opentracing.impl; - -import com.github.kristofa.brave.ServerSpan; -import java.util.Map; - -import com.github.kristofa.brave.Brave; -import com.github.kristofa.brave.IdConversion; -import com.github.kristofa.brave.InheritableServerClientAndLocalSpanState; -import com.github.kristofa.brave.SpanId; -import com.github.kristofa.brave.http.BraveHttpHeaders; -import com.twitter.zipkin.gen.Endpoint; -import io.opentracing.NoopSpanBuilder; -import io.opentracing.Span; -import io.opentracing.SpanContext; - -import io.opentracing.propagation.Format; -import java.util.HashMap; - -/** - * See project README.md for examples on how to use the API. - * - * Design notes: - * All spans that are explicitly created are done so with the local tracer. - * CS+CR and SR+SS annotations are done around the inject and extract methods. - * - * There is a mismatch between the two APIs in how state of the current span is held. - * OpenTracing does not hold any such state and passes in the current span intended to be a parent - * is an explicit action in the API, while in Brave this state is known and such action not required. - * OpenTracing's expectations are honoured here and Brave's internal state is overridden as needed. - * - * It is noted that it probably would have been simpler to have implemented against lower APIs in brave, - * like directly against the collector and spans, than the top level Brave api. - */ -public final class BraveTracer extends AbstractTracer { - - final Brave brave; - - public BraveTracer() { - this(Endpoint.create("unknown", 0)); - } - - public BraveTracer(Endpoint endpoint) { - this(new Brave.Builder(new InheritableServerClientAndLocalSpanState(endpoint))); - } - - public BraveTracer(Brave.Builder builder) { - brave = builder.build(); - } - - @Override - BraveSpanBuilder createSpanBuilder(String operationName) { - return BraveSpanBuilder.create(brave, operationName); - } - - @Override - Map getTraceState(SpanContext spanContext) { - BraveSpanContext sc = (BraveSpanContext)spanContext; - - return new HashMap() {{ - put(BraveHttpHeaders.Sampled.getName(), "1"); - put(BraveHttpHeaders.TraceId.getName(), IdConversion.convertToString(sc.getContextTraceId())); - put(BraveHttpHeaders.SpanId.getName(), IdConversion.convertToString(sc.getContextSpanId())); - if (null != sc.getContextParentSpanId()) { - put(BraveHttpHeaders.ParentSpanId.getName(), IdConversion.convertToString(sc.getContextParentSpanId())); - } - }}; - } - - Map getBaggage(Span span) { - return ((BraveSpan)span).getBaggage(); - } - - @Override - public void inject(SpanContext spanContext, Format format, C carrier) { - final SpanId spanId = brave.clientTracer().startNewSpan(((BraveSpan)spanContext).getOperationName()); - brave.clientTracer().setClientSent(); - - super.inject( - new BraveSpanContext() { - @Override - public long getContextTraceId() { - return spanId.traceId; - } - @Override - public long getContextSpanId() { - return spanId.spanId; - } - @Override - public Long getContextParentSpanId() { - return spanId.parentId; - } - @Override - public Iterable> baggageItems() { - return spanContext.baggageItems(); - } - }, - format, - carrier); - - ((BraveSpan)spanContext).setClientTracer(brave.clientTracer()); - } - - @Override - public SpanBuilder extract(Format format, C carrier) { - - BraveSpanBuilder builder = (BraveSpanBuilder) super.extract(format, carrier); - - if (null != builder.traceId && null != builder.parentSpanId) { - - SpanId context = SpanId.builder().traceId(builder.traceId).spanId(builder.parentSpanId).build(); - - brave.serverTracer().setStateCurrentTrace( - context, - builder.operationName); - - brave.serverTracer().setServerReceived(); - - ServerSpan serverSpan = brave.serverSpanThreadBinder().getCurrentServerSpan(); - if (Boolean.FALSE.equals(serverSpan.getSample())) { - return NoopSpanBuilder.INSTANCE; - } - brave.localSpanThreadBinder().setCurrentSpan(serverSpan.getSpan()); - - builder.withServerTracer(brave.serverTracer()); - return builder; - } - return NoopSpanBuilder.INSTANCE; - } - -} From b0e13e35990f73600f08ffb83a5700d535e504d0 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 14:33:51 -0500 Subject: [PATCH 06/17] Finished copying the existing impl out of the io.zipkin.brave:brave tests --- .../brave/features/opentracing/BraveSpan.java | 44 ++++++++++++------- .../opentracing/BraveSpanBuilder.java | 7 ++- .../features/opentracing/BraveTracer.java | 2 +- 3 files changed, 33 insertions(+), 20 deletions(-) diff --git a/src/main/java/brave/features/opentracing/BraveSpan.java b/src/main/java/brave/features/opentracing/BraveSpan.java index d994508..07d0650 100644 --- a/src/main/java/brave/features/opentracing/BraveSpan.java +++ b/src/main/java/brave/features/opentracing/BraveSpan.java @@ -42,7 +42,7 @@ private BraveSpan(brave.Span delegate) { */ @Override public SpanContext context() { - return null; + return context; } /** @@ -50,7 +50,7 @@ public SpanContext context() { */ @Override public void finish() { - + delegate.finish(); } /** @@ -58,7 +58,7 @@ public void finish() { */ @Override public void finish(long finishMicros) { - + delegate.finish(finishMicros); } /** @@ -66,7 +66,7 @@ public void finish(long finishMicros) { */ @Override public void close() { - + delegate.close(); } /** @@ -74,7 +74,8 @@ public void close() { */ @Override public Span setTag(String key, String value) { - return null; + delegate.tag(key, value); + return this; } /** @@ -82,7 +83,7 @@ public Span setTag(String key, String value) { */ @Override public Span setTag(String key, boolean value) { - return null; + return setTag(key, Boolean.toString(value)); } /** @@ -90,7 +91,7 @@ public Span setTag(String key, boolean value) { */ @Override public Span setTag(String key, Number value) { - return null; + return setTag(key, value.toString()); } /** @@ -98,7 +99,9 @@ public Span setTag(String key, Number value) { */ @Override public Span log(Map fields) { - return null; + if (fields.isEmpty()) return this; + // in real life, do like zipkin-go-opentracing: "key1=value1 key2=value2" + return log(fields.toString()); } /** @@ -106,7 +109,9 @@ public Span log(Map fields) { */ @Override public Span log(long timestampMicroseconds, Map fields) { - return null; + if (fields.isEmpty()) return this; + // in real life, do like zipkin-go-opentracing: "key1=value1 key2=value2" + return log(timestampMicroseconds, fields.toString()); } /** @@ -114,7 +119,8 @@ public Span log(long timestampMicroseconds, Map fields) { */ @Override public Span log(String event) { - return null; + delegate.annotate(event); + return this; } /** @@ -122,7 +128,8 @@ public Span log(String event) { */ @Override public Span log(long timestampMicroseconds, String event) { - return null; + delegate.annotate(timestampMicroseconds, event); + return this; } /** @@ -130,7 +137,8 @@ public Span log(long timestampMicroseconds, String event) { */ @Override public Span setBaggageItem(String key, String value) { - return null; + // brave does not support baggage + return this; } /** @@ -138,6 +146,7 @@ public Span setBaggageItem(String key, String value) { */ @Override public String getBaggageItem(String key) { + // brave does not support baggage return null; } @@ -146,22 +155,23 @@ public String getBaggageItem(String key) { */ @Override public Span setOperationName(String operationName) { - return null; + delegate.name(operationName); + return this; } /** * {@inheritDoc} */ @Override - public Span log(String eventName, Object payload) { - return null; + public Span log(String eventName, Object ignored) { + return log(eventName); } /** * {@inheritDoc} */ @Override - public Span log(long timestampMicroseconds, String eventName, Object payload) { - return null; + public Span log(long timestampMicroseconds, String eventName, Object ignored) { + return log(timestampMicroseconds, eventName); } } diff --git a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java index ca7aa0c..286a1d7 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java +++ b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java @@ -112,10 +112,13 @@ public Span start() { for (Map.Entry tag : tags.entrySet()) { span.tag(tag.getKey(), tag.getValue()); } + brave.Span result; if (timestamp != 0) { - return BraveSpan.wrap(span.start(timestamp)); + result = span.start(timestamp); + } else { + result = span.start(); } - return BraveSpan.wrap(span.start()); + return BraveSpan.wrap(result); } /** diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java index c09ba52..7e99bf1 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -36,7 +36,7 @@ public class BraveTracer implements Tracer { static final TraceContext.Extractor EXTRACTOR = Propagation.B3_STRING.extractor(TextMapView::get); private brave.Tracer brave4; - private Brave brave3; + private Brave brave3; // Not sure if I need this or not. Might want to attach to the local tracer context static BraveTracer wrap(brave.Tracer brave4) { if (brave4 == null) throw new NullPointerException("brave tracer == null"); From 568bbb1dc395a036561221ffa9e402a9ef403920 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 14:38:26 -0500 Subject: [PATCH 07/17] Bring in the test from brave:brave --- pom.xml | 6 + .../opentracing/OpenTracingAdapterTest.java | 103 ++++ .../io/opentracing/impl/AssertionTest.java | 33 -- .../impl/BraveSpanBuilderTest.java | 153 ------ .../io/opentracing/impl/BraveSpanTest.java | 146 ------ .../io/opentracing/impl/BraveTracerTest.java | 496 ------------------ 6 files changed, 109 insertions(+), 828 deletions(-) create mode 100644 src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java delete mode 100644 src/test/java/io/opentracing/impl/AssertionTest.java delete mode 100644 src/test/java/io/opentracing/impl/BraveSpanBuilderTest.java delete mode 100644 src/test/java/io/opentracing/impl/BraveSpanTest.java delete mode 100644 src/test/java/io/opentracing/impl/BraveTracerTest.java diff --git a/pom.xml b/pom.xml index 9ee4496..907794b 100644 --- a/pom.xml +++ b/pom.xml @@ -115,6 +115,12 @@ 1.10.19 test + + org.assertj + assertj-core + 3.6.1 + test + diff --git a/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java b/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java new file mode 100644 index 0000000..27af5e2 --- /dev/null +++ b/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java @@ -0,0 +1,103 @@ +package brave.features.opentracing; + +import brave.Tracer; +import brave.propagation.TraceContext; +import io.opentracing.propagation.Format; +import io.opentracing.propagation.TextMapExtractAdapter; +import io.opentracing.propagation.TextMapInjectAdapter; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import org.junit.Test; +import zipkin.Constants; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.tuple; +import static org.assertj.core.data.MapEntry.entry; +import static zipkin.internal.Util.UTF_8; + +/** + * This shows how one might make an OpenTracing adapter for Brave, and how to navigate in and out + * of the core concepts. + */ +public class OpenTracingAdapterTest { + List spans = new ArrayList<>(); + Tracer brave = Tracer.newBuilder().reporter(spans::add).build(); + BraveTracer opentracing = BraveTracer.wrap(brave); + + @Test public void startWithOpenTracingAndFinishWithBrave() { + io.opentracing.Span openTracingSpan = opentracing.buildSpan("encode") + .withTag(Constants.LOCAL_COMPONENT, "codec") + .withStartTimestamp(1L).start(); + + brave.Span braveSpan = ((BraveSpan) openTracingSpan).unwrap(); + + braveSpan.annotate(2L, "pump fake"); + braveSpan.finish(3L); + + checkSpanReportedToZipkin(); + } + + @Test public void startWithBraveAndFinishWithOpenTracing() { + brave.Span braveSpan = brave.newTrace().name("encode") + .tag(Constants.LOCAL_COMPONENT, "codec") + .start(1L); + + io.opentracing.Span openTracingSpan = BraveSpan.wrap(braveSpan); + + openTracingSpan.log(2L, "pump fake"); + openTracingSpan.finish(3L); + + checkSpanReportedToZipkin(); + } + + @Test + public void extractTraceContext() throws Exception { + Map map = new LinkedHashMap<>(); + map.put("X-B3-TraceId", "0000000000000001"); + map.put("X-B3-SpanId", "0000000000000002"); + map.put("X-B3-Sampled", "1"); + + BraveSpanContext openTracingContext = + (BraveSpanContext) opentracing.extract(Format.Builtin.HTTP_HEADERS, new TextMapExtractAdapter(map)); + + assertThat(openTracingContext.unwrap()) + .isEqualTo(TraceContext.newBuilder() + .traceId(1L) + .spanId(2L) + .shared(true) + .sampled(true).build()); + } + + @Test + public void injectTraceContext() throws Exception { + TraceContext context = TraceContext.newBuilder() + .traceId(1L) + .spanId(2L) + .sampled(true).build(); + + Map map = new LinkedHashMap<>(); + TextMapInjectAdapter carrier = new TextMapInjectAdapter(map); + opentracing.inject(BraveSpanContext.wrap(context), Format.Builtin.HTTP_HEADERS, carrier); + + assertThat(map).containsExactly( + entry("X-B3-TraceId", "0000000000000001"), + entry("X-B3-SpanId", "0000000000000002"), + entry("X-B3-Sampled", "1") + ); + } + + void checkSpanReportedToZipkin() { + assertThat(spans).first().satisfies(s -> { + assertThat(s.name).isEqualTo("encode"); + assertThat(s.timestamp).isEqualTo(1L); + assertThat(s.annotations).extracting(a -> a.timestamp, a -> a.value) + .containsExactly(tuple(2L, "pump fake")); + assertThat(s.binaryAnnotations).extracting(b -> b.key, b -> new String(b.value, UTF_8)) + .containsExactly(tuple(Constants.LOCAL_COMPONENT, "codec")); + assertThat(s.duration).isEqualTo(2L); + } + ); + } +} diff --git a/src/test/java/io/opentracing/impl/AssertionTest.java b/src/test/java/io/opentracing/impl/AssertionTest.java deleted file mode 100644 index 6876a68..0000000 --- a/src/test/java/io/opentracing/impl/AssertionTest.java +++ /dev/null @@ -1,33 +0,0 @@ -/** - * Copyright 2016 The OpenZipkin Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under the License - * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express - * or implied. See the License for the specific language governing permissions and limitations under - * the License. - */ - -package io.opentracing.impl; - -import org.junit.Test; - -public final class AssertionTest { - - @Test - public void test_assertions_enabled() { - boolean asserted = false; - try { - assert false; - } catch (AssertionError error) { - asserted = true; - } - if (!asserted) { - throw new AssertionError("assertions are not enabled"); - } - } -} diff --git a/src/test/java/io/opentracing/impl/BraveSpanBuilderTest.java b/src/test/java/io/opentracing/impl/BraveSpanBuilderTest.java deleted file mode 100644 index 9850ec6..0000000 --- a/src/test/java/io/opentracing/impl/BraveSpanBuilderTest.java +++ /dev/null @@ -1,153 +0,0 @@ -/** - * Copyright 2016-2017 The OpenZipkin Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under the License - * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express - * or implied. See the License for the specific language governing permissions and limitations under - * the License. - */ -package io.opentracing.impl; - -import com.github.kristofa.brave.Brave; -import com.github.kristofa.brave.ThreadLocalServerClientAndLocalSpanState; -import com.github.kristofa.brave.http.BraveHttpHeaders; -import io.opentracing.Span; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Optional; -import org.junit.Before; -import org.junit.Test; - -public final class BraveSpanBuilderTest { - - private List spans = new ArrayList<>(); - // -1062731775 = 192.168.0.1 - private Brave brave = new Brave.Builder(-1062731775, 8080, "unknown") - .reporter(spans::add).build(); - - @Before - public void setup() { - ThreadLocalServerClientAndLocalSpanState.clear(); - } - - @Test - public void testCreateSpan() { - String operationName = "test-testCreateSpan"; - BraveSpanBuilder builder = BraveSpanBuilder.create(brave, operationName); - BraveSpan span = builder.createSpan(); - - assert null != span.spanId; - assert 0 != span.spanId.spanId : span.spanId.spanId; - assert 0 != span.spanId.traceId : span.spanId.traceId; - assert null == span.spanId.nullableParentId() : span.spanId.nullableParentId(); - assert operationName.equals(span.getOperationName()) : "span.getOperationName was " + span.getOperationName(); - assert !span.parent.isPresent(); - assert !span.serverTracer.isPresent(); - assert span.getBaggage().isEmpty(); - } - - @Test - public void testWithServerTracer() { - String operationName = "test-testWithServerTracer"; - - BraveSpanBuilder builder = BraveSpanBuilder - .create(brave, operationName) - .withServerTracer(brave.serverTracer()); - - BraveSpan span = builder.createSpan(); - - assert null != span.spanId; - assert 0 != span.spanId.spanId : span.spanId.spanId; - assert 0 != span.spanId.traceId : span.spanId.traceId; - assert null == span.spanId.nullableParentId() : span.spanId.nullableParentId(); - assert operationName.equals(span.getOperationName()) : "span.getOperationName was " + span.getOperationName(); - assert !span.parent.isPresent(); - assert span.serverTracer.isPresent(); - assert brave.serverTracer().equals(span.serverTracer.get()); - assert span.getBaggage().isEmpty(); - } - - @Test - public void testWithServerTracer_withParent() { - String operationName = "test-testWithServerTracer_withParent"; - Instant start = Instant.now(); - - BraveSpan parent = BraveSpan.create( - brave, - operationName + "-parent", - Optional.empty(), - start.minusMillis(100), - Optional.of(brave.serverTracer())); - - brave.serverTracer().setStateCurrentTrace( - parent.spanId, - parent.getOperationName()); - - BraveSpanBuilder builder = (BraveSpanBuilder) BraveSpanBuilder - .create(brave, operationName) - .withServerTracer(brave.serverTracer()) - .asChildOf((Span)parent); - - BraveSpan span = builder.createSpan(); - - assert null != span.spanId; - assert 0 != span.spanId.spanId : span.spanId.spanId; - assert 0 != span.spanId.traceId : span.spanId.traceId; - assert null != span.spanId.nullableParentId() : span.spanId.nullableParentId(); - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert span.parent.isPresent(); - assert parent.equals(span.parent.get()); - assert span.serverTracer.isPresent(); - assert brave.serverTracer().equals(span.serverTracer.get()); - assert span.getBaggage().isEmpty(); - } - - @Test - public void testIsTraceState() { - String operationName = "test-testCreateSpan"; - BraveSpanBuilder builder = BraveSpanBuilder.create(brave, operationName); - - for (BraveHttpHeaders header : BraveHttpHeaders.values()) { - assert builder.isTraceState(header.getName(), "any-value") - : header.getName() + " should be a trace state key"; - } - - assert !builder.isTraceState("not-a-zipkin-header", "any-value"); - } - - @Test - public void testWithStateItem() { - String operationName = "test-testWithStateItem"; - - BraveSpanBuilder builder = BraveSpanBuilder - .create(brave, operationName) - .withServerTracer(brave.serverTracer()) - .withStateItem(BraveHttpHeaders.TraceId.getName(), "123") - .withStateItem(BraveHttpHeaders.SpanId.getName(), "234"); - - brave.serverTracer().setStateCurrentTrace( - builder.traceId, - builder.parentSpanId, - null, - builder.operationName); - - BraveSpan span = builder.createSpan(); - - assert null != span.spanId; - assert 0 != span.spanId.spanId : span.spanId.spanId; - assert 291 == span.spanId.traceId : span.spanId.traceId; - assert 564 == span.spanId.nullableParentId() : span.spanId.nullableParentId(); - assert operationName.equals(span.getOperationName()) : span.getOperationName(); - assert !span.parent.isPresent(); - assert span.serverTracer.isPresent(); - assert brave.serverTracer().equals(span.serverTracer.get()); - assert span.getBaggage().isEmpty(); - } - -} diff --git a/src/test/java/io/opentracing/impl/BraveSpanTest.java b/src/test/java/io/opentracing/impl/BraveSpanTest.java deleted file mode 100644 index de6ee4e..0000000 --- a/src/test/java/io/opentracing/impl/BraveSpanTest.java +++ /dev/null @@ -1,146 +0,0 @@ -/** - * Copyright 2016-2017 The OpenZipkin Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under the License - * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express - * or implied. See the License for the specific language governing permissions and limitations under - * the License. - */ -package io.opentracing.impl; - -import com.github.kristofa.brave.Brave; -import com.github.kristofa.brave.ServerTracer; -import com.github.kristofa.brave.ThreadLocalServerClientAndLocalSpanState; -import java.time.Instant; -import java.util.ArrayList; -import java.util.List; -import java.util.Optional; -import org.junit.Before; -import org.junit.Test; - -public final class BraveSpanTest { - - private List spans = new ArrayList<>(); - // -1062731775 = 192.168.0.1 - private Brave brave = new Brave.Builder(-1062731775, 8080, "unknown") - .reporter(spans::add).build(); - - @Before - public void setup() { - ThreadLocalServerClientAndLocalSpanState.clear(); - } - - @Test - public void test() { - String operationName = "test-test"; - Optional parent = Optional.empty(); - Instant start = Instant.now(); - Optional serverTracer = Optional.empty(); - - BraveSpan span = BraveSpan.create(brave, operationName, parent, start, serverTracer); - - assert null != span.spanId; - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert !span.parent.isPresent(); - assert !span.serverTracer.isPresent(); - assert span.getBaggage().isEmpty(); - - span.finish(); - - assert null != span.spanId; - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert !span.parent.isPresent(); - assert !span.serverTracer.isPresent(); - assert span.getBaggage().isEmpty(); - } - - @Test - public void test_withServerTracer() { - String operationName = "test-test_withServerTracer"; - Optional parent = Optional.empty(); - Instant start = Instant.now(); - Optional serverTracer = Optional.of(brave.serverTracer()); - - BraveSpan span = BraveSpan.create(brave, operationName, parent, start, serverTracer); - - assert null != span.spanId; - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert !span.parent.isPresent(); - assert span.serverTracer.isPresent(); - assert brave.serverTracer().equals(span.serverTracer.get()); - assert span.getBaggage().isEmpty(); - - span.finish(); - - assert null != span.spanId; - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert !span.parent.isPresent(); - assert span.serverTracer.isPresent(); - assert brave.serverTracer().equals(span.serverTracer.get()); - assert span.getBaggage().isEmpty(); - } - - @Test - public void test_withParent() { - String operationName = "test-test_withParent"; - Instant start = Instant.now(); - Optional serverTracer = Optional.empty(); - - Optional parent = Optional.of( - BraveSpan.create(brave, operationName, Optional.empty(), start.minusMillis(100), serverTracer)); - - BraveSpan span = BraveSpan.create(brave, operationName, parent, start, serverTracer); - - assert null != span.spanId; - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert span.parent.isPresent(); - assert span.parent.get() == parent.get(); - assert !span.serverTracer.isPresent(); - assert span.getBaggage().isEmpty(); - - span.finish(); - - assert null != span.spanId; - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert span.parent.isPresent(); - assert span.parent.get() == parent.get(); - assert !span.serverTracer.isPresent(); - assert span.getBaggage().isEmpty(); - } - - @Test - public void test_withParent_withServerTracer() { - String operationName = "test-test_withParent_withServerTracer"; - Instant start = Instant.now(); - Optional serverTracer = Optional.of(brave.serverTracer()); - - Optional parent = Optional.of( - BraveSpan.create(brave, operationName, Optional.empty(), start.minusMillis(100), serverTracer)); - - BraveSpan span = BraveSpan.create(brave, operationName, parent, start, serverTracer); - - assert null != span.spanId; - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert span.parent.isPresent(); - assert span.parent.get() == parent.get(); - assert span.serverTracer.isPresent(); - assert brave.serverTracer().equals(span.serverTracer.get()); - assert span.getBaggage().isEmpty(); - - span.finish(); - - assert null != span.spanId; - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert span.parent.isPresent(); - assert span.parent.get() == parent.get(); - assert span.serverTracer.isPresent(); - assert brave.serverTracer().equals(span.serverTracer.get()); - assert span.getBaggage().isEmpty(); - } - -} diff --git a/src/test/java/io/opentracing/impl/BraveTracerTest.java b/src/test/java/io/opentracing/impl/BraveTracerTest.java deleted file mode 100644 index 613a425..0000000 --- a/src/test/java/io/opentracing/impl/BraveTracerTest.java +++ /dev/null @@ -1,496 +0,0 @@ -/** - * Copyright 2016-2017 The OpenZipkin Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except - * in compliance with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software distributed under the License - * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express - * or implied. See the License for the specific language governing permissions and limitations under - * the License. - */ -package io.opentracing.impl; - -import com.github.kristofa.brave.IdConversion; -import com.github.kristofa.brave.ServerTracer; -import com.github.kristofa.brave.ThreadLocalServerClientAndLocalSpanState; -import com.github.kristofa.brave.http.BraveHttpHeaders; -import io.opentracing.NoopSpanContext; -import io.opentracing.Span; -import io.opentracing.SpanContext; -import io.opentracing.propagation.Format; -import io.opentracing.propagation.TextMapExtractAdapter; -import io.opentracing.propagation.TextMapInjectAdapter; -import java.time.Instant; -import java.util.Collections; -import java.util.HashMap; -import java.util.Map; -import java.util.Optional; -import org.junit.Before; -import org.junit.Test; - - -public final class BraveTracerTest { - - @Before - public void setup() { - ThreadLocalServerClientAndLocalSpanState.clear(); - } - - @Test - public void test_buildSpan() { - String operationName = "test-test_buildSpan"; - BraveTracer tracer = new BraveTracer(); - BraveSpanBuilder builder = (BraveSpanBuilder) tracer.buildSpan(operationName); - - assert operationName.equals(builder.operationName) : builder.operationName; - assert null == builder.parentSpanId : builder.parentSpanId; - assert builder.references.isEmpty(); - assert null == builder.serverTracer : builder.serverTracer; - assert builder.start.isBefore(Instant.now().plusMillis(1)); - assert null == builder.traceId : builder.traceId; - - BraveSpan span = builder.createSpan(); - - assert null != span.spanId; - assert 0 != span.spanId.spanId : span.spanId.spanId; - assert 0 != span.spanId.traceId : span.spanId.traceId; - assert null == span.spanId.nullableParentId() : span.spanId.nullableParentId(); - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert !span.parent.isPresent(); - assert !span.serverTracer.isPresent(); - assert span.getBaggage().isEmpty(); - - span.finish(); - } - - @Test - public void test_buildSpan_child() { - String parentOperationName = "test-test_buildSpan_child-parent"; - String operationName = "test-test_buildSpan_child"; - BraveTracer tracer = new BraveTracer(); - BraveSpanBuilder builder = (BraveSpanBuilder) tracer.buildSpan(parentOperationName); - - assert parentOperationName.equals(builder.operationName) : builder.operationName; - assert null == builder.parentSpanId : builder.parentSpanId; - assert builder.references.isEmpty(); - assert null == builder.serverTracer : builder.serverTracer; - assert builder.start.isBefore(Instant.now().plusMillis(1)); - assert null == builder.traceId : builder.traceId; - - BraveSpan parent = builder.createSpan(); - - assert null != parent.spanId; - assert 0 != parent.spanId.spanId : parent.spanId.spanId; - assert 0 != parent.spanId.traceId : parent.spanId.traceId; - assert null == parent.spanId.nullableParentId() : parent.spanId.nullableParentId(); - assert parentOperationName.equals(parent.getOperationName()) : "span.operationName was " + parent.getOperationName(); - assert !parent.parent.isPresent(); - assert !parent.serverTracer.isPresent(); - assert parent.getBaggage().isEmpty(); - - builder = (BraveSpanBuilder) tracer.buildSpan(operationName).asChildOf((Span)parent); - BraveSpan span = builder.createSpan(); - - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assertChildToParent(span, parent, false); - - span.finish(); - parent.finish(); - } - - @Test - public void test_buildSpan_seperate_traces() { - String parentOperationName = "test-test_buildSpan_seperate_traces-parent"; - String operationName = "test-test_buildSpan_seperate_traces"; - BraveTracer tracer = new BraveTracer(); - BraveSpanBuilder builder = (BraveSpanBuilder) tracer.buildSpan(parentOperationName); - - assert parentOperationName.equals(builder.operationName) : builder.operationName; - assert null == builder.parentSpanId : builder.parentSpanId; - assert builder.references.isEmpty(); - assert null == builder.serverTracer : builder.serverTracer; - assert builder.start.isBefore(Instant.now().plusMillis(1)); - assert null == builder.traceId : builder.traceId; - - BraveSpan first = builder.createSpan(); - - assert null != first.spanId; - assert 0 != first.spanId.spanId : first.spanId.spanId; - assert 0 != first.spanId.traceId : first.spanId.traceId; - assert null == first.spanId.nullableParentId() : first.spanId.nullableParentId(); - assert parentOperationName.equals(first.getOperationName()) : "span.operationName was " + first.getOperationName(); - assert !first.parent.isPresent(); - assert !first.serverTracer.isPresent(); - assert first.getBaggage().isEmpty(); - - first.finish(); - builder = (BraveSpanBuilder) tracer.buildSpan(operationName); - BraveSpan second = builder.createSpan(); - - assert null != second.spanId; - assert 0 != second.spanId.spanId : second.spanId.spanId; - assert 0 != second.spanId.spanId : second.spanId.spanId; - assert 0 != second.spanId.traceId : second.spanId.traceId; - - assert first.spanId.traceId != second.spanId.traceId - : "child: " + first.spanId.traceId + " ; parent: " + second.spanId.traceId; - - assert null == second.spanId.nullableParentId() : second.spanId.nullableParentId(); - assert operationName.equals(second.getOperationName()) : "span.operationName was " + second.getOperationName(); - assert !first.parent.isPresent(); - assert !second.serverTracer.isPresent(); - assert second.getBaggage().isEmpty(); - - second.finish(); - } - - @Test - public void test_buildSpan_same_trace() { - String parentOperationName = "test-test_buildSpan_same_trace-parent"; - String operationName1 = "test-test_buildSpan_same_trace-1"; - String operationName2 = "test-test_buildSpan_same_trace-2"; - BraveTracer tracer = new BraveTracer(); - BraveSpanBuilder builder = (BraveSpanBuilder) tracer.buildSpan(parentOperationName); - - assert parentOperationName.equals(builder.operationName) : builder.operationName; - assert null == builder.parentSpanId : builder.parentSpanId; - assert builder.references.isEmpty(); - assert null == builder.serverTracer : builder.serverTracer; - assert builder.start.isBefore(Instant.now().plusMillis(1)); - assert null == builder.traceId : builder.traceId; - - BraveSpan parent = builder.createSpan(); - - assert null != parent.spanId; - assert 0 != parent.spanId.spanId : parent.spanId.spanId; - assert 0 != parent.spanId.traceId : parent.spanId.traceId; - assert null == parent.spanId.nullableParentId() : parent.spanId.nullableParentId(); - assert parentOperationName.equals(parent.getOperationName()) : "span.operationName was " + parent.getOperationName(); - assert !parent.parent.isPresent(); - assert !parent.serverTracer.isPresent(); - assert parent.getBaggage().isEmpty(); - - builder = (BraveSpanBuilder) tracer.buildSpan(operationName1).asChildOf((Span)parent); - BraveSpan first = builder.createSpan(); - - assert operationName1.equals(first.getOperationName()) : "span.operationName was " + first.getOperationName(); - assertChildToParent(first, parent, false); - - first.finish(); - builder = (BraveSpanBuilder) tracer.buildSpan(operationName2).asChildOf((Span)parent); - BraveSpan second = builder.createSpan(); - - assert operationName2.equals(second.getOperationName()) : "span.operationName was " + second.getOperationName(); - assertChildToParent(second, parent, false); - - second.finish(); - parent.finish(); - } - - @Test - public void test_buildSpan_notChild_separate_traces() { - String parentOperationName = "test-test_buildSpan_notChild_seperate_traces-parent"; - String operationName = "test-test_buildSpan_notChild_seperate_traces"; - BraveTracer tracer = new BraveTracer(); - BraveSpanBuilder builder = (BraveSpanBuilder) tracer.buildSpan(parentOperationName); - - assert parentOperationName.equals(builder.operationName) : builder.operationName; - assert null == builder.parentSpanId : builder.parentSpanId; - assert builder.references.isEmpty(); - assert null == builder.serverTracer : builder.serverTracer; - assert builder.start.isBefore(Instant.now().plusMillis(1)); - assert null == builder.traceId : builder.traceId; - - BraveSpan first = builder.createSpan(); - - assert null != first.spanId; - assert 0 != first.spanId.spanId : first.spanId.spanId; - assert 0 != first.spanId.traceId : first.spanId.traceId; - assert null == first.spanId.nullableParentId() : first.spanId.nullableParentId(); - assert parentOperationName.equals(first.getOperationName()) : "span.operationName was " + first.getOperationName(); - assert !first.parent.isPresent(); - assert !first.serverTracer.isPresent(); - assert first.getBaggage().isEmpty(); - - builder = (BraveSpanBuilder) tracer.buildSpan(operationName); - BraveSpan second = builder.createSpan(); - - assert null != second.spanId; - assert 0 != second.spanId.spanId : second.spanId.spanId; - assert 0 != second.spanId.spanId : second.spanId.spanId; - assert 0 != second.spanId.traceId : second.spanId.traceId; - - assert first.spanId.traceId != second.spanId.traceId - : "child: " + first.spanId.traceId + " ; parent: " + second.spanId.traceId; - - assert null == second.spanId.nullableParentId() : second.spanId.nullableParentId(); - assert operationName.equals(second.getOperationName()) : "span.operationName was " + second.getOperationName(); - assert !first.parent.isPresent(); - assert !second.serverTracer.isPresent(); - assert second.getBaggage().isEmpty(); - - first.finish(); - second.finish(); - } - - @Test - public void testGetTraceState() { - String operationName = "test-testGetTraceState"; - BraveTracer tracer = new BraveTracer(); - - Optional parent = Optional.empty(); - Instant start = Instant.now(); - Optional serverTracer = Optional.empty(); - - BraveSpan span = BraveSpan.create(tracer.brave, operationName, parent, start, serverTracer); - - assert tracer.getTraceState(span).containsKey(BraveHttpHeaders.TraceId.getName()); - assert tracer.getTraceState(span).containsKey(BraveHttpHeaders.SpanId.getName()); - assert tracer.getTraceState(span).containsKey(BraveHttpHeaders.Sampled.getName()); - - assert tracer.getTraceState(span).get(BraveHttpHeaders.TraceId.getName()) - .equals(IdConversion.convertToString(span.spanId.traceId)); - - assert tracer.getTraceState(span).get(BraveHttpHeaders.SpanId.getName()) - .equals(IdConversion.convertToString(span.spanId.spanId)); - - span.finish(); - } - - @Test - public void testGetBaggage() { - String operationName = "test-testGetBaggage"; - BraveTracer tracer = new BraveTracer(); - - BraveSpanBuilder builder = (BraveSpanBuilder) tracer.buildSpan(operationName); - - Span span = builder.withBaggageItem("getBaggage()-key-1", "getBaggage()-value-1").start(); - - assert tracer.getBaggage(span).containsKey("getBaggage()-key-1"); - assert "getBaggage()-value-1".equals(tracer.getBaggage(span).get("getBaggage()-key-1")); - - span.finish(); - } - - @Test - public void testInject() { - String operationName = "test-testInject"; - BraveTracer tracer = new BraveTracer(); - BraveSpanBuilder builder = (BraveSpanBuilder) tracer.buildSpan(operationName); - - assert operationName.equals(builder.operationName) : builder.operationName; - assert null == builder.parentSpanId : builder.parentSpanId; - assert builder.references.isEmpty(); - assert null == builder.serverTracer : builder.serverTracer; - assert builder.start.isBefore(Instant.now().plusMillis(1)); - assert null == builder.traceId : builder.traceId; - - BraveSpan span = builder.createSpan(); - - assert null != span.spanId; - assert 0 != span.spanId.spanId : span.spanId.spanId; - assert 0 != span.spanId.traceId : span.spanId.traceId; - assert null == span.spanId.nullableParentId() : span.spanId.nullableParentId(); - assert operationName.equals(span.getOperationName()) : "span.operationName was " + span.getOperationName(); - assert !span.parent.isPresent(); - assert !span.serverTracer.isPresent(); - assert span.getBaggage().isEmpty(); - - Map map = new HashMap<>(); - TextMapInjectAdapter adapter = new TextMapInjectAdapter(map); - tracer.inject(span, Format.Builtin.TEXT_MAP, adapter); - - assert map.containsKey(BraveHttpHeaders.TraceId.getName()); - assert map.containsKey(BraveHttpHeaders.SpanId.getName()); - - span.finish(); - } - - @Test - public void testExtract() { - - Map map = new HashMap() {{ - put(BraveHttpHeaders.Sampled.getName(), "1"); - put(BraveHttpHeaders.TraceId.getName(), "123"); - put(BraveHttpHeaders.SpanId.getName(), "234"); - }}; - - TextMapExtractAdapter adapter = new TextMapExtractAdapter(map); - BraveTracer tracer = new BraveTracer(); - BraveSpanBuilder builder = (BraveSpanBuilder) tracer.extract(Format.Builtin.TEXT_MAP, adapter); - - assert 291 == builder.traceId : builder.traceId; - assert 564 == builder.parentSpanId : builder.parentSpanId; - } - - @Test - public void testExtractAsParent() throws Exception { - Map map = new HashMap() {{ - put(BraveHttpHeaders.Sampled.getName(), "1"); - put(BraveHttpHeaders.TraceId.getName(), "123"); - put(BraveHttpHeaders.SpanId.getName(), "234"); - }}; - TextMapExtractAdapter adapter = new TextMapExtractAdapter(map); - BraveTracer tracer = new BraveTracer(); - SpanContext parent = tracer.extract(Format.Builtin.TEXT_MAP, adapter); - BraveSpan span = (BraveSpan) tracer.buildSpan("child").asChildOf(parent).start(); - assert 291 == span.getContextTraceId() : span.getContextTraceId(); - assert 0 != span.getContextSpanId(): span.getContextSpanId(); - assert 564 == span.getContextParentSpanId() : span.getContextParentSpanId(); - } - - @Test - public void testExtractOfNoParent() throws Exception { - TextMapExtractAdapter adapter = new TextMapExtractAdapter(Collections.emptyMap()); - BraveTracer tracer = new BraveTracer(); - NoopSpanContext parent = (NoopSpanContext)tracer.extract(Format.Builtin.TEXT_MAP, adapter); - - assert NoopSpanContext.class.isAssignableFrom(parent.getClass()) - : "Expecting NoopSpanContext: " + parent.getClass(); - - Span child = tracer.buildSpan("child").asChildOf(parent).start(); - assert NoopSpan.class.isAssignableFrom(child.getClass()) : "Expecting NoopSpan: " + child.getClass(); - } - - @Test - public void test_stack() throws InterruptedException { - - BraveTracer tracer = new BraveTracer(); - - long start = System.currentTimeMillis() - 10000; - - // start a span - try ( Span span0 = tracer.buildSpan("span-0") - .withStartTimestamp(start) - .withTag("description", "top level initial span in the original process") - .start() ) { - - - try ( Span span1 = tracer.buildSpan("span-1") - .withStartTimestamp(start +100) - .asChildOf(span0) - .withTag("description", "the first inner span in the original process") - .start() ) { - - assertChildToParent((BraveSpan) span1, (BraveSpan) span0, false); - - try ( Span span2 = tracer.buildSpan("span-2") - .withStartTimestamp(start +200) - .asChildOf(span1) - .withTag("description", "the second inner span in the original process") - .start() ) { - - assertChildToParent((BraveSpan) span2, (BraveSpan) span1, false); - - // cross process boundary - Map map = new HashMap<>(); - tracer.inject(span2.context(), Format.Builtin.TEXT_MAP, new TextMapInjectAdapter(map)); - - try ( Span span3 = tracer.extract(Format.Builtin.TEXT_MAP, new TextMapExtractAdapter(map)) - .withStartTimestamp(start +300) - .withTag("description", "the third inner span in the second process") - .start() ) { - - assertChildToParent((BraveSpan) span3, (BraveSpan) span2, true); - - try ( Span span4 = tracer.buildSpan("span-4") - .withStartTimestamp(start +400) - .asChildOf(span3) - .withTag("description", "the fourth inner span in the second process") - .start() ) { - - assertChildToParent((BraveSpan) span4, (BraveSpan) span3, false); - - // cross process boundary - map = new HashMap<>(); - tracer.inject(span4.context(), Format.Builtin.TEXT_MAP, new TextMapInjectAdapter(map)); - - try ( Span span5 = tracer.extract(Format.Builtin.TEXT_MAP, new TextMapExtractAdapter(map)) - .withStartTimestamp(start +500) - .withTag("description", "the fifth inner span in the third process") - .start() ) { - - assertChildToParent((BraveSpan) span5, (BraveSpan) span4, true); - - try ( Span span6 = tracer.buildSpan("span-6") - .withStartTimestamp(start +600) - .asChildOf(span5) - .withTag("description", "the sixth inner span in the third process") - .start() ) { - - assertChildToParent((BraveSpan) span6, (BraveSpan) span5, false); - - try ( Span span7 = tracer.buildSpan("span-7") - .withStartTimestamp(start +700) - .asChildOf(span6) - .withTag("description", "the seventh span in the third process") - .start() ) { - - assertChildToParent((BraveSpan) span7, (BraveSpan) span6, false); - - // cross process boundary - map = new HashMap<>(); - - tracer.inject( - span7.context(), - Format.Builtin.TEXT_MAP, - new TextMapInjectAdapter(map)); - - try ( Span span8 = tracer - .extract(Format.Builtin.TEXT_MAP, new TextMapExtractAdapter(map)) - .withStartTimestamp(start +800) - .withTag("description", "the eight inner span in the fourth process") - .start() ) { - - assertChildToParent((BraveSpan) span8, (BraveSpan) span7, true); - - try ( Span span9 = tracer.buildSpan("span-9") - .withStartTimestamp(start +900) - .asChildOf(span8) - .withTag("description", "the ninth inner span in the fouth process") - .start() ) { - - assertChildToParent((BraveSpan) span9, (BraveSpan) span8, false); - Thread.sleep(10); - } - Thread.sleep(10); - } - Thread.sleep(10); - } - Thread.sleep(10); - } - Thread.sleep(10); - } - Thread.sleep(10); - } - Thread.sleep(10); - } - Thread.sleep(10); - } - Thread.sleep(10); - } - Thread.sleep(10); - } - } - - private void assertChildToParent(BraveSpan span, BraveSpan parent, boolean extracted) { - assert null != span.spanId; - assert 0 != span.spanId.spanId : span.spanId.spanId; - - assert parent.spanId.traceId == span.spanId.traceId - : "parent: " + parent.spanId.traceId + " ; child: " + span.spanId.traceId; - - if (!extracted) { - assert parent.spanId.spanId == span.spanId.nullableParentId() - : "parent: " + parent.spanId.spanId + " ; child: " + span.spanId.nullableParentId(); - } - - assert extracted || span.parent.isPresent(); - assert extracted || span.parent.get().equals(parent); - assert !extracted || span.serverTracer.isPresent(); - assert span.getBaggage().isEmpty(); - } -} From 01a28f3302dc18376eefa7c2d58e2229f7271f2a Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 14:40:30 -0500 Subject: [PATCH 08/17] Fix licenses --- .../features/opentracing/BraveSpanContext.java | 13 +++++++++++++ .../opentracing/OpenTracingAdapterTest.java | 13 +++++++++++++ 2 files changed, 26 insertions(+) diff --git a/src/main/java/brave/features/opentracing/BraveSpanContext.java b/src/main/java/brave/features/opentracing/BraveSpanContext.java index ea7e7ad..cddc8de 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanContext.java +++ b/src/main/java/brave/features/opentracing/BraveSpanContext.java @@ -1,3 +1,16 @@ +/** + * Copyright 2016-2017 The OpenZipkin Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License + * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + * or implied. See the License for the specific language governing permissions and limitations under + * the License. + */ package brave.features.opentracing; import brave.propagation.TraceContext; diff --git a/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java b/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java index 27af5e2..766d9a6 100644 --- a/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java +++ b/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java @@ -1,3 +1,16 @@ +/** + * Copyright 2016-2017 The OpenZipkin Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License + * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + * or implied. See the License for the specific language governing permissions and limitations under + * the License. + */ package brave.features.opentracing; import brave.Tracer; From 1c5b8b8706df1fdc9c6ba6c9992d79603b271816 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 14:50:40 -0500 Subject: [PATCH 09/17] Make exception messages the same --- src/main/java/brave/features/opentracing/BraveTracer.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java index 7e99bf1..fc12368 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -62,7 +62,7 @@ public SpanBuilder buildSpan(String operationName) { @Override public void inject(SpanContext spanContext, Format format, C carrier) { if (format != Format.Builtin.HTTP_HEADERS) { - throw new UnsupportedOperationException(format + " != Format.Builtin.HTTP_HEADERS"); + throw new UnsupportedOperationException(format.toString() + " != Format.Builtin.HTTP_HEADERS"); } TraceContext traceContext = ((BraveSpanContext) spanContext).unwrap(); INJECTOR.inject(traceContext, (TextMap) carrier); @@ -74,7 +74,7 @@ public void inject(SpanContext spanContext, Format format, C carrier) { @Override public SpanContext extract(Format format, C carrier) { if (format != Format.Builtin.HTTP_HEADERS) { - throw new UnsupportedOperationException(format.toString()); + throw new UnsupportedOperationException(format.toString() + " != Format.Builtin.HTTP_HEADERS"); } TraceContextOrSamplingFlags result = EXTRACTOR.extract(new TextMapView(PROPAGATION_KEYS, (TextMap) carrier)); From f42213085105de1a3ab0c2d93f67e76a9c950448 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 15:29:59 -0500 Subject: [PATCH 10/17] That needs to be public for actually using this thing --- src/main/java/brave/features/opentracing/BraveTracer.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java index fc12368..5dcd8ef 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -38,7 +38,7 @@ public class BraveTracer implements Tracer { private brave.Tracer brave4; private Brave brave3; // Not sure if I need this or not. Might want to attach to the local tracer context - static BraveTracer wrap(brave.Tracer brave4) { + public static BraveTracer wrap(brave.Tracer brave4) { if (brave4 == null) throw new NullPointerException("brave tracer == null"); return new BraveTracer(brave4); } From 28b15cce71e257112ccb7f5d39ebb707d478c397 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 15:31:37 -0500 Subject: [PATCH 11/17] The constructor can be private also --- src/main/java/brave/features/opentracing/BraveTracer.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java index 5dcd8ef..39d6ef4 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -43,7 +43,7 @@ public static BraveTracer wrap(brave.Tracer brave4) { return new BraveTracer(brave4); } - BraveTracer(brave.Tracer brave4) { + private BraveTracer(brave.Tracer brave4) { this.brave4 = brave4; this.brave3 = TracerAdapter.newBrave(this.brave4); } From ba1605960581c127842bc6319596b6c72adb32d1 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Tue, 24 Jan 2017 21:54:37 -0500 Subject: [PATCH 12/17] Code review changes --- pom.xml | 5 ----- .../java/brave/features/opentracing/BraveSpan.java | 11 ++++++++--- .../brave/features/opentracing/BraveSpanBuilder.java | 5 ++++- .../java/brave/features/opentracing/BraveTracer.java | 4 ---- 4 files changed, 12 insertions(+), 13 deletions(-) diff --git a/pom.xml b/pom.xml index 907794b..0e698df 100644 --- a/pom.xml +++ b/pom.xml @@ -97,11 +97,6 @@ brave 4.0.3 - - io.zipkin.brave - brave-core - 4.0.3 - junit diff --git a/src/main/java/brave/features/opentracing/BraveSpan.java b/src/main/java/brave/features/opentracing/BraveSpan.java index 07d0650..3c96541 100644 --- a/src/main/java/brave/features/opentracing/BraveSpan.java +++ b/src/main/java/brave/features/opentracing/BraveSpan.java @@ -133,8 +133,11 @@ public Span log(long timestampMicroseconds, String event) { } /** - * {@inheritDoc} + * This is a NOOP as neither B3 + * nor Brave include baggage support. */ + // OpenTracing could one day define a way to plug-in arbitrary baggage handling similar to how + // it has feature-specific apis like active-span @Override public Span setBaggageItem(String key, String value) { // brave does not support baggage @@ -142,11 +145,13 @@ public Span setBaggageItem(String key, String value) { } /** - * {@inheritDoc} + * Returns null as neither B3 + * nor Brave include baggage support. */ + // OpenTracing could one day define a way to plug-in arbitrary baggage handling similar to how + // it has feature-specific apis like active-span @Override public String getBaggageItem(String key) { - // brave does not support baggage return null; } diff --git a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java index 286a1d7..a3aeda2 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java +++ b/src/main/java/brave/features/opentracing/BraveSpanBuilder.java @@ -122,8 +122,11 @@ public Span start() { } /** - * {@inheritDoc} + * Returns zero values as neither B3 + * nor Brave include baggage support. */ + // OpenTracing could one day define a way to plug-in arbitrary baggage handling similar to how + // it has feature-specific apis like active-span @Override public Iterable> baggageItems() { // brave doesn't support baggage diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/features/opentracing/BraveTracer.java index 39d6ef4..4c3ce66 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/features/opentracing/BraveTracer.java @@ -17,8 +17,6 @@ import brave.propagation.Propagation; import brave.propagation.TraceContext; import brave.propagation.TraceContextOrSamplingFlags; -import com.github.kristofa.brave.Brave; -import com.github.kristofa.brave.TracerAdapter; import io.opentracing.SpanContext; import io.opentracing.Tracer; import io.opentracing.propagation.Format; @@ -36,7 +34,6 @@ public class BraveTracer implements Tracer { static final TraceContext.Extractor EXTRACTOR = Propagation.B3_STRING.extractor(TextMapView::get); private brave.Tracer brave4; - private Brave brave3; // Not sure if I need this or not. Might want to attach to the local tracer context public static BraveTracer wrap(brave.Tracer brave4) { if (brave4 == null) throw new NullPointerException("brave tracer == null"); @@ -45,7 +42,6 @@ public static BraveTracer wrap(brave.Tracer brave4) { private BraveTracer(brave.Tracer brave4) { this.brave4 = brave4; - this.brave3 = TracerAdapter.newBrave(this.brave4); } /** From 05cc1abf2287c80e2bb6d8097a78edab15ef43bd Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Wed, 25 Jan 2017 11:56:15 -0500 Subject: [PATCH 13/17] Better context object construction --- .../java/brave/features/opentracing/BraveSpanContext.java | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/main/java/brave/features/opentracing/BraveSpanContext.java b/src/main/java/brave/features/opentracing/BraveSpanContext.java index cddc8de..b6c3db4 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanContext.java +++ b/src/main/java/brave/features/opentracing/BraveSpanContext.java @@ -24,9 +24,11 @@ public class BraveSpanContext implements SpanContext { private TraceContext traceContext; static BraveSpanContext wrap(TraceContext traceContext) { - BraveSpanContext context = new BraveSpanContext(); - context.traceContext = traceContext; - return context; + return new BraveSpanContext(traceContext); + } + + private BraveSpanContext(TraceContext traceContext) { + this.traceContext = traceContext; } final TraceContext unwrap() { From d88970eda5579454b232be67158b54d42b17c3d1 Mon Sep 17 00:00:00 2001 From: Brian Devins Date: Fri, 3 Feb 2017 06:51:55 -0500 Subject: [PATCH 14/17] Code review changes, finalizing all types. Should be closer. Needs more javadoc --- .../{features => }/opentracing/BraveSpan.java | 76 +++++++++++++------ .../opentracing/BraveSpanBuilder.java | 13 ++-- .../opentracing/BraveSpanContext.java | 27 +++++-- .../opentracing/BraveTracer.java | 25 ++++-- .../BraveTracerTest.java} | 5 +- 5 files changed, 101 insertions(+), 45 deletions(-) rename src/main/java/brave/{features => }/opentracing/BraveSpan.java (74%) rename src/main/java/brave/{features => }/opentracing/BraveSpanBuilder.java (94%) rename src/main/java/brave/{features => }/opentracing/BraveSpanContext.java (60%) rename src/main/java/brave/{features => }/opentracing/BraveTracer.java (84%) rename src/test/java/brave/{features/opentracing/OpenTracingAdapterTest.java => opentracing/BraveTracerTest.java} (98%) diff --git a/src/main/java/brave/features/opentracing/BraveSpan.java b/src/main/java/brave/opentracing/BraveSpan.java similarity index 74% rename from src/main/java/brave/features/opentracing/BraveSpan.java rename to src/main/java/brave/opentracing/BraveSpan.java index 3c96541..4a9d14e 100644 --- a/src/main/java/brave/features/opentracing/BraveSpan.java +++ b/src/main/java/brave/opentracing/BraveSpan.java @@ -11,26 +11,33 @@ * or implied. See the License for the specific language governing permissions and limitations under * the License. */ -package brave.features.opentracing; +package brave.opentracing; import io.opentracing.Span; import io.opentracing.SpanContext; +import java.util.Iterator; import java.util.Map; -public class BraveSpan implements Span { +public final class BraveSpan implements Span { + /** + * Converts an existing {@linkplain brave.Span} for use in OpenTracing apis + */ static BraveSpan wrap(brave.Span span) { if (span == null) throw new NullPointerException("span == null"); return new BraveSpan(span); } - final brave.Span unwrap() { + /** + * Converts an existing {@linkplain brave.Span} for use in OpenTracing apis + */ + public final brave.Span unwrap() { return delegate; } - final brave.Span delegate; - final SpanContext context; + private final brave.Span delegate; + private final SpanContext context; private BraveSpan(brave.Span delegate) { this.delegate = delegate; @@ -101,7 +108,7 @@ public Span setTag(String key, Number value) { public Span log(Map fields) { if (fields.isEmpty()) return this; // in real life, do like zipkin-go-opentracing: "key1=value1 key2=value2" - return log(fields.toString()); + return log(toAnnotation(fields)); } /** @@ -111,7 +118,30 @@ public Span log(Map fields) { public Span log(long timestampMicroseconds, Map fields) { if (fields.isEmpty()) return this; // in real life, do like zipkin-go-opentracing: "key1=value1 key2=value2" - return log(timestampMicroseconds, fields.toString()); + return log(timestampMicroseconds, toAnnotation(fields)); + } + + /** + * Converts a map to a string of form: "key1=value1 key2=value2" + */ + static String toAnnotation(Map fields) { + // special-case the "event" field which is similar to the semantics of a zipkin annotation + Object event = fields.get("event"); + if (event != null && fields.size() == 1) return event.toString(); + + return joinOnEqualsSpace(fields); + } + + static String joinOnEqualsSpace(Map fields) { + if (fields.isEmpty()) return ""; + + StringBuilder result = new StringBuilder(); + for (Iterator> i = fields.entrySet().iterator(); i.hasNext(); ) { + Map.Entry next = i.next(); + result.append(next.getKey()).append('=').append(next.getValue()); + if (i.hasNext()) result.append(' '); + } + return result.toString(); } /** @@ -132,6 +162,22 @@ public Span log(long timestampMicroseconds, String event) { return this; } + /** + * {@inheritDoc} + */ + @Override + public Span log(String eventName, Object ignored) { + return log(eventName); + } + + /** + * {@inheritDoc} + */ + @Override + public Span log(long timestampMicroseconds, String eventName, Object ignored) { + return log(timestampMicroseconds, eventName); + } + /** * This is a NOOP as neither B3 * nor Brave include baggage support. @@ -163,20 +209,4 @@ public Span setOperationName(String operationName) { delegate.name(operationName); return this; } - - /** - * {@inheritDoc} - */ - @Override - public Span log(String eventName, Object ignored) { - return log(eventName); - } - - /** - * {@inheritDoc} - */ - @Override - public Span log(long timestampMicroseconds, String eventName, Object ignored) { - return log(timestampMicroseconds, eventName); - } } diff --git a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java b/src/main/java/brave/opentracing/BraveSpanBuilder.java similarity index 94% rename from src/main/java/brave/features/opentracing/BraveSpanBuilder.java rename to src/main/java/brave/opentracing/BraveSpanBuilder.java index a3aeda2..403ad60 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanBuilder.java +++ b/src/main/java/brave/opentracing/BraveSpanBuilder.java @@ -11,7 +11,7 @@ * or implied. See the License for the specific language governing permissions and limitations under * the License. */ -package brave.features.opentracing; +package brave.opentracing; import brave.propagation.TraceContext; import io.opentracing.References; @@ -23,17 +23,16 @@ import java.util.LinkedHashMap; import java.util.Map; -public class BraveSpanBuilder implements Tracer.SpanBuilder { +public final class BraveSpanBuilder implements Tracer.SpanBuilder { - private brave.Tracer brave; - - private String operationName; + private final brave.Tracer brave; private final Map tags = new LinkedHashMap<>(); - long timestamp; + private String operationName; + private long timestamp; private TraceContext parent; - public BraveSpanBuilder(brave.Tracer brave, String operationName) { + BraveSpanBuilder(brave.Tracer brave, String operationName) { this.brave = brave; this.operationName = operationName; } diff --git a/src/main/java/brave/features/opentracing/BraveSpanContext.java b/src/main/java/brave/opentracing/BraveSpanContext.java similarity index 60% rename from src/main/java/brave/features/opentracing/BraveSpanContext.java rename to src/main/java/brave/opentracing/BraveSpanContext.java index b6c3db4..315cd1d 100644 --- a/src/main/java/brave/features/opentracing/BraveSpanContext.java +++ b/src/main/java/brave/opentracing/BraveSpanContext.java @@ -11,7 +11,7 @@ * or implied. See the License for the specific language governing permissions and limitations under * the License. */ -package brave.features.opentracing; +package brave.opentracing; import brave.propagation.TraceContext; import io.opentracing.SpanContext; @@ -19,24 +19,35 @@ import java.util.Collections; import java.util.Map; -public class BraveSpanContext implements SpanContext { +/** + * Holds the {@linkplain TraceContext} used by the underlying {@linkplain brave.Tracer}. An + * {@link TraceContext#sampled() unsampled} context results in a {@link opentracing...NoopSpan}. + * + *

This type also includes hooks to integrate with the underlying {@linkplain brave.Tracer}. + * Ex you can access the underlying trace context with {@link #unwrap} + */ +public final class BraveSpanContext implements SpanContext { - private TraceContext traceContext; + private final TraceContext traceContext; static BraveSpanContext wrap(TraceContext traceContext) { return new BraveSpanContext(traceContext); } - private BraveSpanContext(TraceContext traceContext) { - this.traceContext = traceContext; + /** + * Returns the underlying trace context for use in Brave apis + */ + public TraceContext unwrap() { + return traceContext; } - final TraceContext unwrap() { - return traceContext; + private BraveSpanContext(TraceContext traceContext) { + this.traceContext = traceContext; } /** - * {@inheritDoc} + * Returns empty as neither B3 + * nor Brave include baggage support. */ @Override public Iterable> baggageItems() { diff --git a/src/main/java/brave/features/opentracing/BraveTracer.java b/src/main/java/brave/opentracing/BraveTracer.java similarity index 84% rename from src/main/java/brave/features/opentracing/BraveTracer.java rename to src/main/java/brave/opentracing/BraveTracer.java index 4c3ce66..fe5ffe2 100644 --- a/src/main/java/brave/features/opentracing/BraveTracer.java +++ b/src/main/java/brave/opentracing/BraveTracer.java @@ -11,7 +11,7 @@ * or implied. See the License for the specific language governing permissions and limitations under * the License. */ -package brave.features.opentracing; +package brave.opentracing; import brave.internal.Nullable; import brave.propagation.Propagation; @@ -27,14 +27,28 @@ import java.util.List; import java.util.Map; -public class BraveTracer implements Tracer { +/** + * Using a tracer, you can create a spans, inject span contexts into a transport, and extract span contexts from a + * transport + * + * Here's an example: + * 


+ *
+ * @see BraveSpan
+ * @see Propagation
+ */
+public final class BraveTracer implements Tracer {
 
     static final List PROPAGATION_KEYS = Propagation.B3_STRING.keys();
     static final TraceContext.Injector INJECTOR = Propagation.B3_STRING.injector(TextMap::put);
     static final TraceContext.Extractor EXTRACTOR = Propagation.B3_STRING.extractor(TextMapView::get);
 
-    private brave.Tracer brave4;
+    private final brave.Tracer brave4;
 
+    /**
+     * Returns an implementation of {@linkplain io.opentracing.Tracer} which delegates
+     * the the provided Brave Tracer.
+     */
     public static BraveTracer wrap(brave.Tracer brave4) {
         if (brave4 == null) throw new NullPointerException("brave tracer == null");
         return new BraveTracer(brave4);
@@ -53,7 +67,7 @@ public SpanBuilder buildSpan(String operationName) {
     }
 
     /**
-     * {@inheritDoc}
+     * Injects the underlying context using B3 encoding.
      */
     @Override
     public  void inject(SpanContext spanContext, Format format, C carrier) {
@@ -65,7 +79,8 @@ public  void inject(SpanContext spanContext, Format format, C carrier) {
     }
 
     /**
-     * {@inheritDoc}
+     * Extracts the underlying context using B3 encoding.
+     * A new trace context is provisioned when there is no B3-encoded context in the carrier, or upon error extracting it.
      */
     @Override
     public  SpanContext extract(Format format, C carrier) {
diff --git a/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java b/src/test/java/brave/opentracing/BraveTracerTest.java
similarity index 98%
rename from src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java
rename to src/test/java/brave/opentracing/BraveTracerTest.java
index 766d9a6..6b8b347 100644
--- a/src/test/java/brave/features/opentracing/OpenTracingAdapterTest.java
+++ b/src/test/java/brave/opentracing/BraveTracerTest.java
@@ -11,7 +11,7 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-package brave.features.opentracing;
+package brave.opentracing;
 
 import brave.Tracer;
 import brave.propagation.TraceContext;
@@ -34,7 +34,8 @@
  * This shows how one might make an OpenTracing adapter for Brave, and how to navigate in and out
  * of the core concepts.
  */
-public class OpenTracingAdapterTest {
+public class BraveTracerTest {
+
     List spans = new ArrayList<>();
     Tracer brave = Tracer.newBuilder().reporter(spans::add).build();
     BraveTracer opentracing = BraveTracer.wrap(brave);

From 00cc6c8e02f706fb142776c62ad28b644213b255 Mon Sep 17 00:00:00 2001
From: Brian Devins 
Date: Fri, 3 Feb 2017 07:13:36 -0500
Subject: [PATCH 15/17] Better block comment for BraveTracer

---
 src/main/java/brave/opentracing/BraveTracer.java | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/src/main/java/brave/opentracing/BraveTracer.java b/src/main/java/brave/opentracing/BraveTracer.java
index fe5ffe2..9da6477 100644
--- a/src/main/java/brave/opentracing/BraveTracer.java
+++ b/src/main/java/brave/opentracing/BraveTracer.java
@@ -32,7 +32,17 @@
  * transport
  *
  * Here's an example:
- * 

+ * 
+ *     Tracer tracer = BraveTracer.wrap(brave4);
+ *
+ *     Span span = tracer.buildSpan("DoWork").start();
+ *     tracer.inject(span.context());
+ *
+ *     ...
+ *
+ *     SpanContext clientContext = tracer.extract(Format.Builtin.HTTP_HEADERS, request.getHeaders());
+ *     Span clientSpan = tracer.buildSpan('...').asChildOf(clientContext).start();
+ * 

  *
  * @see BraveSpan
  * @see Propagation

From 8bd0a294487a29ce9d2b4b266503de859b053fc4 Mon Sep 17 00:00:00 2001
From: Brian Devins 
Date: Fri, 3 Feb 2017 07:25:29 -0500
Subject: [PATCH 16/17] More documentation

---
 src/main/java/brave/opentracing/BraveSpan.java        | 6 ++++++
 src/main/java/brave/opentracing/BraveSpanBuilder.java | 7 ++++++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/main/java/brave/opentracing/BraveSpan.java b/src/main/java/brave/opentracing/BraveSpan.java
index 4a9d14e..a935b9b 100644
--- a/src/main/java/brave/opentracing/BraveSpan.java
+++ b/src/main/java/brave/opentracing/BraveSpan.java
@@ -19,6 +19,12 @@
 import java.util.Iterator;
 import java.util.Map;
 
+/**
+ * Holds the {@linkplain brave.Span} used by the underlying {@linkplain brave.Tracer}.\
+ *
+ * 
This type also includes hooks to integrate with the underlying {@linkplain brave.Tracer}.
+ * Ex you can access the underlying span with {@link #unwrap}
+ */
 public final class BraveSpan implements Span {
 
     /**
diff --git a/src/main/java/brave/opentracing/BraveSpanBuilder.java b/src/main/java/brave/opentracing/BraveSpanBuilder.java
index 403ad60..769d2a5 100644
--- a/src/main/java/brave/opentracing/BraveSpanBuilder.java
+++ b/src/main/java/brave/opentracing/BraveSpanBuilder.java
@@ -23,6 +23,11 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+/**
+ * Uses by the underlying {@linkplain brave.Tracer} to create a {@linkplain BraveSpan} wrapped {@linkplain brave.Span}
+ *
+ * Brave does not support multiple parents so this has been implemented to use the first parent defined.
+ */
 public final class BraveSpanBuilder implements Tracer.SpanBuilder {
 
     private final brave.Tracer brave;
@@ -105,7 +110,7 @@ public Tracer.SpanBuilder withStartTimestamp(long microseconds) {
      * {@inheritDoc}
      */
     @Override
-    public Span start() {
+    public BraveSpan start() {
         brave.Span span = parent == null ? brave.newTrace() : brave.newChild(parent);
         if (operationName != null) span.name(operationName);
         for (Map.Entry tag : tags.entrySet()) {

From 113631c9398a3bc3176db45ea425bf6d8e2c4774 Mon Sep 17 00:00:00 2001
From: Brian Devins 
Date: Fri, 3 Feb 2017 10:13:04 -0500
Subject: [PATCH 17/17] Modify startup section of readme

---
 README.md | 14 ++------------
 1 file changed, 2 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 799b360..9315ed2 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,8 @@ Some example code demonstrating how the OpenTracing API is to be used.
 
 Code in the first process…
 
-    BraveTracer tracer = new BraveTracer();
+    Tracer brave4 = Tracer.newBuilder()....build();
+    io.opentracing.Tracer tracer = BraveTracer.wrap(brave4);
 
     // start a span
     try ( Span span0 = tracer.buildSpan("span-0")
@@ -76,14 +77,3 @@ Code in the second process
     }
 
 This code repeats from process to process, as far through the stack as required.
-
-## Status
-
-OpenTracing spans created are represented by Brave's local spans. When an OpenTracing span is injected into a protocol's wire a client Brave span is created. Likewise when an OpenTracing span is extracted from a protocol wire a server Brave span is created.
-
-There is a mismatch between the two APIs in how state of the current span is held. OpenTracing does not hold any such state and passes in the
- current span intended to be a parent is an explicit action in the API, while in Brave this state is known and such action not required. OpenTracing's
- expectations are honoured here and Brave's internal state is overridden as needed.
-
-It is noted that it probably would have been simpler to have implemented against lower APIs in brave, like directly against the collector and spans,
- than the top level Brave api. Hopefully this improvement happens in the short-term, otherwise the API usage for the user will not change.