package tracing

import "github.com/influxdata/influxdb/pkg/tracing"

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.

Source Files ¶

context.go doc.go rawspan.go span.go spancontext.go trace.go trace_encoding.go tree.go util.go

Directories ¶