trace

Documentation

Overview

Package trace provides a tracing system for Reflow events. Following Dapper [1], trace events are named by a span. Spans are coordinates in a tree of events, and each span is associated with a logical timeline (e.g., an exec, a cache lookup, a run, etc.). Traces thus form a tree of timelines, where the operation represented by a single timeline is dependent on all of its child timelines.

A span's ID is the 3-tuple

parent ID, ID, span kind

The parent ID is the ID of the span's parent. (The ID 0 is reserved for the root span.) The ID is a unique ID to the span itself, and the span's kind tells what kind of timeline the span represents (e.g., a cache lookup, or a command execution).

Additionally, each event is associated with a timestamp and an event type.

Tracing metadata is propagated through Go's context mechanism: each operation that creates a new span is given a context that represents that span. Package functions are provided to emit trace events to the current span, as defined a context.

[1] https://research.google.com/pubs/pub36356.html

Index

• func Emit(ctx context.Context, event Event) error
• func Note(ctx context.Context, key string, value interface{})
• func On(ctx context.Context) bool
• func Start(ctx context.Context, kind Kind, id digest.Digest) (outctx context.Context, done func())
• func WithTracer(ctx context.Context, tracer Tracer) context.Context
• type Event
• type EventKind
• type Kind
• type Span
• type Tracer

Functions

func Emit

func Emit(ctx context.Context, event Event) error

Emit emits a raw event on the tracer affiliated with the provided context.

func Note

func Note(ctx context.Context, key string, value interface{})

Note emits the provided key and value as a trace event associated with the span of the provided context.

func On

func On(ctx context.Context) bool

On returns true if there is a current tracer associated with the provided context.

func Start

func Start(ctx context.Context, kind Kind, id digest.Digest) (outctx context.Context, done func())

Start traces the beginning of a span of the indicated kind, and with the given ID. Start returns a new context for this span: Notes on the context will be associated with fresh span; new spans become children of this span.

func WithTracer

func WithTracer(ctx context.Context, tracer Tracer) context.Context

WithTracer returns a context that emits trace events to the provided tracer.

Types

type Event

type Event struct {
	// Time is the timestamp of the event, generated at the source of
	// that event.
	Time time.Time
	// Span is the span to which this event belongs.
	Span Span
	// Kind is the type of event.
	Kind EventKind
	// Key stores the key for NoteEvents.
	Key string
	// Value stores the value for NoteEvents.
	Value interface{}
}

Event stores a single trace event. Each event must have at least a timestamp, span, and an event kind. Other arguments depend on the event kind.

type EventKind

type EventKind int

EventKind is the type of trace event.

const (
	// StartEvent is the start of a trace span.
	StartEvent EventKind = iota
	// EndEvent is the end of a trace span.
	EndEvent
	// NoteEvent is a note on the current span.
	NoteEvent
)

type Kind

type Kind int

Kind is the type of spans.

const (
	// Run is the span type for a Reflow run.
	Run Kind = iota
	// Exec is the span type for a single exec.
	Exec
	// Cache is the span type for cache operations.
	Cache
	// Transfer is the span type for transfer operations.
	Transfer
)

type Span

type Span struct {
	Parent, Id digest.Digest
	Kind       Kind
}

Span stores the parent-child tuple of IDs that define a trace span. The zero Span struct is the root span.

type Tracer

type Tracer interface {
	// Emit is called to emit a new event to the tracer.
	Emit(Event) error
}

Tracers are sinks for trace events. Tracer implementations should not block: they are called synchronously.