trace

README

Trace

Veneur provides an experimental API for tracing requests between hosts. The API is in an experimental state and is subject to change.

The main Veneur tracing API is defined in the trace.go file; however, an OpenTracing compatibility layer is provided for convenience as well. These are functionally equivalent, though it is recommended not to mix the functions. (In other words, if a trace is started using Veneur's tracing API, avoid using the OpenTracing API functions on it or future children).

Eventually, these two interfaces will be consolidated.

Documentation

Overview

Package trace provies an experimental API for initiating traces. Veneur's tracing API also provides an opentracing compatibility layer. The Veneur tracing API is completely independent of the opentracing compatibility layer, with the exception of one convenience function.

Index

• Constants
• Variables
• func Disable()
• func Disabled() bool
• func Enable()
• func NameTag(name string) opentracing.StartSpanOption
• type ErrContractViolation
  • func (e ErrContractViolation) Error() string
• type Span
  • func StartSpanFromContext(ctx context.Context, name string, opts ...opentracing.StartSpanOption) (s *Span, c context.Context)
  • func (s *Span) Attach(ctx context.Context) context.Context
  • func (s *Span) BaggageItem(restrictedKey string) string
  • func (s *Span) Context() opentracing.SpanContext
  • func (s *Span) Finish()
  • func (s *Span) FinishWithOptions(opts opentracing.FinishOptions)
  • func (s *Span) Log(data opentracing.LogData)
  • func (s *Span) LogEvent(event string)
  • func (s *Span) LogEventWithPayload(event string, payload interface{})
  • func (s *Span) LogFields(fields ...opentracinglog.Field)
  • func (s *Span) LogKV(alternatingKeyValues ...interface{})
  • func (s *Span) SetBaggageItem(restrictedKey, value string) opentracing.Span
  • func (s *Span) SetOperationName(name string) opentracing.Span
  • func (s *Span) SetTag(key string, value interface{}) opentracing.Span
  • func (s *Span) Tracer() opentracing.Tracer
• type Trace
  • func SpanFromContext(c context.Context) *Trace
  • func StartChildSpan(parent *Trace) *Trace
  • func StartTrace(resource string) *Trace
  • func (t *Trace) Attach(c context.Context) context.Context
  • func (t *Trace) Duration() time.Duration
  • func (t *Trace) Error(err error)
  • func (t *Trace) ProtoMarshalTo(w io.Writer) error
  • func (t *Trace) Record(name string, tags []*ssf.SSFTag) error
  • func (t *Trace) SSFSample() *ssf.SSFSample
  • func (t *Trace) SetParent(parent *Trace)
• type Tracer
  • func (t Tracer) Extract(format interface{}, carrier interface{}) (ctx opentracing.SpanContext, err error)
  • func (tracer Tracer) ExtractRequestChild(resource string, req *http.Request, name string) (*Span, error)
  • func (t Tracer) Inject(sm opentracing.SpanContext, format interface{}, carrier interface{}) (err error)
  • func (tracer Tracer) InjectRequest(t *Trace, req *http.Request) error
  • func (t Tracer) StartSpan(operationName string, opts ...opentracing.StartSpanOption) opentracing.Span

Constants

const ParentIDHeader = "Parentid"

ParentIDHeader is the header for the parent id field

const SpanIDHeader = "Spanid"

SpanIDHeader is the header for the span id field

const TraceIDHeader = "Traceid"

TraceIDHeader is the header for the trace id field

Variables

var ErrUnsupportedSpanContext = errors.New("Unsupported SpanContext")

var GlobalTracer = Tracer{}

GlobalTracer is the… global tracer!

var Service = ""

Service is our service name and should be set exactly once, at startup

Functions

func Disable

func Disable()

(Experimental) Disabled sets tracing to disabled.

func Disabled

func Disabled() bool

func Enable

func Enable()

(Experimental) Enabled sets tracing to enabled.

func NameTag

func NameTag(name string) opentracing.StartSpanOption

Types

type ErrContractViolation

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

func (ErrContractViolation) Error

func (e ErrContractViolation) Error() string

type Span

type Span struct {
	*Trace
	// contains filtered or unexported fields
}

Span is a member of a trace

func StartSpanFromContext

func StartSpanFromContext(ctx context.Context, name string, opts ...opentracing.StartSpanOption) (s *Span, c context.Context)

StartSpanFromContext is used to create a child span when the parent trace is in the context

func (*Span) Attach

func (s *Span) Attach(ctx context.Context) context.Context

Attach attaches the span to the context. It delegates to opentracing.ContextWithSpan

func (*Span) BaggageItem

func (s *Span) BaggageItem(restrictedKey string) string

BaggageItem fetches the value of a baggage item in the span.

func (*Span) Context

func (s *Span) Context() opentracing.SpanContext

func (*Span) Finish

func (s *Span) Finish()

Finish ends a trace end records it.

func (*Span) FinishWithOptions

func (s *Span) FinishWithOptions(opts opentracing.FinishOptions)

FinishWithOptions finishes the span, but with explicit control over timestamps and log data. The BulkLogData field is deprecated and ignored.

func (*Span) Log

func (s *Span) Log(data opentracing.LogData)

Log is deprecated and unimplemented. It is included only to satisfy the opentracing.Span interface.

func (*Span) LogEvent

func (s *Span) LogEvent(event string)

LogEvent is deprecated and unimplemented. It is included only to satisfy the opentracing.Span interface.

func (*Span) LogEventWithPayload

func (s *Span) LogEventWithPayload(event string, payload interface{})

LogEventWithPayload is deprecated and unimplemented. It is included only to satisfy the opentracing.Span interface.

func (*Span) LogFields

func (s *Span) LogFields(fields ...opentracinglog.Field)

LogFields sets log fields on the underlying span. Currently these are ignored, but they can be fun to set anyway!

func (*Span) LogKV

func (s *Span) LogKV(alternatingKeyValues ...interface{})

func (*Span) SetBaggageItem

func (s *Span) SetBaggageItem(restrictedKey, value string) opentracing.Span

SetBaggageItem sets the value of a baggage in the span.

func (*Span) SetOperationName

func (s *Span) SetOperationName(name string) opentracing.Span

SetOperationName sets the name of the operation being performed in this span.

func (*Span) SetTag

func (s *Span) SetTag(key string, value interface{}) opentracing.Span

SetTag sets the tags on the underlying span

func (*Span) Tracer

func (s *Span) Tracer() opentracing.Tracer

Tracer returns the tracer that created this Span

type Trace

type Trace struct {
	// the ID for the root span
	// which is also the ID for the trace itself
	TraceID int64

	// For the root span, this will be equal
	// to the TraceId
	SpanID int64

	// For the root span, this will be <= 0
	ParentID int64

	// The Resource should be the same for all spans in the same trace
	Resource string

	Start time.Time

	End time.Time

	// If non-zero, the trace will be treated
	// as an error
	Status ssf.SSFSample_Status

	Tags []*ssf.SSFTag

	// Unlike the Resource, this should not contain spaces
	// It should be of the format foo.bar.baz
	Name string
}

Trace is a convenient structural representation of a TraceSpan. It is intended to map transparently to the more general type SSFSample.

func SpanFromContext

func SpanFromContext(c context.Context) *Trace

SpanFromContext is used to create a child span when the parent trace is in the context

func StartChildSpan

func StartChildSpan(parent *Trace) *Trace

StartChildSpan creates a new Span with the specified parent

func StartTrace

func StartTrace(resource string) *Trace

StartTrace is called by to create the root-level span for a trace

func (*Trace) Attach

func (t *Trace) Attach(c context.Context) context.Context

Attach attaches the current trace to the context and returns a copy of the context with that trace stored under the key "trace".

func (*Trace) Duration

func (t *Trace) Duration() time.Duration

Duration is a convenience function for the difference between the Start and End timestamps. It assumes the span has already ended.

func (*Trace) Error

func (t *Trace) Error(err error)

func (*Trace) ProtoMarshalTo

func (t *Trace) ProtoMarshalTo(w io.Writer) error

ProtoMarshalTo writes the Trace as a protocol buffer in text format to the specified writer.

func (*Trace) Record

func (t *Trace) Record(name string, tags []*ssf.SSFTag) error

Record sends a trace to the (local) veneur instance, which will pass it on to the tracing agent running on the global veneur instance.

func (*Trace) SSFSample

func (t *Trace) SSFSample() *ssf.SSFSample

SSFSample converts the Trace to an SSFSample type. It sets the duration, so it assumes the span has already ended. (It is safe to call on a span that has not ended, but the duration field will be invalid)

func (*Trace) SetParent

func (t *Trace) SetParent(parent *Trace)

SetParent updates the ParentId, TraceId, and Resource of a trace based on the parent's values (SpanId, TraceId, Resource).

type Tracer

type Tracer struct {
}

Tracer is a tracer

func (Tracer) Extract

func (t Tracer) Extract(format interface{}, carrier interface{}) (ctx opentracing.SpanContext, err error)

Extract returns a SpanContext given the format and the carrier. The SpanContext returned represents the parent span (ie, SpanId refers to the parent span's own SpanId). TODO support all the BuiltinFormats

func (Tracer) ExtractRequestChild

func (tracer Tracer) ExtractRequestChild(resource string, req *http.Request, name string) (*Span, error)

ExtractRequestChild extracts a span from an HTTP request and creates and returns a new child of that span

func (Tracer) Inject

func (t Tracer) Inject(sm opentracing.SpanContext, format interface{}, carrier interface{}) (err error)

Inject injects the provided SpanContext into the carrier for propagation. It will return opentracing.ErrUnsupportedFormat if the format is not supported. TODO support other SpanContext implementations TODO support all the BuiltinFormats

func (Tracer) InjectRequest

func (tracer Tracer) InjectRequest(t *Trace, req *http.Request) error

InjectRequest injects a trace into an HTTP request header. It is a convenience function for Inject.

func (Tracer) StartSpan

func (t Tracer) StartSpan(operationName string, opts ...opentracing.StartSpanOption) opentracing.Span

StartSpan starts a span with the specified operationName (resource) and options. If the options specify a parent span and/or root trace, the resource from the root trace will be used. The tag "name" will be used as the SSF Name field - this can be set using the NameTag convenience function. The value returned is always a concrete Span (which satisfies the opentracing.Span interface)