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.
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
- type Tracer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CopyTraceContext ¶
CopyTraceContext copies the trace context from src to dst.
func Flush ¶
Flush should be called at least once, when no more events will be emitted, to guarantee that traces are persisted.
func Note ¶
Note emits the provided key and value as a trace event associated with the span of the provided context.
func ReadHTTPContext ¶
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 WithTracer ¶
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
// 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 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 )
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.
Source Files
Directories