opentracing

Documentation

Overview

Package opentracing implements an OpenTracing (http://opentracing.io) compatible tracer. A Datadog tracer must be initialized through a Configuration object as you can see in the following examples.

Example (Initialization)

package main

import (
	// ddtrace namespace is suggested
	ddtrace "github.com/DataDog/dd-trace-go/opentracing"
	opentracing "github.com/opentracing/opentracing-go"
)

func main() {
	// create a Tracer configuration
	config := ddtrace.NewConfiguration()
	config.ServiceName = "api-intake"
	config.AgentHostname = "ddagent.consul.local"

	// initialize a Tracer and ensure a graceful shutdown
	// using the `closer.Close()`
	tracer, closer, err := ddtrace.NewTracer(config)
	if err != nil {
		// handle the configuration error
	}
	defer closer.Close()

	// set the Datadog tracer as a GlobalTracer
	opentracing.SetGlobalTracer(tracer)
	startWebServer()
}

func startWebServer() {
	// start a web server
}

Example (StartContext)

You can leverage the Golang `Context` for intra-process propagation of Spans. In this example we create a root Span, so that it can be reused in a nested function to create a child Span.

package main

import (
	"context"

	opentracing "github.com/opentracing/opentracing-go"
)

// You can leverage the Golang `Context` for intra-process propagation of
// Spans. In this example we create a root Span, so that it can be reused
// in a nested function to create a child Span.
func main() {
	// create a new root Span and return a new Context that includes
	// the Span itself
	ctx := context.Background()
	rootSpan, ctx := opentracing.StartSpanFromContext(ctx, "web.request")
	defer rootSpan.Finish()

	requestHandler(ctx)
}

func requestHandler(ctx context.Context) {
	// retrieve the previously set root Span
	span := opentracing.SpanFromContext(ctx)
	span.SetTag("resource.name", "/")

	// or simply create a new child Span from the previous Context
	childSpan, _ := opentracing.StartSpanFromContext(ctx, "sql.query")
	defer childSpan.Finish()
}

Example (StartSpan)

You can use the GlobalTracer to create a root Span. If you need to create a hierarchy, simply use the `ChildOf` reference

package main

import (
	opentracing "github.com/opentracing/opentracing-go"
)

// You can use the GlobalTracer to create a root Span. If you need to create a hierarchy,
// simply use the `ChildOf` reference
func main() {
	// use the GlobalTracer previously set
	rootSpan := opentracing.StartSpan("web.request")
	defer rootSpan.Finish()

	// set the reference to create a hierarchy of spans
	reference := opentracing.ChildOf(rootSpan.Context())
	childSpan := opentracing.StartSpan("sql.query", reference)
	defer childSpan.Finish()

	dbQuery()
}

func dbQuery() {
	// start a database query
}

Index

• Constants
• func NewTracer(config *Configuration) (ot.Tracer, io.Closer, error)
• type Configuration
  • func NewConfiguration() *Configuration
• type Propagator
• type Span
  • func NewSpan(operationName string) *Span
  • func (s *Span) BaggageItem(key string) string
  • func (s *Span) Context() ot.SpanContext
  • func (s *Span) FinishWithOptions(options ot.FinishOptions)
  • func (s *Span) Log(data ot.LogData)
  • func (s *Span) LogEvent(event string)
  • func (s *Span) LogEventWithPayload(event string, payload interface{})
  • func (s *Span) LogFields(fields ...log.Field)
  • func (s *Span) LogKV(keyVals ...interface{})
  • func (s *Span) SetBaggageItem(key, val string) ot.Span
  • func (s *Span) SetOperationName(operationName string) ot.Span
  • func (s *Span) SetTag(key string, value interface{}) ot.Span
  • func (s *Span) Tracer() ot.Tracer
• type SpanContext
  • func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)
  • func (c SpanContext) WithBaggageItem(key, val string) SpanContext
• type TextMapPropagator
  • func NewTextMapPropagator(baggagePrefix, traceHeader, parentHeader string) *TextMapPropagator
  • func (p *TextMapPropagator) Extract(carrier interface{}) (ot.SpanContext, error)
  • func (p *TextMapPropagator) Inject(context ot.SpanContext, carrier interface{}) error
• type Tracer
  • func (t *Tracer) Close() error
  • func (t *Tracer) Extract(format interface{}, carrier interface{}) (ot.SpanContext, error)
  • func (t *Tracer) Inject(ctx ot.SpanContext, format interface{}, carrier interface{}) error
  • func (t *Tracer) StartSpan(operationName string, options ...ot.StartSpanOption) ot.Span

Examples

• Package (Initialization)
• Package (StartContext)
• Package (StartSpan)

Constants

const (
	// SpanType defines the Span type (web, db, cache)
	SpanType = "span.type"
	// ServiceName defines the Service name for this Span
	ServiceName = "service.name"
	// ResourceName defines the Resource name for the Span
	ResourceName = "resource.name"
	// Error defines an error.
	Error = "error.error"
)

Functions

func NewTracer

func NewTracer(config *Configuration) (ot.Tracer, io.Closer, error)

NewTracer uses a Configuration object to initialize a Datadog Tracer. The initialization returns a `io.Closer` that can be used to graceful shutdown the tracer. If the configuration object defines a disabled Tracer, a no-op implementation is returned.

Types

type Configuration

type Configuration struct {
	// Enabled, when false, returns a no-op implementation of the Tracer.
	Enabled bool

	// Debug, when true, writes details to logs.
	Debug bool

	// ServiceName specifies the name of this application.
	ServiceName string

	// SampleRate sets the Tracer sample rate (ext/priority.go).
	SampleRate float64

	// AgentHostname specifies the hostname of the agent where the traces
	// are sent to.
	AgentHostname string

	// AgentPort specifies the port that the agent is listening on.
	AgentPort string

	// GlobalTags holds a set of tags that will be automatically applied to
	// all spans.
	GlobalTags map[string]interface{}

	// TextMapPropagator is an injector used for Context propagation.
	TextMapPropagator Propagator
}

Configuration struct configures the Datadog tracer. Please use the NewConfiguration constructor to begin.

func NewConfiguration

func NewConfiguration() *Configuration

NewConfiguration creates a `Configuration` object with default values.

type Propagator

type Propagator interface {
	// Inject takes the SpanContext and injects it into the carrier using
	// an implementation specific method.
	Inject(context ot.SpanContext, carrier interface{}) error

	// Extract returns the SpanContext from the given carrier using an
	// implementation specific method.
	Extract(carrier interface{}) (ot.SpanContext, error)
}

Propagator implementations should be able to inject and extract SpanContexts into an implementation specific carrier.

type Span

type Span struct {
	*ddtrace.Span
	// contains filtered or unexported fields
}

Span represents an active, un-finished span in the OpenTracing system. Spans are created by the Tracer interface.

func NewSpan

func NewSpan(operationName string) *Span

NewSpan is the OpenTracing Span constructor

func (*Span) BaggageItem

func (s *Span) BaggageItem(key string) string

BaggageItem gets the value for a baggage item given its key. Returns the empty string if the value isn't found in this Span.

func (*Span) Context

func (s *Span) Context() ot.SpanContext

Context yields the SpanContext for this Span. Note that the return value of Context() is still valid after a call to Span.Finish(), as is a call to Span.Context() after a call to Span.Finish().

func (*Span) FinishWithOptions

func (s *Span) FinishWithOptions(options ot.FinishOptions)

FinishWithOptions is like Finish() but with explicit control over timestamps and log data.

func (*Span) Log

func (s *Span) Log(data ot.LogData)

Log is deprecated: use LogFields or LogKV

func (*Span) LogEvent

func (s *Span) LogEvent(event string)

LogEvent is deprecated: use LogFields or LogKV

func (*Span) LogEventWithPayload

func (s *Span) LogEventWithPayload(event string, payload interface{})

LogEventWithPayload deprecated: use LogFields or LogKV

func (*Span) LogFields

func (s *Span) LogFields(fields ...log.Field)

LogFields is an efficient and type-checked way to record key:value logging data about a Span, though the programming interface is a little more verbose than LogKV().

func (*Span) LogKV

func (s *Span) LogKV(keyVals ...interface{})

LogKV is a concise, readable way to record key:value logging data about a Span, though unfortunately this also makes it less efficient and less type-safe than LogFields().

func (*Span) SetBaggageItem

func (s *Span) SetBaggageItem(key, val string) ot.Span

SetBaggageItem sets a key:value pair on this Span and its SpanContext that also propagates to descendants of this Span.

func (*Span) SetOperationName

func (s *Span) SetOperationName(operationName string) ot.Span

SetOperationName sets or changes the operation name.

func (*Span) SetTag

func (s *Span) SetTag(key string, value interface{}) ot.Span

SetTag adds a tag to the span, overwriting pre-existing values for the given `key`.

func (*Span) Tracer

func (s *Span) Tracer() ot.Tracer

Tracer provides access to the `Tracer“ that created this Span.

type SpanContext

type SpanContext struct {
	// contains filtered or unexported fields
}

SpanContext represents Span state that must propagate to descendant Spans and across process boundaries.

func (SpanContext) ForeachBaggageItem

func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem grants access to all baggage items stored in the SpanContext

func (SpanContext) WithBaggageItem

func (c SpanContext) WithBaggageItem(key, val string) SpanContext

WithBaggageItem returns an entirely new SpanContext with the given key:value baggage pair set.

type TextMapPropagator

type TextMapPropagator struct {
	// contains filtered or unexported fields
}

TextMapPropagator implements a propagator which uses opentracing.TextMap internally.

func NewTextMapPropagator

func NewTextMapPropagator(baggagePrefix, traceHeader, parentHeader string) *TextMapPropagator

NewTextMapPropagator returns a new propagator which uses opentracing.TextMap to inject and extract values. The parameters specify the prefix that will be used to prefix baggage header keys along with the trace and parent header. Empty strings may be provided to use the defaults, which are: "ot-baggage-" as prefix for baggage headers, "x-datadog-trace-id" and "x-datadog-parent-id" for trace and parent ID headers.

func (*TextMapPropagator) Extract

func (p *TextMapPropagator) Extract(carrier interface{}) (ot.SpanContext, error)

Extract implements Propagator.

func (*TextMapPropagator) Inject

func (p *TextMapPropagator) Inject(context ot.SpanContext, carrier interface{}) error

Inject defines the TextMapPropagator to propagate SpanContext data out of the current process. The implementation propagates the TraceID and the current active SpanID, as well as the Span baggage.

type Tracer

type Tracer struct {
	// contains filtered or unexported fields
}

Tracer is a simple, thin interface for Span creation and SpanContext propagation. In the current state, this Tracer is a compatibility layer that wraps the Datadog Tracer implementation.

func (*Tracer) Close

func (t *Tracer) Close() error

Close method implements `io.Closer` interface to graceful shutdown the Datadog Tracer. Note that this is a blocking operation that waits for the flushing Go routine.

func (*Tracer) Extract

func (t *Tracer) Extract(format interface{}, carrier interface{}) (ot.SpanContext, error)

Extract returns a SpanContext instance given `format` and `carrier`.

func (*Tracer) Inject

func (t *Tracer) Inject(ctx ot.SpanContext, format interface{}, carrier interface{}) error

Inject takes the `sm` SpanContext instance and injects it for propagation within `carrier`. The actual type of `carrier` depends on the value of `format`. Currently supported Injectors are: * `TextMap` * `HTTPHeaders`

func (*Tracer) StartSpan

func (t *Tracer) StartSpan(operationName string, options ...ot.StartSpanOption) ot.Span

StartSpan creates, starts, and returns a new Span with the given `operationName` A Span with no SpanReference options (e.g., opentracing.ChildOf() or opentracing.FollowsFrom()) becomes the root of its own trace.