vtrace

type Annotation struct {
	// When the annotation was added.
	When time.Time
	// The annotation message.
	// TODO(mattr): Allow richer annotations.
	Message string
}

type Manager interface {
	// WithNewTrace creates a new vtrace context that is not the child of any
	// other span.  This is useful when starting operations that are
	// disconnected from the activity ctx is performing.  For example
	// this might be used to start background tasks.
	WithNewTrace(ctx *context.T, name string, sr *SamplingRequest) (*context.T, Span)

	// WithContinuedTrace creates a span that represents a continuation of
	// a trace from a remote server.  name is the name of the new span and
	// req contains the parameters needed to connect this span with it's
	// trace.
	WithContinuedTrace(ctx *context.T, name string, sr *SamplingRequest, req Request) (*context.T, Span)

	// WithNewSpan derives a context with a new Span that can be used to
	// trace and annotate operations across process boundaries.
	WithNewSpan(ctx *context.T, name string) (*context.T, Span)

	// Generate a Request from the current context.
	GetRequest(ctx *context.T) Request

	// Generate a Response from the current context.
	GetResponse(ctx *context.T) Response
}

type Node struct {
	Span     *SpanRecord
	Children []*Node
}

type Request struct {
	SpanId          uniqueid.Id // The Id of the span that originated the RPC call.
	TraceId         uniqueid.Id // The Id of the trace this call is a part of.
	RequestMetadata []byte      // Any metadata to be sent with the request.
	Flags           TraceFlags
	LogLevel        int32
}

type Response struct {
	// Flags give options for trace collection, the client should alter its
	// collection for this trace according to the flags sent back from the
	// server.
	Flags TraceFlags
	// Trace is collected trace data.  This may be empty.
	Trace TraceRecord
}

type SamplingRequest struct {
	Local  string // The address/name of the local host generating this trace.
	Name   string // The name the traced service is available as, may differ from the name of the span.
	Method string // The method being invoked.
}

type Span interface {
	// Name returns the name of the span.
	Name() string

	// ID returns the uniqueid.ID of the span.
	ID() uniqueid.Id

	// Parent returns the uniqueid.ID of this spans parent span.
	Parent() uniqueid.Id

	// Annotate adds a string annotation to the trace.  Where Spans
	// represent time periods Annotations represent data thats relevant
	// at a specific moment.
	Annotate(s string)

	// Annotatef adds an annotation to the trace.  Where Spans represent
	// time periods Annotations represent data thats relevant at a
	// specific moment.
	// format and a are interpreted as with fmt.Printf.
	Annotatef(format string, a ...interface{})

	// AnnotateMetadata can be used to associate key/value with the span. If
	// indexed is false, the underlying implementation may create a searchable
	// index using this metadata. However, indexing itself is an implementation
	// specific feature and need be provided by every implementation.
	// NOTE that metadata is not communicated back to the requestor and is
	// intended for purely per-server/node use.
	AnnotateMetadata(key string, value interface{}, indexed bool) error

	// SetRequestMetadata appends metadata to be associated with this span and
	// hence encoded in any RPC requests made by this span. The interpretation
	// of the metdata is governed by the value of TraceFlags.
	SetRequestMetadata(metadata []byte)

	// Finish ends the span, marking the end time.  The span should
	// not be used after Finish is called.
	Finish(error)

	// Trace returns the id of the trace this Span is a member of.
	Trace() uniqueid.Id

	// Store returns the store that this Span is stored in.
	Store() Store

	Request(ctx *context.T) Request
}

type SpanRecord struct {
	Id     uniqueid.Id // The Id of the Span.
	Parent uniqueid.Id // The Id of this Span's parent.
	Name   string      // The Name of this span.
	Start  time.Time   // The start time of this span.
	End    time.Time   // The end time of this span.
	// A series of annotations.
	Annotations []Annotation
	// RequestMetadata that will be sent along with the request.
	RequestMetadata []byte
}

type Store interface {
	// TraceRecords returns TraceRecords for all traces saved in the store.
	TraceRecords() []TraceRecord

	// TraceRecord returns a TraceRecord for a given ID.  Returns
	// nil if the given id is not present.
	TraceRecord(traceid uniqueid.Id) *TraceRecord

	// ForceCollect forces the store to collect all information about a given trace and to capture
	// the log messages at the given log level.
	ForceCollect(traceid uniqueid.Id, level int)

	// Merge merges a vtrace.Response into the current store.
	Merge(response Response)

	// Return the log level in effect for this trace.
	LogLevel(traceid uniqueid.Id) int

	Flags(traceid uniqueid.Id) TraceFlags

	Start(traceid uniqueid.Id, span SpanRecord)

	Finish(traceid uniqueid.Id, span SpanRecord, timestamp time.Time)

	// Annotate records the requested annotation.
	Annotate(traceid uniqueid.Id, span SpanRecord, annotation Annotation)

	// AnnotateMetadata records the requested key value data with optional
	// indexing.
	AnnotateMetadata(traceid uniqueid.Id, span SpanRecord, key string, value interface{}, indexed bool) error
}

type TraceFlags int32

type TraceRecord struct {
	Id    uniqueid.Id
	Spans []SpanRecord
}