trace

Documentation

Overview

Package trace defines common-use Dapper-style tracing APIs for the Go programming language.

Package trace provides a backend-agnostic APIs and various tracing providers can be used with the package by importing various implementations of the Client interface.

Index

• func Configure(c Client)
• func NewContext(ctx context.Context, span *Span) context.Context
• func NewSpan(name string, linked ...*Span) (*Span, FinishFunc)
• type Client
• type FinishFunc
• type HTTPCarrier
• type Span
  • func FromContext(ctx context.Context) *Span
  • func FromHTTPReq(req *http.Request) (*Span, error)
  • func (s *Span) Annotate(key string, val []byte)
  • func (s *Span) Child(name string, linked ...*Span) (*Span, FinishFunc)
  • func (s *Span) ToHTTPReq(req *http.Request) (*http.Request, error)

Functions

func Configure

func Configure(c Client)

TODO(jbd): A big TODO, we probably don't want to set a global client.

func NewContext

func NewContext(ctx context.Context, span *Span) context.Context

NewContext returns a context with the span in.

func NewSpan

func NewSpan(name string, linked ...*Span) (*Span, FinishFunc)

NewSpan creates a new root-level span.

The span must be finished when the job it represents it is finished.

Types

type Client

type Client interface {
	NewSpan(parent []byte) (id []byte)
	Finish(id []byte, name string, linked [][]byte, annotations map[string][]byte, start, end time.Time) error
}

Client represents a client communicates with a tracing backend. Tracing backends are supposed to implement the interface in order to provide Go support.

A Client is an HTTPCarrier if it can propagate the tracing information via an HTTP request.

If you are not a tracing provider, you will never have to interact with this interface directly.

type FinishFunc

type FinishFunc func() error

FinishFunc finalizes its span.

type HTTPCarrier

type HTTPCarrier interface {
	FromReq(req *http.Request) (id []byte, err error)
	ToReq(req *http.Request, id []byte) error
}

HTTPCarrier represents a mechanism that can attach the tracing information into an HTTP request or extract it from one.

type Span

type Span struct {
	ID          []byte            // represents the global identifier of the span.
	Annotations map[string][]byte // annotations set on this span.
}

Span represents a work.

func FromContext

func FromContext(ctx context.Context) *Span

FromContext returns a span from the given context.

func FromHTTPReq

func FromHTTPReq(req *http.Request) (*Span, error)

FromHTTPReq creates a *Span from an incoming request.

An error will be returned if the current tracing client is not supporting propagation via HTTP.

func (*Span) Annotate

func (s *Span) Annotate(key string, val []byte)

Annotate allows you to attach data to a span. Key-value pairs are arbitary information you want to collect in the lifetime of a span.

func (*Span) Child

func (s *Span) Child(name string, linked ...*Span) (*Span, FinishFunc)

Child creates a child span from s with the given name. Created child span needs to be finished by calling the finishing function.

func (*Span) ToHTTPReq

func (s *Span) ToHTTPReq(req *http.Request) (*http.Request, error)

ToHTTPReq injects the span information in the given request and returns the modified request.

If the current client is not supporting HTTP propagation, an error is returned.