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 (
	// datadog namespace is suggested
	datadog "github.com/DataDog/dd-trace-go/opentracing"
	opentracing "github.com/opentracing/opentracing-go"
)

func main() {
	// create a Tracer configuration
	config := datadog.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 := datadog.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 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 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"
	// ErrorMsg defines the error message
	ErrorMsg = "error.msg"
	// ErrorType defines the error class
	ErrorType = "error.type"
	// ErrorStack defines the stack for the given error or panic
	ErrorStack = "error.stack"
)

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       bool    // when disabled, a no-op implementation is returned
	Debug         bool    // when enabled, more details are written in logs
	ServiceName   string  // define the service name for this application
	SampleRate    float64 // set the Tracer sample rate [0, 1]
	AgentHostname string  // change the hostname where traces are sent
	AgentPort     string  // change the port where traces are sent
}

Configuration struct to configure a Datadog Tracer

func NewConfiguration

func NewConfiguration() *Configuration

NewConfiguration creates a `Configuration` object with default values.

type Span

type Span struct {
	*datadog.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 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.