tracing

Documentation

Overview

Package tracing provides a way for capturing hierarchical traces.

To start a new trace with a root span named select

trace, span := tracing.NewTrace("select")

It is recommended that a span be forwarded to callees using the context package. Firstly, create a new context with the span associated as follows

ctx = tracing.NewContextWithSpan(ctx, span)

followed by calling the API with the new context

SomeAPI(ctx, ...)

Once the trace is complete, it may be converted to a graph with the Tree method.

tree := t.Tree()

The tree is intended to be used with the Walk function in order to generate different presentations. The default Tree#String method returns a tree.

Index

• func NewContextWithSpan(ctx context.Context, c *Span) context.Context
• func NewContextWithTrace(ctx context.Context, t *Trace) context.Context
• func NewTrace(name string, opt ...StartSpanOption) (*Trace, *Span)
• func NewTraceFromSpan(name string, parent SpanContext, opt ...StartSpanOption) (*Trace, *Span)
• func Walk(v Visitor, node *TreeNode)
• type RawSpan
• type Span
  • func SpanFromContext(ctx context.Context) *Span
  • func (s *Span) Context() SpanContext
  • func (s *Span) Finish()
  • func (s *Span) MergeFields(args ...fields.Field)
  • func (s *Span) MergeLabels(args ...string)
  • func (s *Span) SetFields(set fields.Fields)
  • func (s *Span) SetLabels(args ...string)
  • func (s *Span) StartSpan(name string, opt ...StartSpanOption) *Span
  • func (s *Span) Tree() *TreeNode
• type SpanContext
  • func (s SpanContext) MarshalBinary() ([]byte, error)
  • func (s *SpanContext) UnmarshalBinary(data []byte) error
• type StartSpanOption
• type StartTime
• type Trace
  • func TraceFromContext(ctx context.Context) *Trace
  • func (t *Trace) MarshalBinary() ([]byte, error)
  • func (t *Trace) Merge(other *Trace)
  • func (t *Trace) Tree() *TreeNode
  • func (t *Trace) TreeFrom(root uint64) *TreeNode
  • func (t *Trace) UnmarshalBinary(data []byte) error
• type TreeNode
  • func (t *TreeNode) String() string
• type Visitor

Functions

func NewContextWithSpan

func NewContextWithSpan(ctx context.Context, c *Span) context.Context

NewContextWithSpan returns a new context with the given Span added.

func NewContextWithTrace

func NewContextWithTrace(ctx context.Context, t *Trace) context.Context

NewContextWithTrace returns a new context with the given Trace added.

func NewTrace

func NewTrace(name string, opt ...StartSpanOption) (*Trace, *Span)

NewTrace starts a new trace and returns a root span identified by the provided name.

Additional options may be specified to override the default behavior when creating the span.

func NewTraceFromSpan

func NewTraceFromSpan(name string, parent SpanContext, opt ...StartSpanOption) (*Trace, *Span)

NewTraceFromSpan starts a new trace and returns the associated span, which is a child of the parent span context.

func Walk

func Walk(v Visitor, node *TreeNode)

Walk traverses the graph in a depth-first order, calling v.Visit for each node until completion or v.Visit returns nil.

Types

type RawSpan

type RawSpan struct {
	Context      SpanContext
	ParentSpanID uint64        // ParentSpanID identifies the parent of this span or 0 if this is the root span.
	Name         string        // Name is the operation name given to this span.
	Start        time.Time     // Start identifies the start time of the span.
	Labels       labels.Labels // Labels contains additional metadata about this span.
	Fields       fields.Fields // Fields contains typed values associated with this span.
}

RawSpan represents the data associated with a span.

type Span

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

The Span type denotes a specific operation for a Trace. A Span may have one or more children, identifying additional details about a trace.

func SpanFromContext

func SpanFromContext(ctx context.Context) *Span

SpanFromContext returns the Span associated with ctx or nil if no Span has been assigned.

func (*Span) Context

func (s *Span) Context() SpanContext

Context returns a SpanContext that can be serialized and passed to a remote node to continue a trace.

func (*Span) Finish

func (s *Span) Finish()

Finish marks the end of the span and records it to the associated Trace. If Finish is not called, the span will not appear in the trace.

func (*Span) MergeFields

func (s *Span) MergeFields(args ...fields.Field)

MergeFields merges the provides args with any existing fields defined for the Span.

func (*Span) MergeLabels

func (s *Span) MergeLabels(args ...string)

MergeLabels merges args with any existing labels defined for the Span.

func (*Span) SetFields

func (s *Span) SetFields(set fields.Fields)

SetFields replaces any existing fields for the Span with args.

func (*Span) SetLabels

func (s *Span) SetLabels(args ...string)

SetLabels replaces any existing labels for the Span with args.

func (*Span) StartSpan

func (s *Span) StartSpan(name string, opt ...StartSpanOption) *Span

StartSpan creates a new child span using time.Now as the start time.

func (*Span) Tree

func (s *Span) Tree() *TreeNode

type SpanContext

type SpanContext struct {
	TraceID uint64 // TraceID is assigned a random number to this trace.
	SpanID  uint64 // SpanID is assigned a random number to identify this span.
}

A SpanContext represents the minimal information to identify a span in a trace. This is typically serialized to continue a trace on a remote node.

func (SpanContext) MarshalBinary

func (s SpanContext) MarshalBinary() ([]byte, error)

func (*SpanContext) UnmarshalBinary

func (s *SpanContext) UnmarshalBinary(data []byte) error

type StartSpanOption

type StartSpanOption interface {
	// contains filtered or unexported methods
}

type StartTime

type StartTime time.Time

The StartTime start span option specifies the start time of the new span rather than using now.

type Trace

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

The Trace type functions as a container for capturing Spans used to trace the execution of a request.

func TraceFromContext

func TraceFromContext(ctx context.Context) *Trace

TraceFromContext returns the Trace associated with ctx or nil if no Trace has been assigned.

func (*Trace) MarshalBinary

func (t *Trace) MarshalBinary() ([]byte, error)

func (*Trace) Merge

func (t *Trace) Merge(other *Trace)

Merge combines other with the current trace. This is typically necessary when traces are transferred from a remote.

func (*Trace) Tree

func (t *Trace) Tree() *TreeNode

Tree returns a graph of the current trace.

func (*Trace) TreeFrom

func (t *Trace) TreeFrom(root uint64) *TreeNode

func (*Trace) UnmarshalBinary

func (t *Trace) UnmarshalBinary(data []byte) error

type TreeNode

type TreeNode struct {
	Raw      RawSpan
	Children []*TreeNode
}

A TreeNode represents a single node in the graph.

func (*TreeNode) String

func (t *TreeNode) String() string

String returns the tree as a string.

type Visitor

type Visitor interface {
	Visit(*TreeNode) Visitor
}

A Visitor's Visit method is invoked for each node encountered by Walk. If the result of Visit is not nil, Walk visits each of the children.