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 CopyTraceContext(src, dst context.Context) context.Context
• func Emit(ctx context.Context, event Event) (context.Context, error)
• func Flush(ctx context.Context)
• func Note(ctx context.Context, key string, value interface{})
• func On(ctx context.Context) bool
• func ReadHTTPContext(ctx context.Context, h http.Header) context.Context
• func Start(ctx context.Context, kind Kind, id digest.Digest, name string) (outctx context.Context, done func())
• func URL(ctx context.Context) string
• func WithTracer(ctx context.Context, tracer Tracer) context.Context
• func WriteHTTPContext(ctx context.Context, h *http.Header)
• type Event
• type EventKind
• type Kind
  • func (i Kind) String() string
• type Tracer

Functions

func CopyTraceContext

func CopyTraceContext(src, dst context.Context) context.Context

CopyTraceContext copies the trace context from src to dst.

func Emit

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

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

func Flush

func Flush(ctx context.Context)

Flush should be called at least once, when no more events will be emitted, to guarantee that traces are persisted.

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 ReadHTTPContext

func ReadHTTPContext(ctx context.Context, h http.Header) context.Context

ReadHTTPContext restores the trace context from HTTP headers.

func Start

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

Start traces the beginning of a span of the indicated kind, name and id. Name is an abbreviated info about the span. Name may be used by trace implementations to display on a UI. Start returns a new context for this span. The returned context should be used to create child spans. Notes on the context will be associated with fresh span/or annotations on the current span (implementation dependent). Calling done() ends the span.

func URL

func URL(ctx context.Context) string

URL returns the url of the current trace.

func WithTracer

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

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

func WriteHTTPContext

func WriteHTTPContext(ctx context.Context, h *http.Header)

WriteHTTPContext saves the current trace context to HTTP headers.

Types

type Event

type Event struct {
	// Time is the timestamp of the event, generated at the source of
	// that event.
	Time time.Time
	// Kind is the type of event.
	Kind EventKind
	// Key stores the key for NoteEvents.
	Key string
	// Value stores the value for NoteEvents.
	Value interface{}
	// The following fields are set for events of type StartEvent and EndEvent.
	// Id of the span this event belongs to.
	Id digest.Digest
	// Name of the span this belongs to.
	Name string
	// Kind of span.
	SpanKind Kind
}

Event stores a single trace event. Each event must have at least a timestamp 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 an annotation 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
	// AllocReq is the span type for resource allocation requests.
	AllocReq
	// AllocLifespan is the span type for a single alloc's lifespan.
	AllocLifespan
)

func (Kind) String

func (i Kind) String() string

type Tracer

type Tracer interface {
	// Emit is called to emit a new event to the tracer.
	// The returned context should be used to create children spans.
	Emit(context.Context, Event) (context.Context, error)
	// WriteHTTPContext saves the current trace context to http header.
	WriteHTTPContext(context.Context, *http.Header)
	// ReadHTTPContext restores the trace context from http header.
	ReadHTTPContext(context.Context, http.Header) context.Context
	// CopyTraceContext copies trace specific metadata from src to dst.
	CopyTraceContext(src context.Context, dst context.Context) context.Context
	// URL returns the trace URL for the trace associated with ctx.
	URL(context.Context) string
	// Flush should be called at least once, when no more events
	// will be emitted, to guarantee traces that are persisted.
	Flush()
}

Tracer is a sink for trace events. Tracer implementations should not block: they are called synchronously.

var NopTracer Tracer = nopTracer{}

NopTracer is default tracer that does nothing.