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.
*/