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

    Constants

    This section is empty.

    Variables

    This section is empty.

    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
                        )

                        Directories

                        Path Synopsis
                        Package tracetest contains tracing system implementation useful in tests.
                        Package tracetest contains tracing system implementation useful in tests.