trace

Documentation

Overview

Package trace contains a helper interface that allows various tracing tools to be plugged in to components using this interface. If no plugin is registered, the default one makes all trace calls into no-ops.

Index

• func CopySpan(parentCtx, spanCtx context.Context) context.Context
• func NewContext(parent context.Context, span Span) context.Context
• func RegisterSpanFactory(sf SpanFactory)
• type Span
  • func FromContext(ctx context.Context) (Span, bool)
  • func NewSpan(parent Span) Span
  • func NewSpanFromContext(ctx context.Context) Span
• type SpanFactory

Functions

func CopySpan

func CopySpan(parentCtx, spanCtx context.Context) context.Context

CopySpan creates a new context from parentCtx, with only the trace span copied over from spanCtx, if it has any. If not, parentCtx is returned.

func NewContext

func NewContext(parent context.Context, span Span) context.Context

NewContext returns a context based on parent with a new Span value.

func RegisterSpanFactory

func RegisterSpanFactory(sf SpanFactory)

RegisterSpanFactory should be called by a plugin during init() to install a factory that creates Spans for that plugin's tracing framework. Each call to RegisterSpanFactory will overwrite any previous setting. If no factory is registered, the default fake factory will produce Spans whose methods are all no-ops.

Types

type Span

type Span interface {
	// StartLocal marks the beginning of a span representing time spent doing
	// work locally.
	StartLocal(label string)
	// StartClient marks the beginning of a span representing time spent acting as
	// a client and waiting for a response.
	StartClient(label string)
	// StartServer marks the beginning of a span representing time spent doing
	// work in service of a remote client request.
	StartServer(label string)
	// Finish marks the span as complete.
	Finish()
	// Annotate records a key/value pair associated with a Span. It should be
	// called between Start and Finish.
	Annotate(key string, value interface{})
}

Span represents a unit of work within a trace. After creating a Span with NewSpan(), call one of the Start methods to mark the beginning of the work represented by this Span. Call Finish() when that work is done to record the Span. A Span may be reused by calling Start again.

func FromContext

func FromContext(ctx context.Context) (Span, bool)

FromContext returns the Span from a Context if present. The bool return value indicates whether a Span was present in the Context.

func NewSpan

func NewSpan(parent Span) Span

NewSpan creates a new Span with the currently installed tracing plugin. If no tracing plugin is installed, it returns a fake Span that does nothing.

func NewSpanFromContext

func NewSpanFromContext(ctx context.Context) Span

NewSpanFromContext returns a new Span whose parent is the Span from the given Context if present, or a new Span with no parent if not.

type SpanFactory

type SpanFactory interface {
	New(parent Span) Span
	FromContext(ctx context.Context) (Span, bool)
	NewContext(parent context.Context, span Span) context.Context
}

SpanFactory is an interface for creating spans or extracting them from Contexts.