Back to

Package trace

Latest Go to latest

The latest major version is .

Published: Aug 1, 2020 | License: Apache-2.0 | Module:


Package trace provides support for collecting tracing spans.

It decouples spans collection from the system that actually uploads spans. So it tracing is not needed in a binary, there's almost 0 overhead on it.


func InstrumentTransport

func InstrumentTransport(ctx context.Context, t http.RoundTripper) http.RoundTripper

InstrumentTransport wraps the transport with tracing.

Each outgoing request will result in a span. Additionally, adds headers to propagate the span context to the peer.

Uses the context from requests or 'ctx' if requests don't have a non-background context.

func SetBackend

func SetBackend(b Backend)

SetBackend installs the process-global implementation of the span collector.

May be called at most once (preferably before the first StartSpan call). Panics otherwise.

type Backend

type Backend interface {
	// StartSpan implements public StartSpan function.
	StartSpan(ctx context.Context, name string, kind SpanKind) (context.Context, Span)
	// PropagateSpanContext returns a shallow copy of http.Request with the span
	// context (from the given `ctx`) injected into the headers.
	PropagateSpanContext(ctx context.Context, span Span, req *http.Request) *http.Request

Backend knows how to collect and upload spans.

type NullSpan

type NullSpan struct{}

NullSpan implements Span by doing nothing.

func (NullSpan) Attribute

func (NullSpan) Attribute(key string, val interface{})

Attribute does nothing.

func (NullSpan) End

func (NullSpan) End(err error)

End does nothing.

type Span

type Span interface {
	// End marks the span as finished (with the given status).
	// Recognizes gRPC errors and annotates spans with their status. Also, for all
	// errors, annotates spans with the error message.
	End(err error)

	// Attribute annotates the span with an attribute.
	Attribute(key string, val interface{})

Span is in-progress trace span opened by StartSpan.

func StartSpan

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

StartSpan adds a span with the given name to the current trace.

This span is set as the current in the context (so nested spans can discover it and use it as a parent). The span must be closed with End when done.

May return NullSpan{} if tracing is disabled globally in the process or the current trace is not being recorded.

type SpanKind

type SpanKind int

SpanKind is an enum that defines a flavor of a span.

const (
	SpanKindInternal SpanKind = 0 // a span internal to the server
	SpanKindClient   SpanKind = 1 // a span with a client side of an RPC call

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier