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.

func SpanContext Uses

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.

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

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 27 packages. Updated 2020-12-06. Refresh now. Tools for package owners.