From 87a0c6d5135e277402b160a1741d1209f0ef98b5 Mon Sep 17 00:00:00 2001 From: mck Date: Sun, 21 Feb 2016 19:45:04 +1100 Subject: [PATCH] Put into place the top-level design that fulfils the new Specification - Only span creation method is in Tracer.startSpan(..) - Add Tracer's inject(..) and join(..) methods reference: https://github.com/opentracing/opentracing-java/pull/10 --- .../src/main/java/opentracing/Span.java | 24 +++---- .../main/java/opentracing/SpanPropagator.java | 72 ------------------- .../src/main/java/opentracing/Tracer.java | 36 ++++++++-- 3 files changed, 40 insertions(+), 92 deletions(-) delete mode 100644 opentracing/src/main/java/opentracing/SpanPropagator.java diff --git a/opentracing/src/main/java/opentracing/Span.java b/opentracing/src/main/java/opentracing/Span.java index 7aa4f8b1..8269a8af 100644 --- a/opentracing/src/main/java/opentracing/Span.java +++ b/opentracing/src/main/java/opentracing/Span.java @@ -16,19 +16,10 @@ /** * Span represents an active, un-finished span in the opentracing system. * - *

Spans are created by the {@link Tracer} interface and {@link #startChild(String)}. + *

Spans are created by the {@link Tracer} interface. */ public interface Span { - /** - * Denotes the beginning of a subordinate unit of work. - * - * @param operationName name of the operation represened by the new span from the perspective of - * the current service. - * @return a new child Span in "started" state. - */ - Span startChild(String operationName); - /** * Sets the end timestamp and records the span. * @@ -38,7 +29,7 @@ public interface Span { void finish(); /** - * Adds a tag to the span. + * Set a key:value tag on the Span. * *

Tag values can be of arbitrary types, however the treatment of complex types is dependent on * the underlying tracing system implementation. It is expected that most tracing systems will @@ -54,10 +45,17 @@ public interface Span { Span setTag(String key, boolean value); /** Same as {@link #setTag(String, String)}, but for numeric values. */ - // numbers kindof suck.. we've no idea if this is a float, how many bits, etc. Span setTag(String key, Number value); - Span setTraceAttribute(String key, String value); + /** + * Set a Baggage item, represented as a simple string:string pair. + * + * Note that newly-set Baggage items are only guaranteed to propagate to future children of the given Span. + */ + Span setBaggageItem(String key, String value); + + /** Get a Baggage item by key. */ + String getBaggageItem(String key); /** * * Add a new log event to the Span, accepting an event name string and an optional structured payload argument. diff --git a/opentracing/src/main/java/opentracing/SpanPropagator.java b/opentracing/src/main/java/opentracing/SpanPropagator.java deleted file mode 100644 index 92537efd..00000000 --- a/opentracing/src/main/java/opentracing/SpanPropagator.java +++ /dev/null @@ -1,72 +0,0 @@ -/** - * Copyright 2016 The OpenTracing 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 opentracing; - -import java.util.Map; - -/** - * Encodes or Decodes a {@linkplain Span span} in binary or text formats. - * - *

The toXXX methods are expected to serialize spans into a pair of values representing - * separately the span / span identity, and the trace attributes. - * - * This is done specifically for binary protocols that may represent tracing identity in a dedicated fixed-length slot in the - * binary message format, so that it can be inspected efficiently by the middleware / routing layers - * without parsing the whole message. - */ -public interface SpanPropagator { - - /** - * Implementation-specific format of a span's identity along with any trace attributes. - * - * @param encoding, for example {@code byte[]} for binary, or {@code Map} for - * text. - */ - // Can instead explicitly create BinaryEncodedSpan, TextEncodedSpan, just.. cluttery - interface EncodedSpan { - /** Encoded span identifier. */ - E spanIdentity(); - - /** Encoded trace attributes, or null if none were encoded. */ - E traceAttributes(); - } - - /** - * Encodes the span into a binary representation of the span's identity and trace - * attributes. - */ - EncodedSpan toBinary(Span tc); - - /** - * Decodes a span from a binary representation of the span's identity and trace - * attributes. - * - * @throws IllegalArgumentException if the encoded data is malformed. - */ - Span fromBinary(EncodedSpan encoded); - - /** - * Encodes the span into a text representation of the span's identity and trace - * attributes. - */ - EncodedSpan> toText(Span tc); - - /** - * Decodes a span from a text representation of the span's identity and trace - * attributes. - * - * @throws IllegalArgumentException if the encoded data is malformed. - */ - Span fromText(EncodedSpan> encoded); -} diff --git a/opentracing/src/main/java/opentracing/Tracer.java b/opentracing/src/main/java/opentracing/Tracer.java index 163fc73c..2808ffa1 100644 --- a/opentracing/src/main/java/opentracing/Tracer.java +++ b/opentracing/src/main/java/opentracing/Tracer.java @@ -13,25 +13,47 @@ */ package opentracing; + /** - * Tracer is a simple, thin interface for Span creation. + * Tracer is a simple, thin interface for Span creation, and Span propagation into different transport formats. */ public interface Tracer { /** - * Create, start, and return a new Span with the given `operationName`, all without specifying a - * parent Span that can be used to incorporate the newly-returned Span into an existing trace. + * Create, start, and return a new Span with the given `operationName`. + * An optional parent Span can be specified used to incorporate the newly-returned Span into an existing trace. * *

Example: * 

{@code
    * Tracer tracer = ...
-   * Span feed = tracer.startTrace("GetFeed");
-   * Span http = tracer.startTrace("HandleHTTPRequest")
+   * Span feed = tracer.startTrace("GetFeed", null);
+   * Span http = tracer.startTrace("HandleHTTPRequest", feed)
    *                   .setTag("user_agent", req.UserAgent)
    *                   .setTag("lucky_number", 42);
    * }
*/ - Span startTrace(String operationName); + Span startSpan(String operationName, /* @Nullable */ Span parent); - SpanPropagator getSpanPropagator(); + /** + * Same as {@link #startSpan(String, Span)}, + * but allows to specify a past timestamp in microseconds when the Span was created. + */ + Span startSpan(String operationName, long microseconds, /* @Nullable */ Span parent); + + /** Takes two arguments: + * a Span instance, and + * a “carrier” object in which to inject that Span for cross-process propagation. + * + */ + void inject(Span span, T carrier); + + /** Takes two arguments: + * the operation name for the Span it’s about to create, and + * a “carrier” object from which to extract identifying information needed by the new Span instance. + * + * Unless there’s an error, it returns a freshly-started Span which can be used in the host process like any other. + * (Note that some OpenTracing implementations consider the Spans on either side of an RPC to have the same identity, + * and others consider the caller to be the parent and the receiver to be the child) + */ + Span join(String operationName, T carrier); }