Merge pull request #13 from opentracing/interfaces

Initial opentracing-java API

opentracing/src/main/java/opentracing/Span.java

@@ -0,0 +1,76 @@
+/**
+ * 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;
+
+/**
+ * Represents an in-flight span in the opentracing system.
+ *
+ * <p>Spans are created by the {@link Tracer#buildSpan} interface.
+ */
+public interface Span {
+
+  /**
+   * Sets the end timestamp and records the span.
+   *
+   * <p>This should be the last call made to any span instance, and to do otherwise leads to
+   * undefined behavior.
+   */
+  void finish();
+
+  /**
+   * Set a key:value tag on the Span.
+   */
+  // overloaded 3x to support the BasicType concern
+  Span setTag(String key, String value);
+
+  /** Same as {@link #setTag(String, String)}, but for boolean values. */
+  Span setTag(String key, boolean value);
+
+  /** Same as {@link #setTag(String, String)}, but for numeric values. */
+  Span setTag(String key, Number 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.
+   *
+   * 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).
+   *
+   * The timestamp of this log event is the current time.
+   **/
+  Span log(String eventName, /* @Nullable */ Object payload);
+
+  /**
+   * 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).
+   *
+   * The timestamp is specified manually here to represent a past log event.
+   * The timestamp in microseconds in UTC time.
+   **/
+  Span log(long timestampMicroseconds, String eventName, /* @Nullable */ Object payload);
+}

opentracing/src/main/java/opentracing/Tracer.java

@@ -0,0 +1,105 @@
+/**
+ * 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;
+
+
+/**
+ * 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`.
+   * An optional parent Span can be specified used to incorporate the newly-returned Span into an existing trace.
+   *
+   * <p>Example:
+   * <pre>{@code
+    Tracer tracer = ...
+
+    Span feed = tracer.buildSpan("GetFeed")
+                      .start();
+
+    Span http = tracer.buildSpan("HandleHTTPRequest")
+                      .withParent(feed)
+                      .withTag("user_agent", req.UserAgent)
+                      .withTag("lucky_number", 42)
+                      .start();
+    }</pre>
+   */
+  SpanBuilder buildSpan(String operationName);
+
+  /** Takes two arguments:
+   *    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).
+   *
+   * 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);
+
+  /**  Returns a SpanBuilder provided
+   *    a “carrier” object from which to extract identifying information needed by the new Span instance.
+   *
+   * If the carrier object has no such span stored within it, a new Span is created.
+   *
+   * Unless there’s an error, it returns a SpanBuilder.
+   * The Span generated from the builder 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)
+   *
+   * 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.
+       *
+       * If the operationName has already been set (implicitly or explicitly) an IllegalStateException will be thrown.
+       */
+      SpanBuilder withOperationName(String operationName);
+
+      /** Specify the parent span
+       *
+       * If the parent has already been set an IllegalStateException will be thrown.
+       */
+      SpanBuilder withParent(Span parent);
+
+      /** Same as {@link Span#setTag(String, String)}, but for the span being built. */
+      SpanBuilder withTag(String key, String value);
+
+      /** Same as {@link Span#setTag(String, String)}, but for the span being built. */
+      SpanBuilder withTag(String key, boolean value);
+
+      /** 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);
+  }
+}