go.opencensus.io: go.opencensus.io/trace Index | Examples | Files | Directories

package trace

import "go.opencensus.io/trace"

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.


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.



Package Files

basetypes.go config.go doc.go evictedqueue.go export.go lrumap.go sampling.go spanbucket.go spanstore.go status_codes.go trace.go trace_go11.go


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
    StatusCodeUnavailable        = 14
    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

All available span kinds. Span kind must be either one of these values.

func ApplyConfig Uses

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 Uses

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

NewContext returns a new context with the given Span attached.

func RegisterExporter Uses

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 Uses

func UnregisterExporter(e Exporter)

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

type Annotation Uses

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 Uses

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 Uses

func BoolAttribute(key string, value bool) Attribute

BoolAttribute returns a bool-valued attribute.

func Float64Attribute Uses

func Float64Attribute(key string, value float64) Attribute

Float64Attribute returns a float64-valued attribute.

func Int64Attribute Uses

func Int64Attribute(key string, value int64) Attribute

Int64Attribute returns an int64-valued attribute.

func StringAttribute Uses

func StringAttribute(key string, value string) Attribute

StringAttribute returns a string-valued attribute.

type Config Uses

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 Uses

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 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 Uses

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 linked span is a child of the current span.
    LinkTypeParent                      // The linked span is the parent of the current span.

LinkType values.

type MessageEvent Uses

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 Uses

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 Uses

type Sampler func(SamplingParameters) SamplingDecision

Sampler decides whether a trace should be sampled and exported.

func AlwaysSample Uses

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 NeverSample Uses

func NeverSample() Sampler

NeverSample returns a Sampler that samples no traces.

func ProbabilitySampler Uses

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 Uses

type SamplingDecision struct {
    Sample bool

SamplingDecision is the value returned by a Sampler.

type SamplingParameters Uses

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

SamplingParameters contains the values passed to a Sampler.

type Span Uses

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 Uses

func FromContext(ctx context.Context) *Span

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

func StartSpan Uses

func StartSpan(ctx context.Context, name string, o ...StartOption) (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.

Returned context contains the newly created span. You can use it to propagate the returned span in process.

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.


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 {

ctx := context.Background()

func StartSpanWithRemoteParent Uses

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 Uses

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

AddAttributes sets attributes in the span.

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

func (s *Span) AddLink(l Link)

AddLink adds a link to the span.

func (*Span) AddMessageReceiveEvent Uses

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 Uses

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 Uses

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

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

func (*Span) Annotatef Uses

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

Annotatef adds an annotation with attributes.

func (*Span) End Uses

func (s *Span) End()

End ends the span.

func (*Span) IsRecordingEvents Uses

func (s *Span) IsRecordingEvents() bool

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 Uses

func (s *Span) SetName(name string)

SetName sets the name of the span, if it is recording events.

func (*Span) SetStatus Uses

func (s *Span) SetStatus(status Status)

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

func (*Span) SpanContext Uses

func (s *Span) SpanContext() SpanContext

SpanContext returns the SpanContext of the span.

func (*Span) String Uses

func (s *Span) String() string

type SpanContext Uses

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 Uses

func (sc SpanContext) IsSampled() bool

IsSampled returns true if the span will be exported.

type SpanData Uses

type SpanData struct {
    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
    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 SpanID Uses

type SpanID [8]byte

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

func (SpanID) String Uses

func (s SpanID) String() string

type StartOption Uses

type StartOption func(*StartOptions)

StartOption apply changes to StartOptions.

func WithSampler Uses

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 Uses

func WithSpanKind(spanKind int) StartOption

WithSpanKind makes new spans to be created with the given kind.

type StartOptions Uses

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 Uses

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 TraceID Uses

type TraceID [16]byte

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

func (TraceID) String Uses

func (t TraceID) String() string

type TraceOptions Uses

type TraceOptions uint32

TraceOptions contains options associated with a trace span.

func (TraceOptions) IsSampled Uses

func (t TraceOptions) IsSampled() bool

IsSampled returns true if the span will be exported.


internalPackage internal provides trace internals.
propagationPackage propagation implements the binary trace context format.
tracestatePackage tracestate implements support for the Tracestate header of the W3C TraceContext propagation format.

Package trace imports 13 packages (graph) and is imported by 881 packages. Updated 2020-10-24. Refresh now. Tools for package owners.