README
¶
basictracer-go
The Go incarnation of the cross-platform "BasicTracer" reference implementation for OpenTracing.
Status
In early development: there will be backwards-incompatible changes so caveat emptor for now!
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Delegator delegatorType
Delegator is the format to use for DelegatingCarrier.
var NetTraceIntegrator = func() func(SpanEvent) { var tr trace.Trace return func(e SpanEvent) { switch t := e.(type) { case EventCreate: tr = trace.New("tracing", t.OperationName) case EventFinish: tr.Finish() case EventLog: if t.Payload != nil { tr.LazyPrintf("%s (payload %v)", t.Event, t.Payload) } else { tr.LazyPrintf("%s", t.Event) } } } }
NetTraceIntegrator can be passed into a basictracer as NewSpanEventListener and causes all traces to be registered with the net/trace endpoint.
Functions ¶
func New ¶
func New(recorder SpanRecorder) opentracing.Tracer
New creates and returns a standard Tracer which defers completed Spans to `recorder`. Spans created by this Tracer support the ext.SamplingPriority tag: Setting ext.SamplingPriority causes the Span to be Sampled from that point on.
func NewWithOptions ¶
func NewWithOptions(opts Options) opentracing.Tracer
NewWithOptions creates a customized Tracer.
Types ¶
type Context ¶
type Context struct {
// A probabilistically unique identifier for a [multi-span] trace.
TraceID int64
// A probabilistically unique identifier for a span.
SpanID int64
// The SpanID of this Context's parent, or 0 if there is no parent.
ParentSpanID int64
// Whether the trace is sampled.
Sampled bool
}
Context holds the basic Span metadata.
type DelegatingCarrier ¶
type DelegatingCarrier interface {
SetState(traceID, spanID int64, sampled bool)
State() (traceID, spanID int64, sampled bool)
SetBaggageItem(key, value string)
GetBaggage(func(key, value string))
}
DelegatingCarrier is a flexible carrier interface which can be implemented by types which have a means of storing the trace metadata and already know how to serialize themselves (for example, protocol buffers).
type EventBaggage ¶
type EventBaggage struct {
Key, Value string
}
EventBaggage is received when SetBaggageItem is called.
type EventCreate ¶
type EventCreate struct{ OperationName string }
EventCreate is emitted when a Span is created.
type EventLog ¶
type EventLog opentracing.LogData
EventLog is received when Log (or one of its derivatives) is called.
type EventTag ¶
type EventTag struct {
Key string
Value interface{}
}
EventTag is received when SetTag is called.
type Options ¶
type Options struct {
// ShouldSample is a function which is called when creating a new Span and
// determines whether that Span is sampled. The randomized TraceID is supplied
// to allow deterministic sampling decisions to be made across different nodes.
// For example,
//
// func(traceID int64) { return traceID % 64 == 0 }
//
// samples every 64th trace on average.
ShouldSample func(int64) bool
// TrimUnsampledSpans turns potentially expensive operations on unsampled
// Spans into no-ops. More precisely, tags, baggage items, and log events
// are silently discarded. If NewSpanEventListener is set, the callbacks
// will still fire in that case.
TrimUnsampledSpans bool
// Recorder receives Spans which have been finished.
Recorder SpanRecorder
// NewSpanEventListener can be used to enhance the tracer by effectively
// attaching external code to trace events. See NetTraceIntegrator for a
// practical example, and event.go for the list of possible events.
NewSpanEventListener func() func(SpanEvent)
// DebugAssertSingleGoroutine internally records the ID of the goroutine
// creating each Span and verifies that no operation is carried out on
// it on a different goroutine.
// Provided strictly for development purposes.
// Passing Spans between goroutine without proper synchronization often
// results in use-after-Finish() errors. For a simple example, consider the
// following pseudocode:
//
// func (s *Server) Handle(req http.Request) error {
// sp := s.StartSpan("server")
// defer sp.Finish()
// wait := s.queueProcessing(opentracing.ContextWithSpan(context.Background(), ctx), req)
// select {
// case resp := <-wait:
// return resp.Error
// case <-time.After(10*time.Second):
// sp.LogEvent("timed out waiting for processing")
// return ErrTimedOut
// }
// }
//
// This looks reasonable at first, but a request which spends more than ten
// seconds in the queue is abandoned by the main goroutine and its trace
// finished, leading to use-after-finish when the request is finally
// processed. Note also that even joining on to a finished Span via
// StartSpanWithOptions constitutes an illegal operation.
//
// Code bases which do not require (or decide they do not want) Spans to
// be passed across goroutine boundaries can run with this flag enabled in
// tests to increase their chances of spotting wrong-doers.
DebugAssertSingleGoroutine bool
// DebugAssertUseAfterFinish is provided strictly for development purposes.
// When set, it attempts to exacerbate issues emanating from use of Spans
// after calling Finish by running additional assertions.
DebugAssertUseAfterFinish bool
}
Options allows creating a customized Tracer via NewWithOptions. The object must not be updated when there is an active tracer using it.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns an Options object with a 1 in 64 sampling rate and all options disabled. A Recorder needs to be set manually before using the returned object with a Tracer.
type RawSpan ¶
type RawSpan struct {
// The RawSpan embeds its Context. Those recording the RawSpan
// should also record the contents of its Context.
Context
// The name of the "operation" this span is an instance of. (Called a "span
// name" in some implementations)
Operation string
// We store <start, duration> rather than <start, end> so that only
// one of the timestamps has global clock uncertainty issues.
Start time.Time
Duration time.Duration
// Essentially an extension mechanism. Can be used for many purposes,
// not to be enumerated here.
Tags opentracing.Tags
// The span's "microlog".
Logs []opentracing.LogData
// The span's associated baggage.
Baggage map[string]string // initialized on first use
}
RawSpan encapsulates all state associated with a (finished) Span.
type SpanEvent ¶
type SpanEvent interface{}
A SpanEvent is emitted when a mutating command is called on a Span.
type SpanRecorder ¶
type SpanRecorder interface {
// Implementations must determine whether and where to store `span`.
RecordSpan(span RawSpan)
}
A SpanRecorder handles all of the `RawSpan` data generated via an associated `Tracer` (see `NewStandardTracer`) instance. It also names the containing process and provides access to a straightforward tag map.
Source Files
Directories