trace

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Dec 15, 2017 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package trace contains types for representing trace information, and functions for global configuration of tracing.

The following assumes a basic familiarity with OpenCensus concepts. See http://opencensus.io.

Enabling Tracing for a Program

To use OpenCensus tracing, register at least one Exporter. You can use one of the provided exporters or write your own. 

trace.RegisterExporter(anExporter)

By default, traces will be sampled relatively rarely. To change the sampling frequency for your entire program, call SetDefaultSampler. Use a ProbabilitySampler to sample a subset of traces, or use AlwaysSample to collect a trace on every run: 

trace.SetDefaultSampler(trace.AlwaysSample())

Adding Spans to a Trace

A trace consists of a tree of spans. In Go, the current span is carried in a context.Context.

It is common to want to capture all the activity of a function call in a span. For this to work, the function must take a context.Context as a parameter. Add these two lines to the top of the function: 

ctx = trace.StartSpan(ctx, "your choice of name")
defer trace.EndSpan(ctx)

StartSpan will create a child span if one already exists, and will create a new top-level span otherwise.

As a suggestion, use the fully-qualified function name as the span name, e.g. "github.com/me/mypackage.Run".

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions 

func AddLink(ctx context.Context, l Link)

AddLink adds a link to the current span.

func AddMessageReceiveEvent 

func AddMessageReceiveEvent(ctx context.Context, messageID, uncompressedByteSize, compressedByteSize int64)

AddMessageReceiveEvent adds a message receive event to the current span.

messageID is an identifier for the message, which is recommended to be unique in this span and the same between the send event and the receive event (this allows to identify a message between the sender and receiver). For example, this could be a sequence id.

func AddMessageSendEvent 

func AddMessageSendEvent(ctx context.Context, messageID, uncompressedByteSize, compressedByteSize int64)

AddMessageSendEvent adds a message send event to the current span.

messageID is an identifier for the message, which is recommended to be unique in this span and the same between the send event and the receive event (this allows to identify a message between the sender and receiver). For example, this could be a sequence id.

func ConfigureBucketSizes 

func ConfigureBucketSizes(bcs []BucketConfiguration)

ConfigureBucketSizes sets the number of spans to keep per latency and error bucket for different span names.

func EndSpan 

func EndSpan(ctx context.Context)

EndSpan ends the current span.

The context passed to EndSpan will still refer to the now-ended span, so any code that adds more information to it, like SetSpanStatus, should be called before EndSpan.

func IsRecordingEvents 

func IsRecordingEvents(ctx context.Context) bool

IsRecordingEvents returns true if events are being recorded for the current span.

func IsSampled 

func IsSampled(ctx context.Context) bool

IsSampled returns true if the current span will be exported.

func LazyPrint 

func LazyPrint(ctx context.Context, str fmt.Stringer)

LazyPrint adds an annotation to the current span using a fmt.Stringer.

str.String is called only when the annotation text is needed.

func LazyPrintWithAttributes 

func LazyPrintWithAttributes(ctx context.Context, attributes []Attribute, str fmt.Stringer)

LazyPrintWithAttributes adds an annotation with attributes to the current span using a fmt.Stringer.

str.String is called only when the annotation text is needed.

func LazyPrintf 

func LazyPrintf(ctx context.Context, format string, a ...interface{})

LazyPrintf adds an annotation to the current span.

The format string is evaluated with its arguments only when the annotation text is needed.

func LazyPrintfWithAttributes 

func LazyPrintfWithAttributes(ctx context.Context, attributes []Attribute, format string, a ...interface{})

LazyPrintfWithAttributes adds an annotation with attributes to the current span.

The format string is evaluated with its arguments only when the annotation text is needed.

func Print 

func Print(ctx context.Context, str string)

Print adds an annotation to the current span.

func PrintWithAttributes 

func PrintWithAttributes(ctx context.Context, attributes []Attribute, str string)

PrintWithAttributes adds an annotation with attributes to the current span.

func RegisterExporter 

func RegisterExporter(e Exporter)

RegisterExporter adds to the list of Exporters that will receive sampled trace spans.

func SampledSpansSummary 

func SampledSpansSummary() map[string]PerMethodSummary

SampledSpansSummary returns a summary of what spans are being stored for each span name.

func SetDefaultSampler 

func SetDefaultSampler(sampler Sampler)

SetDefaultSampler sets the default sampler used when creating new spans.

func SetSpanAttributes 

func SetSpanAttributes(ctx context.Context, attributes ...Attribute)

SetSpanAttributes sets attributes in the current span.

Existing attributes whose keys appear in the attributes parameter are overwritten.

func SetSpanStatus 

func SetSpanStatus(ctx context.Context, status Status)

SetSpanStatus sets the status of the current span, if it is recording events.

func SetStackTrace 

func SetStackTrace(ctx context.Context)

SetStackTrace adds a stack trace to the current span.

func StartSpan 

func StartSpan(ctx context.Context, name string) context.Context

StartSpan starts a new child span of the current span in the context.

If there is no span in the context, creates a new trace and span.

Example

This example shows how to use StartSpan and EndSpan to capture a function execution in a Span. It assumes that the function has a context.Context argument. 

package main

import (
	"fmt"

	"go.opencensus.io/trace"
	"golang.org/x/net/context"
)

func main() {
	printEvens := func(ctx context.Context) {
		ctx = trace.StartSpan(ctx, "my/package.Function")
		defer trace.EndSpan(ctx)

		for i := 0; i < 10; i++ {
			if i%2 == 0 {
				fmt.Printf("Even!\n")
			}
		}
	}

	ctx := context.Background()
	printEvens(ctx)
}

Output:

func StartSpanWithOptions 

func StartSpanWithOptions(ctx context.Context, name string, o StartSpanOptions) context.Context

StartSpanWithOptions starts a new child span of the current span in the context.

If there is no span in the context, creates a new trace and span.

func StartSpanWithRemoteParent 

func StartSpanWithRemoteParent(ctx context.Context, name string, parent SpanContext, o StartSpanOptions) context.Context

StartSpanWithRemoteParent starts a new child span with the given parent SpanContext.

If there is an existing span in ctx, it is ignored -- the returned Span is a child of the span specified by parent.

func UnregisterExporter 

func UnregisterExporter(e Exporter)

UnregisterExporter removes from the list of Exporters the Exporter that was registered with the given name.

func WithSpan 

func WithSpan(parent context.Context, s *Span) context.Context

WithSpan returns a new context with the given Span attached.

Types

type Annotation 

type Annotation struct {
	time.Time
	Message    string
	Attributes map[string]interface{}
}

Annotation represents a text annotation with a set of attributes and a timestamp.

type Attribute 

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

Attribute is an interface for attributes; it is implemented by BoolAttribute, IntAttribute, and StringAttribute.

type BoolAttribute 

type BoolAttribute struct {
	Key   string
	Value bool
}

BoolAttribute represents a bool-valued attribute.

type BucketConfiguration 

type BucketConfiguration struct {
	Name                 string
	MaxRequestsSucceeded int
	MaxRequestsErrors    int
}

BucketConfiguration stores the number of samples to store for span buckets for successful and failed spans for a particular span name.

type ErrorBucketSummary 

type ErrorBucketSummary struct {
	ErrorCode int32
	Size      int
}

ErrorBucketSummary is a summary of an error bucket.

type Exporter 

type Exporter interface {
	Export(s *SpanData)
}

Exporter is a type for functions that receive sampled trace spans.

The Export method should return quickly; if an Exporter takes a significant amount of time to process a SpanData, that work should be done on another goroutine.

The SpanData should not be modified, but a pointer to it can be kept.

type Int64Attribute 

type Int64Attribute struct {
	Key   string
	Value int64
}

Int64Attribute represents an int64-valued attribute.

type LatencyBucketSummary 

type LatencyBucketSummary struct {
	MinLatency, MaxLatency time.Duration
	Size                   int
}

LatencyBucketSummary is a summary of a latency bucket. 

type Link struct {
	TraceID
	SpanID
	Type LinkType
	// Attributes is a set of attributes on the link.
	Attributes map[string]interface{}
}

Link represents a reference from one span to another span.

type LinkType 

type LinkType int32

LinkType specifies the relationship between the span that had the link added, and the linked span. 

const (
	LinkTypeUnspecified LinkType = iota // The relationship of the two spans is unknown.
	LinkTypeChild                       // The current span is a child of the linked span.
	LinkTypeParent                      // The current span is the parent of the linked span.
)

LinkType values.

type MessageEvent 

type MessageEvent struct {
	time.Time
	EventType            MessageEventType
	MessageID            int64
	UncompressedByteSize int64
	CompressedByteSize   int64
}

MessageEvent represents an event describing a message sent or received on the network.

type MessageEventType 

type MessageEventType int32

MessageEventType specifies the type of message event. 

const (
	MessageEventTypeUnspecified MessageEventType = iota // Unknown event type.
	MessageEventTypeSent                                // Indicates a sent RPC message.
	MessageEventTypeRecv                                // Indicates a received RPC message.
)

MessageEventType values.

type PerMethodSummary 

type PerMethodSummary struct {
	Active         int
	LatencyBuckets []LatencyBucketSummary
	ErrorBuckets   []ErrorBucketSummary
}

PerMethodSummary is a summary of the spans stored for a single span name.

type Sampler 

type Sampler interface {
	Sample(p SamplingParameters) SamplingDecision
}

Sampler is an interface for values that have a method that the trace library can call to determine whether to export a trace's spans.

func AlwaysSample 

func AlwaysSample() Sampler

AlwaysSample returns a Sampler that samples every trace.

func NeverSample 

func NeverSample() Sampler

NeverSample returns a Sampler that samples no traces.

func ProbabilitySampler 

func ProbabilitySampler(fraction float64) Sampler

ProbabilitySampler returns a Sampler that samples a given fraction of traces.

It also samples spans whose parents are sampled.

type SamplingDecision 

type SamplingDecision struct {
	Sample bool
}

SamplingDecision is the value returned by a Sampler.

type SamplingParameters 

type SamplingParameters struct {
	ParentContext SpanContext
	TraceID
	SpanID
	Name            string
	HasRemoteParent bool
}

SamplingParameters contains the values passed to a Sampler.

type Span 

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

Span represents a span of a trace. It has an associated SpanContext, and stores data accumulated while the span is active.

Ideally users should interact with Spans by calling the functions in this package that take a Context parameter.

func FromContext 

func FromContext(ctx context.Context) *Span

FromContext returns the Span stored in a context, or nil if there isn't one.

func NewSpan 

func NewSpan(name string, o StartSpanOptions) *Span

NewSpan returns a new span.

The returned span has no parent span; a new trace ID will be created for it.

func NewSpanWithRemoteParent 

func NewSpanWithRemoteParent(name string, parent SpanContext, o StartSpanOptions) *Span

NewSpanWithRemoteParent returns a new span with the given parent SpanContext. 

func (s *Span) AddLink(l Link)

AddLink adds a link to the span.

func (*Span) AddMessageReceiveEvent 

func (s *Span) AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize int64)

AddMessageReceiveEvent adds a message receive event to the span.

messageID is an identifier for the message, which is recommended to be unique in this span and the same between the send event and the receive event (this allows to identify a message between the sender and receiver). For example, this could be a sequence id.

func (*Span) AddMessageSendEvent 

func (s *Span) AddMessageSendEvent(messageID, uncompressedByteSize, compressedByteSize int64)

AddMessageSendEvent adds a message send event to the span.

messageID is an identifier for the message, which is recommended to be unique in this span and the same between the send event and the receive event (this allows to identify a message between the sender and receiver). For example, this could be a sequence id.

func (*Span) End 

func (s *Span) End()

End ends the span.

func (*Span) IsRecordingEvents 

func (s *Span) IsRecordingEvents() bool

IsRecordingEvents returns true if events are being recorded for this span.

func (*Span) IsSampled 

func (s *Span) IsSampled() bool

IsSampled returns true if this span will be exported.

func (*Span) LazyPrint 

func (s *Span) LazyPrint(str fmt.Stringer)

LazyPrint adds an annotation using a fmt.Stringer.

str.String is called only when the annotation text is needed.

func (*Span) LazyPrintWithAttributes 

func (s *Span) LazyPrintWithAttributes(attributes []Attribute, str fmt.Stringer)

LazyPrintWithAttributes adds an annotation with attributes using a fmt.Stringer.

str.String is called only when the annotation text is needed.

func (*Span) LazyPrintf 

func (s *Span) LazyPrintf(format string, a ...interface{})

LazyPrintf adds an annotation.

The format string is evaluated with its arguments only when the annotation text is needed.

func (*Span) LazyPrintfWithAttributes 

func (s *Span) LazyPrintfWithAttributes(attributes []Attribute, format string, a ...interface{})

LazyPrintfWithAttributes adds an annotation with attributes.

The format string is evaluated with its arguments only when the annotation text is needed.

func (*Span) Print 

func (s *Span) Print(str string)

Print adds an annotation.

func (*Span) PrintWithAttributes 

func (s *Span) PrintWithAttributes(attributes []Attribute, str string)

PrintWithAttributes adds an annotation with attributes.

func (*Span) SetAttributes 

func (s *Span) SetAttributes(attributes ...Attribute)

SetAttributes sets attributes in the span.

Existing attributes whose keys appear in the attributes parameter are overwritten.

func (*Span) SetStackTrace 

func (s *Span) SetStackTrace()

SetStackTrace adds a stack trace to the span.

func (*Span) SetStatus 

func (s *Span) SetStatus(status Status)

SetStatus sets the status of the span, if it is recording events.

func (*Span) SpanContext 

func (s *Span) SpanContext() SpanContext

SpanContext returns the SpanContext of the span.

func (*Span) StartSpan 

func (s *Span) StartSpan(name string) *Span

StartSpan starts a new child span.

If s is nil, creates a new trace and span, like the function NewSpan.

func (*Span) StartSpanWithOptions 

func (s *Span) StartSpanWithOptions(name string, o StartSpanOptions) *Span

StartSpanWithOptions starts a new child span using the given options.

If s is nil, creates a new trace and span, like the function NewSpan.

func (*Span) String 

func (s *Span) String() string

type SpanContext 

type SpanContext struct {
	TraceID
	SpanID
	TraceOptions
}

SpanContext contains the state that must propagate across process boundaries.

SpanContext is not an implementation of context.Context. TODO: add reference to external Census docs for SpanContext.

func SpanContextFromContext 

func SpanContextFromContext(ctx context.Context) (SpanContext, bool)

SpanContextFromContext returns the SpanContext of the current span, if there is one.

func (SpanContext) IsSampled 

func (sc SpanContext) IsSampled() bool

IsSampled returns true if the span will be exported.

type SpanData 

type SpanData struct {
	SpanContext
	ParentSpanID SpanID
	Name         string
	StartTime    time.Time
	EndTime      time.Time
	// The values of Attributes each have type string, bool, or int64.
	Attributes    map[string]interface{}
	Annotations   []Annotation
	MessageEvents []MessageEvent
	Status
	StackTrace      []uintptr
	Links           []Link
	HasRemoteParent bool
}

SpanData contains all the information collected by a Span.

func ActiveSpans 

func ActiveSpans(name string) []*SpanData

ActiveSpans returns the active spans for the given name.

func ErrorSampledSpans 

func ErrorSampledSpans(name string, code int32) []*SpanData

ErrorSampledSpans returns a sample of error spans.

If code is nonzero, only spans with that status code are returned.

func LatencySampledSpans 

func LatencySampledSpans(name string, minLatency, maxLatency time.Duration) []*SpanData

LatencySampledSpans returns a sample of successful spans.

minLatency is the minimum latency of spans to be returned. maxLatency, if nonzero, is the maximum latency of spans to be returned.

type SpanID 

type SpanID [8]byte

SpanID is an 8-byte identifier for a single span.

func (SpanID) String 

func (s SpanID) String() string

type StartSpanOptions 

type StartSpanOptions struct {
	// RecordEvents indicates whether to record data for this span, and include
	// the span in a local span store.
	// Events will also be recorded if the span will be exported.
	RecordEvents bool
	Sampler      // if non-nil, the Sampler to consult for this span.
	// RegisterNameForLocalSpanStore indicates that a local span store for spans
	// of this name should be created, if one does not exist.
	// If RecordEvents is false, this option has no effect.
	RegisterNameForLocalSpanStore bool
}

StartSpanOptions contains options concerning how a span is started.

type Status 

type Status struct {
	// Code is a status code.  Zero indicates success.
	//
	// If Code will be propagated to Google APIs, it ideally should be a value from
	// https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto .
	Code    int32
	Message string
}

Status is the status of a Span.

type StringAttribute 

type StringAttribute struct {
	Key   string
	Value string
}

StringAttribute represents a string-valued attribute.

type TraceID 

type TraceID [16]byte

TraceID is a 16-byte identifier for a set of spans.

func (TraceID) String 

func (t TraceID) String() string

type TraceOptions 

type TraceOptions uint32

TraceOptions contains options associated with a trace span.

func (TraceOptions) IsSampled 

func (t TraceOptions) IsSampled() bool

IsSampled returns true if the span will be exported.

Source Files

View all Source files

Directories

Path Synopsis
Package propagation implements the binary trace context format.
 Package propagation implements the binary trace context format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.