Apply the builder pattern to the Span.log(..) methods.

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.
  *
- * <p>Spans are created by the {@link Tracer} interface.
+ * <p>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.
-   *
-   * <p>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.
-   *
-   * <p>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();
+  }
 }

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.
    */
   <T> 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.
    */
   <T> 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);
   }
 }