diff --git a/opentracing/src/main/java/opentracing/Span.java b/opentracing/src/main/java/opentracing/Span.java index 8269a8af..56345843 100644 --- a/opentracing/src/main/java/opentracing/Span.java +++ b/opentracing/src/main/java/opentracing/Span.java @@ -14,9 +14,9 @@ package opentracing; /** - * Span represents an active, un-finished span in the opentracing system. + * Represents an in-flight span in the opentracing system. * - *

Spans are created by the {@link Tracer} interface. + *

Spans are created by the {@link Tracer#buildSpan} interface. */ public interface Span { @@ -30,13 +30,6 @@ public interface 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 - * handle primitive types like strings and numbers. If a tracing system cannot understand how to - * handle a particular value type, it may ignore the tag, but shall not panic. - * - *

If there is a pre-existing tag set for {@code key}, it is overwritten. */ // overloaded 3x to support the BasicType concern Span setTag(String key, String value); @@ -54,27 +47,46 @@ public interface 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. - * If specified, the payload argument may be of any type and arbitrary size, - * though implementations are not required to retain all payload arguments - * (or even all parts of all payload arguments). + /** Get a Baggage item by key. * - * The timestamp of this log event is the current time. - **/ - Span log(String eventName, /* @Nullable */ Object payload); + * Returns null if no entry found, or baggage is not supported in the current implementation. + */ + String getBaggageItem(String key); /** - * Add a new log event to the Span, accepting an event name string and an optional structured payload argument. - * If specified, the payload argument may be of any type and arbitrary size, - * though implementations are not required to retain all payload arguments - * (or even all parts of all payload arguments). + * Create an event builder. * - * The timestamp is specified manually here to represent a past log event. - * The timestamp in microseconds in UTC time. + * The timestamp of this log event is by default the time the EventBuilder is constructed. **/ - Span log(long instantMicroseconds, String eventName, /* @Nullable */ Object payload); + EventBuilder buildEvent(); + + interface EventBuilder { + + /** + * The event name should be the stable identifier for some notable moment in the lifetime of a Span. + * For instance, + * a Span representing a browser page load might add an event for each of the Performance.timing moments. + * + * While it is not a formal requirement, + * specific event names should apply to many Span instances: + * tracing systems can use these event names (and timestamps) to analyze Spans in the aggregate. + */ + EventBuilder withName(String name); + + /** + * Add the optional structured payload argument. + * If specified, the payload argument may be of any type and arbitrary size, + * though implementations are not required to retain all payload arguments + * (or even all parts of all payload arguments). + **/ + EventBuilder withPayload(Object payload); + + /** + * Add a specific timestamp, in microseconds since epoch. + **/ + EventBuilder withTimestamp(long microseconds); + + /** Build the log event, adding it to the Span, then return the Span. */ + Span log(); + } } diff --git a/opentracing/src/main/java/opentracing/Tracer.java b/opentracing/src/main/java/opentracing/Tracer.java index 7d66f5a9..3bd1e7db 100644 --- a/opentracing/src/main/java/opentracing/Tracer.java +++ b/opentracing/src/main/java/opentracing/Tracer.java @@ -43,6 +43,13 @@ public interface Tracer { * a Span instance, and * a “carrier” object in which to inject that Span for cross-process propagation. * + * A “carrier” object is some sort of http or rpc envelope, for example HeaderGroup (from Apache HttpComponents). + * + * The low-level format carriers Map<String,String> and ByteBuffer are guaranteed to be supported, + * otherwise only carriers that have been registered are supported. + * + * Attempting to inject to a carrier that has been registered/configured to this Tracer will result in a + * IllegalStateException. */ void inject(Span span, T carrier); @@ -56,9 +63,16 @@ public interface Tracer { * * (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) + * + * Attempting to join from a carrier that has been registered/configured to this Tracer will result in a + * IllegalStateException. + * + * If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in a + * IllegalArgumentException. */ SpanBuilder join(T carrier); + interface SpanBuilder { /** Specify the operationName. @@ -73,12 +87,6 @@ interface SpanBuilder { */ SpanBuilder withParent(Span parent); - /** Specify a timestamp the Span actually started from. - * - * If the timestamp has already been set an IllegalStateException will be thrown. - */ - SpanBuilder withTimestamp(long microseconds); - /** Same as {@link Span#setTag(String, String)}, but for the span being built. */ SpanBuilder withTag(String key, String value); @@ -88,7 +96,13 @@ interface SpanBuilder { /** Same as {@link Span#setTag(String, String)}, but for the span being built. */ SpanBuilder withTag(String key, Number value); + /** Specify a timestamp of when the Span was started, represented in microseconds since epoch. */ + SpanBuilder withStartTimestamp(long microseconds); + /** Returns the started Span. */ Span start(); + + /** Returns the Span, with a started timestamp (represented in microseconds) as specified. */ + Span start(long microseconds); } }