luci: go.chromium.org/luci/common/trace Index | Files

package trace

import "go.chromium.org/luci/common/trace"

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

Package Files

trace.go transport.go

func InstrumentTransport Uses

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 Uses

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 Uses

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 Uses

type NullSpan struct{}

NullSpan implements Span by doing nothing.

func (NullSpan) Attribute Uses

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

Attribute does nothing.

func (NullSpan) End Uses

func (NullSpan) End(err error)

End does nothing.

type Span Uses

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 Uses

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 Uses

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 trace imports 4 packages (graph) and is imported by 11 packages. Updated 2020-01-26. Refresh now. Tools for package owners.