From 60d90194e3a190fc63a769dff6366843d239aece Mon Sep 17 00:00:00 2001 From: mck Date: Sun, 31 Jan 2016 11:18:19 +1100 Subject: [PATCH] Remove TraceContext, as has already been done in the specification. Remove TraceContextSource, as methods from it now belong in Tracer. Remove Tracer.joinTrace(..) as Span.startChild(..) already does this. ref: - https://github.com/opentracing/opentracing.github.io/pull/42 - https://github.com/opentracing/opentracing-java/pull/7 --- .../src/main/java/opentracing/Span.java | 7 +- ...eContextCodec.java => SpanPropagator.java} | 31 ++++----- .../main/java/opentracing/TraceContext.java | 66 ------------------- .../java/opentracing/TraceContextSource.java | 48 -------------- .../src/main/java/opentracing/Tracer.java | 19 +----- 5 files changed, 19 insertions(+), 152 deletions(-) rename opentracing/src/main/java/opentracing/{TraceContextCodec.java => SpanPropagator.java} (54%) delete mode 100644 opentracing/src/main/java/opentracing/TraceContext.java delete mode 100644 opentracing/src/main/java/opentracing/TraceContextSource.java diff --git a/opentracing/src/main/java/opentracing/Span.java b/opentracing/src/main/java/opentracing/Span.java index df2b1bc9..bd965acb 100644 --- a/opentracing/src/main/java/opentracing/Span.java +++ b/opentracing/src/main/java/opentracing/Span.java @@ -22,11 +22,6 @@ */ public interface Span { - /** - * Suitable for serializing over the wire, etc. - */ - TraceContext traceContext(); - /** * Denotes the beginning of a subordinate unit of work. * @@ -64,6 +59,8 @@ public interface Span { // 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); + /** * {@code message} is a format string and can refer to fields in the payload by path, like so: * diff --git a/opentracing/src/main/java/opentracing/TraceContextCodec.java b/opentracing/src/main/java/opentracing/SpanPropagator.java similarity index 54% rename from opentracing/src/main/java/opentracing/TraceContextCodec.java rename to opentracing/src/main/java/opentracing/SpanPropagator.java index a0455f09..92537efd 100644 --- a/opentracing/src/main/java/opentracing/TraceContextCodec.java +++ b/opentracing/src/main/java/opentracing/SpanPropagator.java @@ -16,15 +16,16 @@ import java.util.Map; /** - * Encodes or Decodes a {@linkplain TraceContext trace context} in binary or text formats. + * Encodes or Decodes a {@linkplain Span span} in binary or text formats. * - *

The toXXX methods are expected to serialize trace contexts into a pair of values representing - * separately the trace context / 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 + *

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 TraceContextCodec { +public interface SpanPropagator { /** * Implementation-specific format of a span's identity along with any trace attributes. @@ -32,8 +33,8 @@ public interface TraceContextCodec { * @param encoding, for example {@code byte[]} for binary, or {@code Map} for * text. */ - // Can instead explicitly create BinaryEncodedTraceContext, TextEncodedTraceContext, just.. cluttery - interface EncodedTraceContext { + // Can instead explicitly create BinaryEncodedSpan, TextEncodedSpan, just.. cluttery + interface EncodedSpan { /** Encoded span identifier. */ E spanIdentity(); @@ -42,30 +43,30 @@ interface EncodedTraceContext { } /** - * Encodes the trace context into a binary representation of the span's identity and trace + * Encodes the span into a binary representation of the span's identity and trace * attributes. */ - EncodedTraceContext toBinary(TraceContext tc); + EncodedSpan toBinary(Span tc); /** - * Decodes a trace context from a binary representation of the span's identity and trace + * Decodes a span from a binary representation of the span's identity and trace * attributes. * * @throws IllegalArgumentException if the encoded data is malformed. */ - TraceContext fromBinary(EncodedTraceContext encoded); + Span fromBinary(EncodedSpan encoded); /** - * Encodes the trace context into a text representation of the span's identity and trace + * Encodes the span into a text representation of the span's identity and trace * attributes. */ - EncodedTraceContext> toText(TraceContext tc); + EncodedSpan> toText(Span tc); /** - * Decodes a trace context from a text representation of the span's identity and trace + * Decodes a span from a text representation of the span's identity and trace * attributes. * * @throws IllegalArgumentException if the encoded data is malformed. */ - TraceContext fromText(EncodedTraceContext> encoded); + Span fromText(EncodedSpan> encoded); } diff --git a/opentracing/src/main/java/opentracing/TraceContext.java b/opentracing/src/main/java/opentracing/TraceContext.java deleted file mode 100644 index d69f24f9..00000000 --- a/opentracing/src/main/java/opentracing/TraceContext.java +++ /dev/null @@ -1,66 +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; - -/** - * TraceContext encpasulates the smallest amount of state needed to describe a Span's identity - * within a larger [potentially distributed] trace. The TraceContext is not intended to encode the - * span's operation name, timing, or log data, but merely any unique identifiers (etc) needed to - * contextualize it within a larger trace tree. - * - *

TraceContexts are sufficient to propagate the, well, *context* of a particular trace between - * processes. - * - *

TraceContext also support a simple string map of "trace attributes". These trace attributes - * are special in that they are propagated *in-band*, presumably alongside application data. See the - * documentation for {@link #setAttribute(String, String)} for more details and some important - * caveats. - */ -public interface TraceContext { - - /** - * Sets a tag on this TraceContext that also propagates to future children per {@link - * TraceContextSource#newChild(TraceContext)}. - * - *

Trace attributes enables powerful functionality given a full-stack opentracing integration - * (e.g., arbitrary application data from a mobile app can make it, transparently, all the way - * into the depths of a storage system), and with it some powerful costs: use this feature with - * care. - * - *

IMPORTANT NOTE #1: This will only propagate trace attributes to *future* children of the - * TraceContextSource#newChild(TraceContext)} and/or the Span that references it. - * - *

IMPORTANT NOTE #2: Use this thoughtfully and with care. Every key and value is copied into - * every local *and remote* child of this TraceContext, and that can add up to a lot of network - * and cpu overhead. - * - *

IMPORTANT NOTE #3: Trace attributes keys have a restricted format: implementations may wish - * to use them as HTTP header keys (or key suffixes), and of course HTTP headers are case - * insensitive. - * - * @param restrictedKey MUST match the regular expression `(?i:[a-z0-9][-a-z0-9]*)` and is - * case-insensitive. That is, it must start with a letter or number, and the remaining characters - * must be letters, numbers, or hyphens. undefined behavior results if the `restrictedKey` does - * not meet these criteria. - */ - TraceContext setAttribute(String restrictedKey, String value); - - /** - * Gets the value for a trace tag given its key. Returns Null if the value isn't found in this - * TraceContext. - * - * @param restrictedKey see {@link #setAttribute(String, String)} notes. - */ - String getAttribute(String restrictedKey); -} diff --git a/opentracing/src/main/java/opentracing/TraceContextSource.java b/opentracing/src/main/java/opentracing/TraceContextSource.java deleted file mode 100644 index f8f9ea4a..00000000 --- a/opentracing/src/main/java/opentracing/TraceContextSource.java +++ /dev/null @@ -1,48 +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; - -/** - * Long-lived interface that knows how to create a root {@linkplain TraceContext} and encode/decode - * any other. - */ -public interface TraceContextSource { - - /** - * Encodes or Decodes a {@linkplain TraceContext trace context} in binary or text formats. - */ - TraceContextCodec codec(); - - /** - * Create a TraceContext which has no parent (and thus begins its own trace). - * - *

A TraceContextSource must always return the same type in successive calls to - * NewRootTraceContext(). - */ - TraceContext newRoot(); - - /** - * Creates a child context for {@code parent}, and returns both that child's own - * TraceContext as well as any Tags that should be added to the child's Span. - */ - ChildTraceContext newChild(TraceContext parent); - - interface ChildTraceContext { - TraceContext child(); - - Map tags(); - } -} diff --git a/opentracing/src/main/java/opentracing/Tracer.java b/opentracing/src/main/java/opentracing/Tracer.java index f62d1e4d..163fc73c 100644 --- a/opentracing/src/main/java/opentracing/Tracer.java +++ b/opentracing/src/main/java/opentracing/Tracer.java @@ -33,22 +33,5 @@ public interface Tracer { */ Span startTrace(String operationName); - /** - * Like {@link #startTrace(String)}, but the returned span is made a child of {@code parent}. - */ - Span joinTrace(String operationName, TraceContext parent); - - /** - * StartSpanWithContext returns a span with the given {@code operationName} and an association - * with {@code context} (rather than creating a fresh root context like {@link - * #startTrace(String)} or a fresh child context like {@link #joinTrace(String, TraceContext)}). - * - *

Note that the following calls are equivalent - * 

{@code
-   * Span feed = tracer.startSpanWithContext("GetFeed", traceContextSource.newRoot());
-   * ...
-   * Span feed = tracer.startTrace("GetFeed");
-   * }
- */ - Span startSpanWithContext(String operationName, TraceContext context); + SpanPropagator getSpanPropagator(); }