tracing

package
v1.7.9-dev1 Latest Latest
Warning

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

Go to latest
Published: Jun 12, 2020 License: MIT Imports: 11 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

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.

Directories

Path Synopsis
Package wire is used to serialize a trace.
Package wire is used to serialize a trace.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL