trace

Documentation

Overview

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.

Index

• func InstrumentTransport(ctx context.Context, t http.RoundTripper) http.RoundTripper
• func SetBackend(b Backend)
• func SpanContext(ctx context.Context) string
• type Backend
• type NullSpan
  • func (NullSpan) Attribute(key string, val interface{})
  • func (NullSpan) End(err error)
• type Span
  • func StartSpan(ctx context.Context, name string) (context.Context, Span)
• type SpanKind

Functions

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.

func SpanContext

func SpanContext(ctx context.Context) string

SpanContext returns the current span context as an HTTP header-safe string.

It is empty if there's no span context.

Types

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
	// SpanContext implements public SpanContext function.
	SpanContext(ctx context.Context) string
}

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
)