Documentation ¶
Overview ¶
Package trace contains support for OpenCensus distributed tracing.
The following assumes a basic familiarity with OpenCensus concepts. See http://opencensus.io
Exporting Traces ¶
To export collected tracing data, register at least one exporter. You can use one of the provided exporters or write your own.
trace.RegisterExporter(exporter)
By default, traces will be sampled relatively rarely. To change the sampling frequency for your entire program, call ApplyConfig. Use a ProbabilitySampler to sample a subset of traces, or use AlwaysSample to collect a trace on every run:
trace.ApplyConfig(trace.Config{DefaultSampler: trace.AlwaysSample()})
Be careful about using trace.AlwaysSample in a production application with significant traffic: a new trace will be started and exported for every request.
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, "example.com/Run") 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.
Index ¶
- Constants
- func ApplyConfig(cfg Config)
- func NewContext(parent context.Context, s *Span) context.Context
- func RegisterExporter(e Exporter)
- func UnregisterExporter(e Exporter)
- type Annotation
- type Attribute
- type Config
- type Exporter
- type Link
- type LinkType
- type MessageEvent
- type MessageEventType
- type Sampler
- type SamplingDecision
- type SamplingParameters
- type Span
- func (s *Span) AddAttributes(attributes ...Attribute)
- func (s *Span) AddLink(l Link)
- func (s *Span) AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize int64)
- func (s *Span) AddMessageSendEvent(messageID, uncompressedByteSize, compressedByteSize int64)
- func (s *Span) Annotate(attributes []Attribute, str string)
- func (s *Span) Annotatef(attributes []Attribute, format string, a ...interface{})
- func (s *Span) End()
- func (s *Span) Internal() SpanInterface
- func (s *Span) IsRecordingEvents() bool
- func (s *Span) SetName(name string)
- func (s *Span) SetStatus(status Status)
- func (s *Span) SpanContext() SpanContext
- func (s *Span) String() string
- type SpanContext
- type SpanData
- type SpanID
- type SpanInterface
- type StartOption
- type StartOptions
- type Status
- type TraceID
- type TraceOptions
- type Tracer
Examples ¶
Constants ¶
const ( // DefaultMaxAnnotationEventsPerSpan is default max number of annotation events per span DefaultMaxAnnotationEventsPerSpan = 32 // DefaultMaxMessageEventsPerSpan is default max number of message events per span DefaultMaxMessageEventsPerSpan = 128 // DefaultMaxAttributesPerSpan is default max number of attributes per span DefaultMaxAttributesPerSpan = 32 // DefaultMaxLinksPerSpan is default max number of links per span DefaultMaxLinksPerSpan = 32 )
const ( StatusCodeOK = 0 StatusCodeCancelled = 1 StatusCodeUnknown = 2 StatusCodeInvalidArgument = 3 StatusCodeDeadlineExceeded = 4 StatusCodeNotFound = 5 StatusCodeAlreadyExists = 6 StatusCodePermissionDenied = 7 StatusCodeResourceExhausted = 8 StatusCodeFailedPrecondition = 9 StatusCodeAborted = 10 StatusCodeOutOfRange = 11 StatusCodeUnimplemented = 12 StatusCodeInternal = 13 StatusCodeDataLoss = 15 StatusCodeUnauthenticated = 16 )
Status codes for use with Span.SetStatus. These correspond to the status codes used by gRPC defined here: https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
const ( SpanKindUnspecified = iota SpanKindServer SpanKindClient )
All available span kinds. Span kind must be either one of these values.
Variables ¶
This section is empty.
Functions ¶
func ApplyConfig ¶ added in v0.7.0
func ApplyConfig(cfg Config)
ApplyConfig applies changes to the global tracing configuration.
Fields not provided in the given config are going to be preserved.
func NewContext ¶ added in v0.9.0
NewContext returns a new context with the given Span attached.
func RegisterExporter ¶
func RegisterExporter(e Exporter)
RegisterExporter adds to the list of Exporters that will receive sampled trace spans.
Binaries can register exporters, libraries shouldn't register exporters.
func UnregisterExporter ¶
func UnregisterExporter(e Exporter)
UnregisterExporter removes from the list of Exporters the Exporter that was registered with the given name.
Types ¶
type Annotation ¶
Annotation represents a text annotation with a set of attributes and a timestamp.
type Attribute ¶
type Attribute struct {
// contains filtered or unexported fields
}
Attribute represents a key-value pair on a span, link or annotation. Construct with one of: BoolAttribute, Int64Attribute, or StringAttribute.
func BoolAttribute ¶
BoolAttribute returns a bool-valued attribute.
func Float64Attribute ¶ added in v0.19.1
Float64Attribute returns a float64-valued attribute.
func Int64Attribute ¶
Int64Attribute returns an int64-valued attribute.
func StringAttribute ¶
StringAttribute returns a string-valued attribute.
type Config ¶ added in v0.7.0
type Config struct { // DefaultSampler is the default sampler used when creating new spans. DefaultSampler Sampler // IDGenerator is for internal use only. IDGenerator internal.IDGenerator // MaxAnnotationEventsPerSpan is max number of annotation events per span MaxAnnotationEventsPerSpan int // MaxMessageEventsPerSpan is max number of message events per span MaxMessageEventsPerSpan int // MaxAnnotationEventsPerSpan is max number of attributes per span MaxAttributesPerSpan int // MaxLinksPerSpan is max number of links per span MaxLinksPerSpan int }
Config represents the global tracing configuration.
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 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.
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.
type Sampler ¶
type Sampler func(SamplingParameters) SamplingDecision
Sampler decides whether a trace should be sampled and exported.
func AlwaysSample ¶
func AlwaysSample() Sampler
AlwaysSample returns a Sampler that samples every trace. Be careful about using this sampler in a production application with significant traffic: a new trace will be started and exported for every request.
func ProbabilitySampler ¶
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 TraceID SpanID SpanID Name string HasRemoteParent bool }
SamplingParameters contains the values passed to a Sampler.
type Span ¶
type Span struct {
// contains filtered or unexported fields
}
Span is a struct wrapper around the SpanInt interface, which allows correctly handling nil spans, while also allowing the SpanInterface implementation to be swapped out.
func FromContext ¶
FromContext returns the Span stored in a context, or a Span that is not recording events if there isn't one.
func NewSpan ¶
func NewSpan(s SpanInterface) *Span
NewSpan is a convenience function for creating a *Span out of a *span
func StartSpan ¶
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.
Returned context contains the newly created span. You can use it to propagate the returned span in process.
Example ¶
This example shows how to use StartSpan and (*Span).End to capture a function execution in a Span. It assumes that the function has a context.Context argument.
package main import ( "context" "fmt" "go.opencensus.io/trace" ) func main() { printEvens := func(ctx context.Context) { ctx, span := trace.StartSpan(ctx, "my/package.Function") defer span.End() for i := 0; i < 10; i++ { if i%2 == 0 { fmt.Printf("Even!\n") } } } ctx := context.Background() printEvens(ctx) }
Output:
func StartSpanWithRemoteParent ¶
func StartSpanWithRemoteParent(ctx context.Context, name string, parent SpanContext, o ...StartOption) (context.Context, *Span)
StartSpanWithRemoteParent starts a new child span of the span from the given parent.
If the incoming context contains a parent, it ignores. StartSpanWithRemoteParent is preferred for cases where the parent is propagated via an incoming request.
Returned context contains the newly created span. You can use it to propagate the returned span in process.
func (*Span) AddAttributes ¶ added in v0.5.0
AddAttributes sets attributes in the span.
Existing attributes whose keys appear in the attributes parameter are overwritten.
func (*Span) AddMessageReceiveEvent ¶
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 ¶
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 ¶ added in v0.2.0
Annotate adds an annotation with attributes. Attributes can be nil.
func (*Span) Internal ¶ added in v0.22.6
func (s *Span) Internal() SpanInterface
Internal returns the underlying implementation of the Span
func (*Span) IsRecordingEvents ¶
IsRecordingEvents returns true if events are being recorded for this span. Use this check to avoid computing expensive annotations when they will never be used.
func (*Span) SetName ¶ added in v0.14.0
SetName sets the name of the span, if it is recording events.
func (*Span) SpanContext ¶
func (s *Span) SpanContext() SpanContext
SpanContext returns the SpanContext of the span.
type SpanContext ¶
type SpanContext struct { TraceID TraceID SpanID SpanID TraceOptions TraceOptions Tracestate *tracestate.Tracestate }
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 SpanKind int 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 DroppedAttributeCount int DroppedAnnotationCount int DroppedMessageEventCount int DroppedLinkCount int // ChildSpanCount holds the number of child span created for this span. ChildSpanCount int }
SpanData contains all the information collected by a Span.
type SpanInterface ¶ added in v0.22.6
type SpanInterface interface { // IsRecordingEvents returns true if events are being recorded for this span. // Use this check to avoid computing expensive annotations when they will never // be used. IsRecordingEvents() bool // End ends the span. End() // SpanContext returns the SpanContext of the span. SpanContext() SpanContext // SetName sets the name of the span, if it is recording events. SetName(name string) // SetStatus sets the status of the span, if it is recording events. SetStatus(status Status) // AddAttributes sets attributes in the span. // // Existing attributes whose keys appear in the attributes parameter are overwritten. AddAttributes(attributes ...Attribute) // Annotate adds an annotation with attributes. // Attributes can be nil. Annotate(attributes []Attribute, str string) // Annotatef adds an annotation with attributes. Annotatef(attributes []Attribute, format string, a ...interface{}) // 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. AddMessageSendEvent(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. AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize int64) // AddLink adds a link to the span. AddLink(l Link) // String prints a string representation of a span. String() string }
SpanInterface 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.
type StartOption ¶ added in v0.9.0
type StartOption func(*StartOptions)
StartOption apply changes to StartOptions.
func WithSampler ¶ added in v0.9.0
func WithSampler(sampler Sampler) StartOption
WithSampler makes new spans to be be created with a custom sampler. Otherwise, the global sampler is used.
func WithSpanKind ¶ added in v0.9.0
func WithSpanKind(spanKind int) StartOption
WithSpanKind makes new spans to be created with the given kind.
type StartOptions ¶ added in v0.2.0
type StartOptions struct { // Sampler to consult for this Span. If provided, it is always consulted. // // If not provided, then the behavior differs based on whether // the parent of this Span is remote, local, or there is no parent. // In the case of a remote parent or no parent, the // default sampler (see Config) will be consulted. Otherwise, // when there is a non-remote parent, no new sampling decision will be made: // we will preserve the sampling of the parent. Sampler Sampler // SpanKind represents the kind of a span. If none is set, // SpanKindUnspecified is used. SpanKind int }
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 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.
type Tracer ¶ added in v0.22.6
type Tracer interface { // 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. // // Returned context contains the newly created span. You can use it to // propagate the returned span in process. StartSpan(ctx context.Context, name string, o ...StartOption) (context.Context, *Span) // StartSpanWithRemoteParent starts a new child span of the span from the given parent. // // If the incoming context contains a parent, it ignores. StartSpanWithRemoteParent is // preferred for cases where the parent is propagated via an incoming request. // // Returned context contains the newly created span. You can use it to // propagate the returned span in process. StartSpanWithRemoteParent(ctx context.Context, name string, parent SpanContext, o ...StartOption) (context.Context, *Span) // FromContext returns the Span stored in a context, or nil if there isn't one. FromContext(ctx context.Context) *Span // NewContext returns a new context with the given Span attached. NewContext(parent context.Context, s *Span) context.Context }
Tracer can start spans and access context functions.
var DefaultTracer Tracer = &tracer{}
DefaultTracer is the tracer used when package-level exported functions are invoked.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package internal provides trace internals.
|
Package internal provides trace internals. |
Package propagation implements the binary trace context format.
|
Package propagation implements the binary trace context format. |
Package tracestate implements support for the Tracestate header of the W3C TraceContext propagation format.
|
Package tracestate implements support for the Tracestate header of the W3C TraceContext propagation format. |