Merge pull request #28118 from ColinBradley/dd-trace

dd-trace - compatibility with opentracing

types/dd-trace/package.json

@@ -0,0 +1,6 @@
+{
+    "private": true,
+    "dependencies": {
+        "opentracing": ">=0.14.1"
+    }
+}

types/dd-trace/src/opentracing/reference.d.ts

@@ -1,29 +0,0 @@
-import Span = require('./span');
-import SpanContext = require('./span_context');
-
-declare class Reference {
-    /**
-     * @return The Reference type (e.g., REFERENCE_CHILD_OF or
-     *         REFERENCE_FOLLOWS_FROM).
-     */
-    type(): string;
-
-    /**
-     * @return The SpanContext being referred to (e.g., the
-     *         parent in a REFERENCE_CHILD_OF Reference).
-     */
-    referencedContext(): SpanContext;
-
-    /**
-     * Initialize a new Reference instance.
-     *
-     * @param type - the Reference type constant (e.g.,
-     *        REFERENCE_CHILD_OF or REFERENCE_FOLLOWS_FROM).
-     * @param referencedContext - the SpanContext being referred
-     *        to. As a convenience, a Span instance may be passed in instead
-     *        (in which case its .context() is used here).
-     */
-    constructor(type: string, referencedContext: SpanContext | Span);
-}
-
-export = Reference;

types/dd-trace/src/opentracing/span.d.ts

@@ -1,7 +1,8 @@
 import Tracer = require('./tracer');
 import SpanContext = require('./span_context');
+import { Span } from 'opentracing';
 
-declare class Span {
+declare class DatadogSpan extends Span {
     /**
      * Returns the SpanContext object associated with this Span.
      */
@@ -117,4 +118,4 @@ declare class Span {
     finish(finishTime?: number): void;
 }
 
-export = Span;
+export = DatadogSpan;

types/dd-trace/src/opentracing/span_context.d.ts

@@ -1,3 +1,5 @@
+import { SpanContext } from 'opentracing';
+
 /**
  * SpanContext represents Span state that must propagate to descendant Spans
  * and across process boundaries.
@@ -8,7 +10,7 @@
  * identify or otherwise contextualize the associated Span instance (e.g., a
  * <trace_id, span_id, sampled> tuple).
  */
-declare class SpanContext {
+declare class DatadogSpanContext extends SpanContext {
     /**
      * Use to create references to parent spans.
      */
@@ -35,4 +37,4 @@ interface SpanContextLike {
     spanId: number;
 }
 
-export = SpanContext;
+export = DatadogSpanContext;

types/dd-trace/src/opentracing/span_options.d.ts

@@ -1,37 +0,0 @@
-import Span = require('./span');
-import Reference = require('./reference');
-import SpanContext = require('./span_context');
-
-interface SpanOptions {
-    /**
-     * a parent SpanContext (or Span, for convenience) that the newly-started
-     * span will be the child of (per REFERENCE_CHILD_OF). If specified,
-     * `references` must be unspecified.
-     */
-    childOf?: Span | SpanContext;
-
-    /**
-     * an array of Reference instances, each pointing to a causal parent
-     * SpanContext. If specified, `fields.childOf` must be unspecified.
-     */
-    references?: Reference[];
-
-    /**
-     * set of key-value pairs which will be set as tags on the newly created
-     * Span. Ownership of the object is passed to the created span for
-     * efficiency reasons (the caller should not modify this object after
-     * calling startSpan).
-     */
-    tags?: {
-        [key: string]: any;
-    };
-
-    /**
-     * a manually specified start time for the created Span object. The time
-     * should be specified in milliseconds as Unix timestamp. Decimal value are
-     * supported to represent time values with sub-millisecond accuracy.
-     */
-    startTime?: number;
-}
-
-export = SpanOptions;

types/dd-trace/src/opentracing/tracer.d.ts

@@ -1,91 +1,11 @@
-import SpanOptions = require('./span_options');
-import Span = require('./span');
-import SpanContext = require('./span_context');
+import { Tracer } from 'opentracing';
 
 /**
  * Tracer is the entry-point between the instrumentation API and the tracing
  * implementation.
  */
-declare class Tracer {
-    /**
-     * Starts and returns a new Span representing a logical unit of work.
-     *
-     * For example:
-     *
-     *     // Start a new (parentless) root Span:
-     *     var parent = Tracer.startSpan('DoWork');
-     *
-     *     // Start a new (child) Span:
-     *     var child = Tracer.startSpan('load-from-db', {
-     *         childOf: parent.context(),
-     *     });
-     *
-     *     // Start a new async (FollowsFrom) Span:
-     *     var child = Tracer.startSpan('async-cache-write', {
-     *         references: [
-     *             opentracing.followsFrom(parent.context())
-     *         ],
-     *     });
-     *
-     * @param name - the name of the operation (REQUIRED).
-     * @param options - options for the newly created span.
-     * @return A new Span object.
-     */
-    startSpan(name: string, options?: SpanOptions): Span;
+declare class DatadogTracer extends Tracer {
 
-    /**
-     * Injects the given SpanContext instance for cross-process propagation
-     * within `carrier`. The expected type of `carrier` depends on the value of
-     * `format.
-     *
-     * OpenTracing defines a common set of `format` values (see
-     * FORMAT_TEXT_MAP, FORMAT_HTTP_HEADERS, and FORMAT_BINARY), and each has
-     * an expected carrier type.
-     *
-     * Consider this pseudocode example:
-     *
-     *     var clientSpan = ...;
-     *     ...
-     *     // Inject clientSpan into a text carrier.
-     *     var headersCarrier = {};
-     *     Tracer.inject(clientSpan.context(), Tracer.FORMAT_HTTP_HEADERS, headersCarrier);
-     *     // Incorporate the textCarrier into the outbound HTTP request header
-     *     // map.
-     *     Object.assign(outboundHTTPReq.headers, headersCarrier);
-     *     // ... send the httpReq
-     *
-     * @param  spanContext - the SpanContext to inject into the
-     *         carrier object. As a convenience, a Span instance may be passed
-     *         in instead (in which case its .context() is used for the
-     *         inject()).
-     * @param  format - the format of the carrier.
-     * @param  carrier - see the documentation for the chosen `format`
-     *         for a description of the carrier object.
-     */
-    inject(spanContext: SpanContext | Span, format: string, carrier: any): void;
-
-    /**
-     * Returns a SpanContext instance extracted from `carrier` in the given
-     * `format`.
-     *
-     * OpenTracing defines a common set of `format` values (see
-     * FORMAT_TEXT_MAP, FORMAT_HTTP_HEADERS, and FORMAT_BINARY), and each has
-     * an expected carrier type.
-     *
-     * Consider this pseudocode example:
-     *
-     *     // Use the inbound HTTP request's headers as a text map carrier.
-     *     var headersCarrier = inboundHTTPReq.headers;
-     *     var wireCtx = Tracer.extract(Tracer.FORMAT_HTTP_HEADERS, headersCarrier);
-     *     var serverSpan = Tracer.startSpan('...', { childOf : wireCtx });
-     *
-     * @param  format - the format of the carrier.
-     * @param  carrier - the type of the carrier object is determined by
-     *         the format.
-     * @return The extracted SpanContext, or null if no such SpanContext could
-     *         be found in `carrier`
-     */
-    extract(format: string, carrier: any): SpanContext | null;
 }
 
-export = Tracer;
+export = DatadogTracer;