Added integration support for DataDog APM Tracing

vendor/gopkg.in/DataDog/dd-trace-go.v1/ddtrace/ddtrace.go

@@ -0,0 +1,108 @@
+// Package ddtrace contains the interfaces that specify the implementations of Datadog's
+// tracing library, as well as a set of sub-packages containing various implementations:
+// our native implementation ("tracer"), a wrapper that can be used with Opentracing
+// ("opentracer") and a mock tracer to be used for testing ("mocktracer"). Additionally,
+// package "ext" provides a set of tag names and values specific to Datadog's APM product.
+//
+// To get started, visit the documentation for any of the packages you'd like to begin
+// with by accessing the subdirectories of this package: https://godoc.org/gopkg.in/DataDog/dd-trace-go.v1/ddtrace#pkg-subdirectories.
+package ddtrace // import "gopkg.in/DataDog/dd-trace-go.v1/ddtrace"
+
+import "time"
+
+// Tracer specifies an implementation of the Datadog tracer which allows starting
+// and propagating spans. The official implementation if exposed as functions
+// within the "tracer" package.
+type Tracer interface {
+	// StartSpan starts a span with the given operation name and options.
+	StartSpan(operationName string, opts ...StartSpanOption) Span
+
+	// Extract extracts a span context from a given carrier. Note that baggage item
+	// keys will always be lower-cased to maintain consistency. It is impossible to
+	// maintain the original casing due to MIME header canonicalization standards.
+	Extract(carrier interface{}) (SpanContext, error)
+
+	// Inject injects a span context into the given carrier.
+	Inject(context SpanContext, carrier interface{}) error
+
+	// Stop stops the active tracer and sets the global tracer to a no-op. Calls to
+	// Stop should be idempotent.
+	Stop()
+}
+
+// Span represents a chunk of computation time. Spans have names, durations,
+// timestamps and other metadata. A Tracer is used to create hierarchies of
+// spans in a request, buffer and submit them to the server.
+type Span interface {
+	// SetTag sets a key/value pair as metadata on the span.
+	SetTag(key string, value interface{})
+
+	// SetOperationName sets the operation name for this span. An operation name should be
+	// a representative name for a group of spans (e.g. "grpc.server" or "http.request").
+	SetOperationName(operationName string)
+
+	// BaggageItem returns the baggage item held by the given key.
+	BaggageItem(key string) string
+
+	// SetBaggageItem sets a new baggage item at the given key. The baggage
+	// item should propagate to all descendant spans, both in- and cross-process.
+	SetBaggageItem(key, val string)
+
+	// Finish finishes the current span with the given options. Finish calls should be idempotent.
+	Finish(opts ...FinishOption)
+
+	// Context returns the SpanContext of this Span.
+	Context() SpanContext
+}
+
+// SpanContext represents a span state that can propagate to descendant spans
+// and across process boundaries. It contains all the information needed to
+// spawn a direct descendant of the span that it belongs to. It can be used
+// to create distributed tracing by propagating it using the provided interfaces.
+type SpanContext interface {
+	// SpanID returns the span ID that this context is carrying.
+	SpanID() uint64
+
+	// TraceID returns the trace ID that this context is carrying.
+	TraceID() uint64
+
+	// ForeachBaggageItem provides an iterator over the key/value pairs set as
+	// baggage within this context. Iteration stops when the handler returns
+	// false.
+	ForeachBaggageItem(handler func(k, v string) bool)
+}
+
+// StartSpanOption is a configuration option that can be used with a Tracer's StartSpan method.
+type StartSpanOption func(cfg *StartSpanConfig)
+
+// FinishOption is a configuration option that can be used with a Span's Finish method.
+type FinishOption func(cfg *FinishConfig)
+
+// FinishConfig holds the configuration for finishing a span. It is usually passed around by
+// reference to one or more FinishOption functions which shape it into its final form.
+type FinishConfig struct {
+	// FinishTime represents the time that should be set as finishing time for the
+	// span. Implementations should use the current time when FinishTime.IsZero().
+	FinishTime time.Time
+
+	// Error holds an optional error that should be set on the span before
+	// finishing.
+	Error error
+}
+
+// StartSpanConfig holds the configuration for starting a new span. It is usually passed
+// around by reference to one or more StartSpanOption functions which shape it into its
+// final form.
+type StartSpanConfig struct {
+	// Parent holds the SpanContext that should be used as a parent for the
+	// new span. If nil, implementations should return a root span.
+	Parent SpanContext
+
+	// StartTime holds the time that should be used as the start time of the span.
+	// Implementations should use the current time when StartTime.IsZero().
+	StartTime time.Time
+
+	// Tags holds a set of key/value pairs that should be set as metadata on the
+	// new span.
+	Tags map[string]interface{}
+}