grpctrace-godoc.md

grpctrace

-- import "go.opencensus.io/plugin/grpc/grpctrace"

Package grpctrace is a package to assist with tracing incoming and outgoing gRPC requests.

Usage

type ClientStatsHandler

type ClientStatsHandler struct{}

ClientStatsHandler is a an implementation of grpc.StatsHandler that can be passed to grpc.Dial using grpc.WithStatsHandler to enable trace context propagation and automatic span creation for outgoing gRPC requests.

func NewClientStatsHandler

func NewClientStatsHandler() *ClientStatsHandler

NewClientStatsHandler returns a StatsHandler that can be passed to grpc.Dial using grpc.WithStatsHandler to enable trace context propagation and automatic span creation for outgoing gRPC requests.

func (*ClientStatsHandler) HandleConn

func (c *ClientStatsHandler) HandleConn(ctx context.Context, cs stats.ConnStats)

HandleConn is a no-op for this StatsHandler.

func (*ClientStatsHandler) HandleRPC

func (c *ClientStatsHandler) HandleRPC(ctx context.Context, rs stats.RPCStats)

HandleRPC processes the RPC stats, adding information to the current trace span.

func (*ClientStatsHandler) TagConn

func (c *ClientStatsHandler) TagConn(ctx context.Context, cti *stats.ConnTagInfo) context.Context

TagConn is a no-op for this StatsHandler.

func (*ClientStatsHandler) TagRPC

func (c *ClientStatsHandler) TagRPC(ctx context.Context, rti *stats.RPCTagInfo) context.Context

TagRPC creates a new trace span for the client side of the RPC.

It returns ctx with the new trace span added and a serialization of the SpanContext added to the outgoing gRPC metadata.

type ServerStatsHandler

type ServerStatsHandler struct{}

ServerStatsHandler is a an implementation of grpc.StatsHandler that can be passed to grpc.NewServer using grpc.StatsHandler to enable trace context propagation and automatic span creation for incoming gRPC requests..

func NewServerStatsHandler

func NewServerStatsHandler() *ServerStatsHandler

NewServerStatsHandler returns a StatsHandler that can be passed to grpc.NewServer using grpc.StatsHandler to enable trace context propagation and automatic span creation for incoming gRPC requests.

func (*ServerStatsHandler) HandleConn

func (s *ServerStatsHandler) HandleConn(ctx context.Context, cs stats.ConnStats)

HandleConn is a no-op for this StatsHandler.

func (*ServerStatsHandler) HandleRPC

func (s *ServerStatsHandler) HandleRPC(ctx context.Context, rs stats.RPCStats)

HandleRPC processes the RPC stats, adding information to the current trace span.

func (*ServerStatsHandler) TagConn

func (s *ServerStatsHandler) TagConn(ctx context.Context, cti *stats.ConnTagInfo) context.Context

TagConn is a no-op for this StatsHandler.

func (*ServerStatsHandler) TagRPC

func (s *ServerStatsHandler) TagRPC(ctx context.Context, rti *stats.RPCTagInfo) context.Context

TagRPC creates a new trace span for the server side of the RPC.

It checks the incoming gRPC metadata in ctx for a SpanContext, and if it finds one, uses that SpanContext as the parent context of the new span.

It returns ctx, with the new trace span added.

trace-godoc.md

trace

-- import "go.opencensus.io/trace"

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, span := trace.StartSpan(ctx, "your choice of name")
defer span.End()

StartSpan will create a new top-level span if the context doesn't contain another span, otherwise it will create a child span.

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

Usage

func RegisterExporter

func RegisterExporter(e Exporter)

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

func SetDefaultSampler

func SetDefaultSampler(sampler Sampler)

SetDefaultSampler sets the default sampler used when creating new spans.

func StartSpan

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

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.

func StartSpanWithOptions

func StartSpanWithOptions(ctx context.Context, name string, o StartOptions) (context.Context, *Span)

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 StartOptions) (context.Context, *Span)

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.

type Annotation

type Annotation struct {
	Time       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.

ErrorBucketSummary is a summary of an error bucket.

type Exporter

type Exporter interface {
	ExportSpan(s *SpanData)
}

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

The ExportSpan method should be safe for concurrent use and 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 Link

type Link struct {
	TraceID TraceID
	SpanID  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.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.

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 {
}

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, parent *Span, o StartOptions) *Span

NewSpan returns a new span.

If parent is not nil, created span will be a child of the parent.

func NewSpanWithRemoteParent

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

NewSpanWithRemoteParent returns a new span with the given parent SpanContext.

func (*Span) AddLink

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) Annotate

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

Annotate adds an annotation with attributes. Attributes can be nil.

func (*Span) Annotatef

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

Annotatef adds an annotation with attributes.

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) 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) 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) 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 (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
	// The wall clock time of EndTime will be adjusted to always be offset
	// from StartTime by the duration of the span.
	EndTime time.Time
	// The values of Attributes each have type string, bool, or int64.
	Attributes    map[string]interface{}
	Annotations   []Annotation
	MessageEvents []MessageEvent
	Status
	Links           []Link
	HasRemoteParent bool
}

SpanData contains all the information collected by a Span.

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 StartOptions

type StartOptions 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 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
}

StartOptions 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.