tracer

Documentation

Index

• func ToCtx(ctx context.Context, trace *Trace) context.Context
• type Trace
  • func FromCtx(ctx context.Context) *Trace
  • func (t *Trace) Epoch(name string) func()
  • func (t *Trace) Event(name string)
  • func (t *Trace) Finalize()
  • func (t *Trace) Fork() *Trace
  • func (t Trace) String() string
• type TraceItem
• type Traceable
• type Tracer
  • func NewTracer(f *util.Feed, origin string) *Tracer
  • func (t *Tracer) NewTrace(tracee Traceable) *Trace

Functions

func ToCtx

func ToCtx(ctx context.Context, trace *Trace) context.Context

ToCtx is a helper to store a Trace in a context.Context under ContextKey.

Types

type Trace

type Trace struct {
	// IDs is the unique identifier for the request in this trace.
	ID string
	// Name is a human-readable identifier for the request in this trace.
	Name string
	// Content is a trace, containing call sites and timings in the order in
	// which they happened.
	Content []TraceItem
	// contains filtered or unexported fields
}

A Trace is created by a Tracer and records the path of a request within (a connected part of) the system. It contains the ID of the traced object and a slice of trace entries. In typical usage the Epoch() and Event() methods are called at various stages to record the path the associated request takes through the system; when the request goes out of scope, a call to Finalize marks the end of the Trace, at which point it publishes itself to an associated `util.Feed`. A request may create multiple Traces as it passes through different parts of a distributed systems. A Trace is not safe for concurrent access.

TODO(tschottdorf): not allowing concurrent access is the right thing to do semantically, but we pass a Trace along with a context.Context, which explicitly encourages sharing of values. Might want to add that just for that reason, but for now it's convenient to let the race detector check what we do with the Trace.

func FromCtx

func FromCtx(ctx context.Context) *Trace

FromCtx is a helper to pass a Trace in a context.Context. It returns the Trace stored at ContextKey or nil.

func (*Trace) Epoch

func (t *Trace) Epoch(name string) func()

Epoch begins a phase in the life of the Trace, starting the measurement of its duration. The returned function needs to be called when the measurement is complete; failure to do so results in a panic() when Finalize() is called. The suggested pattern of usage is, where possible, `defer trace.Epoch("<name>")()`.

func (*Trace) Event

func (t *Trace) Event(name string)

Event adds an Epoch with zero duration to the Trace.

func (*Trace) Finalize

func (t *Trace) Finalize()

Finalize submits the Trace to the underlying feed. If there is an open Epoch, a panic occurs.

func (*Trace) Fork

func (t *Trace) Fork() *Trace

Fork creates a new Trace, equal to (but autonomous from) that which created the original Trace.

func (Trace) String

func (t Trace) String() string

String implements fmt.Stringer. It prints a human-readable breakdown of the Trace.

type TraceItem

type TraceItem struct {
	Origin    string
	Name      string
	Timestamp time.Time
	Duration  time.Duration
	File      string
	Line      int
	Func      string
	HLC       time.Time // TODO(tschottdorf) HLC timestamp
	// contains filtered or unexported fields
}

A TraceItem is an entry in a Trace.

type Traceable

type Traceable interface {
	// TraceID is the unique ID for the tracee.
	TraceID() string
	// TraceName is a short and "sufficiently unique" human-readable
	// representation of the tracee.
	TraceName() string
}

A Traceable object has a Trace identifier attached to it.

type Tracer

type Tracer struct {
	// contains filtered or unexported fields
}

A Tracer is used to follow requests across the system (or across systems). Requests must implement the Traceable interface and can be traced by invoking NewTrace(), which returns a Trace object initialized to publish itself to a util.Feed registered by the Tracer on completion.

func NewTracer

func NewTracer(f *util.Feed, origin string) *Tracer

NewTracer returns a new Tracer whose created Traces publish to the given feed. The origin is an identifier of the system, for instance a host ID.

func (*Tracer) NewTrace

func (t *Tracer) NewTrace(tracee Traceable) *Trace

NewTrace creates a Trace for the given Traceable.