tracer: Index | Files | Directories

package tracer

import ""

Package tracer implements a Dapper-style tracing system. It is compatible with the OpenTracing specification.


To keep the overhead incurred by tracing low, only a subset of requests should be traced. This is achieved by a sampler. Each tracer has a sampler that may sample requests based on chance, a rate, or possibly other mechanisms. The default sampler samples all requests, which is useful for testing, and viable for low-traffic systems.

Only root spans make sampling decisions. Child spans will inherit the sampling decisions of the root spans.

Errors and logging

The instrumentation is defensive and will never purposefully panic. At the same time, most functions do not return errors, because they'll be called by automatic instrumentation, hidden from the user. Instead, errors will be logged.


Package Files

grpc.go propagation.go sampler.go tracer.go


const (
    // The Span has been sampled.
    FlagSampled = 1 << iota

The various flags of a Span.

func RegisterExtracter Uses

func RegisterExtracter(format interface{}, extracter Extracter)

RegisterExtracter registers an Extracter.

func RegisterInjecter Uses

func RegisterInjecter(format interface{}, injecter Injecter)

RegisterInjecter registers an Injecter.

type Extracter Uses

type Extracter func(carrier interface{}) (SpanContext, error)

An Extracter extracts a SpanContext from carrier.

type Flusher Uses

type Flusher interface {
    Flush() error

Flusher is an optional interface that when implemented allows a Storer to flush buffered spawns.

type GRPC Uses

type GRPC struct {
    // contains filtered or unexported fields

GRPC is a gRPC-based transport for sending spans to a server.

func (*GRPC) Flush Uses

func (g *GRPC) Flush() error

func (*GRPC) Store Uses

func (g *GRPC) Store(sp RawSpan) error

Store implements the tracer.Storer interface.

type GRPCOptions Uses

type GRPCOptions struct {
    // How many spans to queue before sending them to the server.
    // Additionally, a buffer the size of 2*QueueSize will be used to
    // process new spans. If this buffer runs full, new spans will be
    // dropped.
    QueueSize int
    // How often to flush spans, even if the queue isn't full yet.
    FlushInterval time.Duration
    // Where to log errors. If nil, the default logger will be used.
    Logger Logger

GRPCOptions are options for the GRPC storer.

type IDGenerator Uses

type IDGenerator interface {
    GenerateID() uint64

IDGenerator generates IDs for traces and spans. The ID with value 0 is reserved to mean "no parent span" and should not be generated.

type Injecter Uses

type Injecter func(sm SpanContext, carrier interface{}) error

An Injecter injects a SpanContext into carrier.

type Logger Uses

type Logger interface {
    // Printf logs a single message, given a format and values. The
    // format is documented in the fmt package.
    Printf(format string, values ...interface{})

A Logger logs messages.

type RandomID Uses

type RandomID struct{}

RandomID generates random IDs by using crypto/rand.

func (RandomID) GenerateID Uses

func (RandomID) GenerateID() uint64

GenerateID generates an ID.

type RawRelation Uses

type RawRelation struct {
    ParentID uint64 `json:"parent_id"`
    ChildID  uint64 `json:"child_id"`
    Kind     string `json:"kind"`

A RawRelation represents the relation between two spans.

type RawSpan Uses

type RawSpan struct {
    ServiceName   string    `json:"service_name"`
    OperationName string    `json:"operation_name"`
    StartTime     time.Time `json:"start_time"`
    FinishTime    time.Time `json:"finish_time"`

    Tags map[string]interface{} `json:"tags"`
    Logs []opentracing.LogData  `json:"logs"`

A RawSpan contains all the data associated with a span.

type RawTrace Uses

type RawTrace struct {
    TraceID   uint64        `json:"trace_id"`
    Spans     []RawSpan     `json:"spans"`
    Relations []RawRelation `json:"relations"`

A RawTrace contains all the data associated with a trace.

type Sampler Uses

type Sampler interface {
    Sample(id uint64) bool

A Sampler determines whether a span should be sampled or not by returning true or false.

func NewConstSampler Uses

func NewConstSampler(decision bool) Sampler

NewConstSampler returns a constant sampler that always returns the same decision.

func NewProbabilisticSampler Uses

func NewProbabilisticSampler(chance float64) Sampler

NewProbabilisticSampler returns a sampler that samples spans with a certain chance, which should be in [0, 1].

func NewRateSampler Uses

func NewRateSampler(n int) Sampler

NewRateSampler returns a sampler that samples up to n samples per second.

type Span Uses

type Span struct {
    // contains filtered or unexported fields

Span is an implementation of the OpenTracing Span interface.

func (*Span) BaggageItem Uses

func (sp *Span) BaggageItem(key string) string

BaggageItem implements the opentracing.Tracer interface.

func (*Span) Context Uses

func (sp *Span) Context() opentracing.SpanContext

Context implements the opentracing.Span interface.

func (*Span) Finish Uses

func (sp *Span) Finish()

Finish implements the opentracing.Span interface.

func (*Span) FinishWithOptions Uses

func (sp *Span) FinishWithOptions(opts opentracing.FinishOptions)

FinishWithOptions implements the opentracing.Span interface.

func (*Span) Log Uses

func (sp *Span) Log(data opentracing.LogData)

Log implements the opentracing.Span interface.

func (*Span) LogEvent Uses

func (sp *Span) LogEvent(event string)

LogEvent implements the opentracing.Span interface.

func (*Span) LogEventWithPayload Uses

func (sp *Span) LogEventWithPayload(event string, payload interface{})

LogEventWithPayload implements the opentracing.Span interface.

func (*Span) RawSpan Uses

func (sp *Span) RawSpan() RawSpan

RawSpan returns a deep copy of the span's underlying data.

func (*Span) Sampled Uses

func (sp *Span) Sampled() bool

Sampled reports whether this span was sampled.

func (*Span) SetBaggageItem Uses

func (sp *Span) SetBaggageItem(key, value string) opentracing.Span

SetBaggageItem implements the opentracing.Tracer interface.

func (*Span) SetOperationName Uses

func (sp *Span) SetOperationName(name string) opentracing.Span

SetOperationName implements the opentracing.Span interface.

func (*Span) SetTag Uses

func (sp *Span) SetTag(key string, value interface{}) opentracing.Span

SetTag implements the opentracing.Span interface.

func (*Span) Tracer Uses

func (sp *Span) Tracer() opentracing.Tracer

Tracer implements the opentracing.Span interface.

type SpanContext Uses

type SpanContext struct {
    TraceID  uint64            `json:"trace_id"`
    ParentID uint64            `json:"parent_id"`
    SpanID   uint64            `json:"span_id"`
    Flags    uint64            `json:"flags"`
    Baggage  map[string]string `json:"baggage"`

SpanContext contains the parts of a span that will be sent to downstream services.

func (SpanContext) ForeachBaggageItem Uses

func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem implements the opentracing.Tracer interface.

type Storer Uses

type Storer interface {
    Store(sp RawSpan) error

A Storer stores a finished span. "Storing" a span may either mean saving it in a storage engine, or sending it to a remote collector.

If a span with the same ID and the same trace ID already exists, the existing and new spans should be merged into one span.

Because spans are only stored once they're done, children will be stored before their parents.

func NewGRPC Uses

func NewGRPC(address string, grpcOpts *GRPCOptions, opts ...grpc.DialOption) (Storer, error)

NewGRPC returns a new Storer that sends spans via gRPC to a server.

type Tracer Uses

type Tracer struct {
    ServiceName string
    Logger      Logger
    Sampler     Sampler
    // contains filtered or unexported fields

Tracer is an implementation of the OpenTracing Tracer interface.

func NewTracer Uses

func NewTracer(serviceName string, storer Storer, idGenerator IDGenerator) *Tracer

NewTracer returns a new tracer.

func (*Tracer) Extract Uses

func (tr *Tracer) Extract(format interface{}, carrier interface{}) (opentracing.SpanContext, error)

Extract implements the opentracing.Tracer interface.

func (*Tracer) Flush Uses

func (tr *Tracer) Flush() error

func (*Tracer) Inject Uses

func (tr *Tracer) Inject(sm opentracing.SpanContext, format interface{}, carrier interface{}) error

Inject implements the opentracing.Tracer interface.

func (*Tracer) StartSpan Uses

func (tr *Tracer) StartSpan(operationName string, opts ...opentracing.StartSpanOption) opentracing.Span

StartSpan implements the opentracing.Tracer interface.


clientPackage client is a client for the HTTP query transport.
pbPackage pb is a generated protocol buffer package.
serverPackage server implements the Tracer server.
tracerutilPackage tracerutil provides helpers for tracing various components.

Package tracer imports 19 packages (graph) and is imported by 4 packages. Updated 2016-09-17. Refresh now. Tools for package owners.