ddtrace

package
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2020 License: BSD-3-Clause Imports: 4 Imported by: 0

Documentation

Overview

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/github.com/signalfx/signalfx-go-tracing/ddtrace#pkg-subdirectories.

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/github.com/signalfx/signalfx-go-tracing/ddtrace#pkg-subdirectories.

Example (Datadog)

The below example illustrates a simple use case using the "tracer" package, our native Datadog APM tracing client integration. For thorough documentation and further examples, visit its own godoc page. 

package main

import (
	"io/ioutil"
	"log"

	"github.com/signalfx/signalfx-go-tracing/ddtrace/ext"
	"github.com/signalfx/signalfx-go-tracing/ddtrace/tracer"
)

func main() {
	// Start the tracer and defer the Stop method.
	tracer.Start(tracer.WithAgentAddr("host:port"))
	defer tracer.Stop()

	// Start a root span.
	span := tracer.StartSpan("get.data")
	defer span.Finish()

	// Create a child of it, computing the time needed to read a file.
	child := tracer.StartSpan("read.file", tracer.ChildOf(span.Context()))
	child.SetTag(ext.ResourceName, "test.json")

	// Perform an operation.
	_, err := ioutil.ReadFile("~/test.json")

	// We may finish the child span using the returned error. If it's
	// nil, it will be disregarded.
	child.FinishWithOptionsExt(tracer.WithError(err))
	if err != nil {
		log.Fatal(err)
	}
}

Output:
Example (Mocking)

The code below illustrates a scenario of how one could use a mock tracer in tests to assert that spans are created correctly. 

package main

import (
	"github.com/signalfx/signalfx-go-tracing/ddtrace/mocktracer"
	"github.com/signalfx/signalfx-go-tracing/ddtrace/tracer"
)

func main() {
	// Setup the test environment: start the mock tracer.
	mt := mocktracer.Start()
	defer mt.Stop()

	// Run test code: in this example we will simply create a span to illustrate.
	tracer.StartSpan("test.span").Finish()

	// Assert the results: query the mock tracer for finished spans.
	spans := mt.FinishedSpans()
	if len(spans) != 1 {
		// fail
	}
	if spans[0].OperationName() != "test.span" {
		// fail
	}
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var Testing = false

Testing is set to true when the mock tracer is active. It usually signifies that we are in a test environment. This value is used by tracer.Start to prevent overriding the GlobalTracer in tests.

Functions

func SetGlobalTracer 

func SetGlobalTracer(t Tracer)

SetGlobalTracer sets the global tracer to t.

Types

type FinishConfig 

type FinishConfig struct {
	opentracing.FinishOptions

	// Error holds an optional error that should be set on the span before
	// finishing.
	Error error

	// NoDebugStack will prevent any set errors from generating an attached stack trace tag.
	NoDebugStack bool

	// StackFrames specifies the number of stack frames to be attached in spans that finish with errors.
	StackFrames uint

	// SkipStackFrames specifies the offset at which to start reporting stack frames from the stack.
	SkipStackFrames uint
}

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 FinishOption 

type FinishOption func(cfg *FinishConfig)

FinishOption is a configuration option that can be used with a Span's Finish method.

type NoopSpan 

type NoopSpan struct{}

NoopSpan is an implementation of ddtrace.Span that is a no-op.

func (NoopSpan) BaggageItem 

func (NoopSpan) BaggageItem(key string) string

BaggageItem implements ddtrace.Span.

func (NoopSpan) Context 

func (NoopSpan) Context() opentracing.SpanContext

Context implements ddtrace.Span.

func (NoopSpan) Finish 

func (NoopSpan) Finish()

Finish implements ddtrace.Span.

func (NoopSpan) FinishWithOptions 

func (NoopSpan) FinishWithOptions(opts opentracing.FinishOptions)

FinishWithOptions implements ddtrace.Span.

func (NoopSpan) FinishWithOptionsExt 

func (NoopSpan) FinishWithOptionsExt(opts ...FinishOption)

FinishWithOptionsExt implements ddtrace.Span.

func (NoopSpan) Log 

func (NoopSpan) Log(data opentracing.LogData)

Log implements ddtrace.Span.

func (NoopSpan) LogEvent 

func (NoopSpan) LogEvent(event string)

LogEvent implements ddtrace.Span.

func (NoopSpan) LogEventWithPayload 

func (NoopSpan) LogEventWithPayload(event string, payload interface{})

LogEventWithPayload implements ddtrace.Span.

func (NoopSpan) LogFields 

func (NoopSpan) LogFields(fields ...log.Field)

LogFields impelments ddtrace.Span

func (NoopSpan) LogKV 

func (NoopSpan) LogKV(alternatingKeyValues ...interface{})

LogKV implements ddtrace.Span.

func (NoopSpan) SetBaggageItem 

func (NoopSpan) SetBaggageItem(restrictedKey, value string) opentracing.Span

SetBaggageItem implements ddtrace.Span.

func (NoopSpan) SetOperationName 

func (NoopSpan) SetOperationName(operationName string) opentracing.Span

SetOperationName implements ddtrace.Span.

func (NoopSpan) SetTag 

func (NoopSpan) SetTag(key string, value interface{}) opentracing.Span

SetTag implements ddtrace.Span.

func (NoopSpan) Tracer 

func (NoopSpan) Tracer() opentracing.Tracer

Tracer implements ddtrace.Span.

type NoopSpanContext 

type NoopSpanContext struct{}

NoopSpanContext is an implementation of ddtrace.SpanContext that is a no-op.

func (NoopSpanContext) ForeachBaggageItem 

func (NoopSpanContext) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem implements ddtrace.SpanContext.

type NoopTracer 

type NoopTracer struct{}

NoopTracer is an implementation of ddtrace.Tracer that is a no-op.

func (NoopTracer) Extract 

func (NoopTracer) Extract(carrier interface{}) (SpanContext, error)

Extract implements ddtrace.Tracer.

func (NoopTracer) ForceFlush 

func (NoopTracer) ForceFlush()

ForceFlush traces

func (NoopTracer) Inject 

func (NoopTracer) Inject(context SpanContext, carrier interface{}) error

Inject implements ddtrace.Tracer.

func (NoopTracer) SetServiceInfo 

func (NoopTracer) SetServiceInfo(name, app, appType string)

SetServiceInfo implements ddtrace.Tracer.

func (NoopTracer) StartSpan 

func (NoopTracer) StartSpan(operationName string, opts ...StartSpanOption) Span

StartSpan implements ddtrace.Tracer.

func (NoopTracer) Stop 

func (NoopTracer) Stop()

Stop implements ddtrace.Tracer.

type Span 

type Span interface {
	opentracing.Span
	FinishWithOptionsExt(opts ...FinishOption)
}

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 SpanContext 

type SpanContext = opentracing.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 StartSpanConfig 

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{}

	// Force-set the SpanID, rather than use a random number. If no Parent SpanContext is present,
	// then this will also set the TraceID to the same value.
	SpanID uint64
}

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 StartSpanOption 

type StartSpanOption func(cfg *StartSpanConfig)

StartSpanOption is a configuration option that can be used with a Tracer's StartSpan method.

func WithChildOf added in v1.2.1 

func WithChildOf(ctx SpanContext) StartSpanOption

WithChildOf tells StartSpan to use the given span context as a parent for the created span.

func WithStartTime added in v1.2.1 

func WithStartTime(t time.Time) StartSpanOption

WithStartTime sets a custom time as the start time for the created span. By default a span is started using the creation time.

func WithTag added in v1.2.1 

func WithTag(k string, v interface{}) StartSpanOption

WithTag sets the given key/value pair as a tag on the started Span.

type Tracer 

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()

	// ForceFlush pending traces
	ForceFlush()
}

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.

func GetGlobalTracer 

func GetGlobalTracer() Tracer

GetGlobalTracer returns the currently active tracer.

Source Files

View all Source files

Directories

Path Synopsis
Package ext contains a set of Datadog-specific constants.
 Package ext contains a set of Datadog-specific constants.
Package mocktracer provides a mock implementation of the tracer used in testing.
 Package mocktracer provides a mock implementation of the tracer used in testing.
Package opentracer provides a wrapper on top of the Datadog tracer that can be used with Opentracing.
 Package opentracer provides a wrapper on top of the Datadog tracer that can be used with Opentracing.
Package tracer contains Datadog's core tracing client.
 Package tracer contains Datadog's core tracing client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.