tracing

Documentation

Overview

Package tracing helps with the propagation of the tracing span through context in the system. It does this for operations contained to single node, as well as across nodes, by injecting special headers.

To use the tracing package, a Tracer instance must be created, which contains functions for starting new span contexts, injecting them in other data, and extracting the active span them from the context.

To use the tracing package a Tracer instance must be created:

tracer, tracerCloser, err := tracing.NewTracer(&tracing.Options{
	Enabled:     true,
	Endpoint:    "127.0.0.1:6831",
	ServiceName: "bee",
})
if err != nil {
	// handle error
}
defer tracerCloser.Close()
// ...

The tracer instance contains functions for starting new span contexts, injecting them in other data, and extracting the active span them from the context:

span, _, ctx := tracer.StartSpanFromContext(ctx, "operation-name", nil)

Once the operation is finished, the open span should be finished:

span.Finish()

The tracing package also provides a function for creating a logger which will inject a "traceID" field entry to the log line, which helps in finding out which log lines belong to a specific trace.

To create a logger with trace just wrap an existing logger:

logger := tracing.NewLoggerWithTraceID(ctx, s.logger)
// ...
logger.Info("some message")

Which will result in following log line (if the context contains tracing information):

time="2015-09-07T08:48:33Z" level=info msg="some message" traceID=ed65818cc1d30c

Index

• Constants
• Variables
• func FromContext(ctx context.Context) opentracing.SpanContext
• func NewLoggerWithTraceID(ctx context.Context, l log.Logger) log.Logger
• func WithContext(ctx context.Context, c opentracing.SpanContext) context.Context
• type Options
• type Tracer
  • func NewTracer(o *Options) (*Tracer, io.Closer, error)
  • func (t *Tracer) AddContextHTTPHeader(ctx context.Context, headers http.Header) error
  • func (t *Tracer) AddContextHeader(ctx context.Context, headers p2p.Headers) error
  • func (t *Tracer) FollowSpanFromContext(ctx context.Context, operationName string, l log.Logger, ...) (opentracing.Span, log.Logger, context.Context)
  • func (t *Tracer) FromHTTPHeaders(headers http.Header) (opentracing.SpanContext, error)
  • func (t *Tracer) FromHeaders(headers p2p.Headers) (opentracing.SpanContext, error)
  • func (t *Tracer) StartSpanFromContext(ctx context.Context, operationName string, l log.Logger, ...) (opentracing.Span, log.Logger, context.Context)
  • func (t *Tracer) WithContextFromHTTPHeaders(ctx context.Context, headers http.Header) (context.Context, error)
  • func (t *Tracer) WithContextFromHeaders(ctx context.Context, headers p2p.Headers) (context.Context, error)

Constants

const (
	// TraceContextHeaderName is the http header name used to propagate tracing context.
	TraceContextHeaderName = "swarm-trace-id"

	// TraceBaggageHeaderPrefix is the prefix for http headers used to propagate baggage.
	TraceBaggageHeaderPrefix = "swarmctx-"
)

const LogField = "traceID"

LogField is the key in log message field that holds tracing id value.

Variables

var (
	// ErrContextNotFound is returned when tracing context is not present
	// in p2p Headers or context.
	ErrContextNotFound = errors.New("tracing context not found")
)

Functions

func FromContext

func FromContext(ctx context.Context) opentracing.SpanContext

FromContext return tracing span context from go context. If the tracing span context is not present in go context, nil is returned.

func NewLoggerWithTraceID

func NewLoggerWithTraceID(ctx context.Context, l log.Logger) log.Logger

NewLoggerWithTraceID creates a new log Entry with "traceID" field added if it exists in tracing span context stored from go context.

func WithContext

func WithContext(ctx context.Context, c opentracing.SpanContext) context.Context

WithContext adds tracing span context to go context.

Types

type Options

type Options struct {
	Enabled     bool
	Endpoint    string
	ServiceName string
}

Options are optional parameters for Tracer constructor.

type Tracer

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

Tracer connect to a tracing server and handles tracing spans and contexts by using opentracing Tracer.

func NewTracer

func NewTracer(o *Options) (*Tracer, io.Closer, error)

NewTracer creates a new Tracer and returns a closer which needs to be closed when the Tracer is no longer used to flush remaining traces.

func (*Tracer) AddContextHTTPHeader

func (t *Tracer) AddContextHTTPHeader(ctx context.Context, headers http.Header) error

AddContextHTTPHeader adds a tracing span context to provided HTTP headers from the go context. If the tracing span context is not present in go context, ErrContextNotFound is returned.

func (*Tracer) AddContextHeader

func (t *Tracer) AddContextHeader(ctx context.Context, headers p2p.Headers) error

AddContextHeader adds a tracing span context to provided p2p Headers from the go context. If the tracing span context is not present in go context, ErrContextNotFound is returned.

func (*Tracer) FollowSpanFromContext

func (t *Tracer) FollowSpanFromContext(ctx context.Context, operationName string, l log.Logger, opts ...opentracing.StartSpanOption) (opentracing.Span, log.Logger, context.Context)

FollowSpanFromContext starts a new tracing span that is either a root one or follows an existing one from the provided Context. If logger is provided, a new log Entry will be returned with "traceID" log field.

func (*Tracer) FromHTTPHeaders

func (t *Tracer) FromHTTPHeaders(headers http.Header) (opentracing.SpanContext, error)

FromHTTPHeaders returns tracing span context from HTTP headers. If the tracing span context is not present in go context, ErrContextNotFound is returned.

func (*Tracer) FromHeaders

func (t *Tracer) FromHeaders(headers p2p.Headers) (opentracing.SpanContext, error)

FromHeaders returns tracing span context from p2p Headers. If the tracing span context is not present in go context, ErrContextNotFound is returned.

func (*Tracer) StartSpanFromContext

func (t *Tracer) StartSpanFromContext(ctx context.Context, operationName string, l log.Logger, opts ...opentracing.StartSpanOption) (opentracing.Span, log.Logger, context.Context)

StartSpanFromContext starts a new tracing span that is either a root one or a child of existing one from the provided Context. If logger is provided, a new log Entry will be returned with "traceID" log field.

func (*Tracer) WithContextFromHTTPHeaders

func (t *Tracer) WithContextFromHTTPHeaders(ctx context.Context, headers http.Header) (context.Context, error)

WithContextFromHTTPHeaders returns a new context with injected tracing span context if they are found in HTTP headers. If the tracing span context is not present in go context, ErrContextNotFound is returned.

func (*Tracer) WithContextFromHeaders

func (t *Tracer) WithContextFromHeaders(ctx context.Context, headers p2p.Headers) (context.Context, error)

WithContextFromHeaders returns a new context with injected tracing span context if they are found in p2p Headers. If the tracing span context is not present in go context, ErrContextNotFound is returned.