loggabletracer

package
v0.0.0-...-ce94876 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 1, 2019 License: MIT, MIT, MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var Delegator delegatorType

Delegator is the format to use for DelegatingCarrier.

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 DelegatingCarrier

type DelegatingCarrier interface {
	SetState(traceID, spanID uint64, sampled bool)
	State() (traceID, spanID uint64, 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 EventFinish

type EventFinish RawSpan

EventFinish is received when Finish is called.

type EventLog

type EventLog opentracing.LogData

EventLog is received when Log (or one of its derivatives) is called.

DEPRECATED

type EventLogFields

type EventLogFields opentracing.LogRecord

EventLogFields is received when LogFields or LogKV is called.

type EventTag

type EventTag struct {
	Key   string
	Value interface{}
}

EventTag is received when SetTag is called.

type LoggableSpan

type LoggableSpan struct {
	TraceID      uint64         `json:"TraceID"`
	SpanID       uint64         `json:"SpanID"`
	ParentSpanID uint64         `json:"ParentSpanID"`
	Operation    string         `json:"Operation"`
	Start        time.Time      `json:"Start"`
	Duration     time.Duration  `json:"Duration"`
	Tags         opentrace.Tags `json:"Tags"`
	Logs         []SpanLog      `json:"Logs"`
}

Loggable Representation of a span, treated as an event log

type LoggableSpanRecorder

type LoggableSpanRecorder struct{}

func NewLoggableRecorder

func NewLoggableRecorder() *LoggableSpanRecorder

NewLoggableRecorder creates new LoggableSpanRecorder

func (*LoggableSpanRecorder) RecordSpan

func (r *LoggableSpanRecorder) RecordSpan(span RawSpan)

RecordSpan implements the respective method of SpanRecorder.

type LoggableTracer

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

Implements the `Tracer` interface.

func (*LoggableTracer) Extract

func (t *LoggableTracer) Extract(format interface{}, carrier interface{}) (opentracing.SpanContext, error)

func (*LoggableTracer) Inject

func (t *LoggableTracer) Inject(sc opentracing.SpanContext, format interface{}, carrier interface{}) error

func (*LoggableTracer) Options

func (t *LoggableTracer) Options() Options

func (*LoggableTracer) StartSpan

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

func (*LoggableTracer) StartSpanWithOptions

func (t *LoggableTracer) StartSpanWithOptions(
	operationName string,
	opts opentracing.StartSpanOptions,
) opentracing.Span

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 uint64) { return traceID % 64 == 0 }
	//
	// samples every 64th trace on average.
	ShouldSample func(traceID uint64) bool
	// TrimUnsampledSpans turns potentially expensive operations on unsampled
	// Spans into no-ops. More precisely, tags and log events are silently
	// discarded. If NewSpanEventListener is set, the callbacks will still fire.
	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)
	// DropAllLogs turns log events on all Spans into no-ops.
	// If NewSpanEventListener is set, the callbacks will still fire.
	DropAllLogs bool
	// MaxLogsPerSpan limits the number of Logs in a span (if set to a nonzero
	// value). If a span has more logs than this value, logs are dropped as
	// necessary (and replaced with a log describing how many were dropped).
	//
	// About half of the MaxLogPerSpan logs kept are the oldest logs, and about
	// half are the newest logs.
	//
	// If NewSpanEventListener is set, the callbacks will still fire for all log
	// events. This value is ignored if DropAllLogs is true.
	MaxLogsPerSpan int
	// 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(), sp), 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
	// EnableSpanPool enables the use of a pool, so that the tracer reuses spans
	// after Finish has been called on it. Adds a slight performance gain as it
	// reduces allocations. However, if you have any use-after-finish race
	// conditions the code may panic.
	EnableSpanPool 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 {
	// Those recording the RawSpan should also record the contents of its
	// SpanContext.
	Context SpanContext

	// The SpanID of this SpanContext's first intra-trace reference (i.e.,
	// "parent"), or 0 if there is no parent.
	ParentSpanID uint64

	// 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.LogRecord
}

RawSpan encapsulates all state associated with a (finished) Span.

type Span

type Span interface {
	opentracing.Span

	// Operation names the work done by this span instance
	Operation() string

	// Start indicates when the span began
	Start() time.Time
}

Span provides access to the essential details of the span, for use by loggabletracer consumers. These methods may only be called prior to (*opentracing.Span).Finish().

type SpanContext

type SpanContext struct {
	// A probabilistically unique identifier for a [multi-span] trace.
	TraceID uint64

	// A probabilistically unique identifier for a span.
	SpanID uint64

	// Whether the trace is sampled.
	Sampled bool

	// The span's associated baggage.
	Baggage map[string]string // initialized on first use
}

SpanContext holds the basic Span metadata.

func (SpanContext) ForeachBaggageItem

func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem belongs to the opentracing.SpanContext interface

func (SpanContext) WithBaggageItem

func (c SpanContext) WithBaggageItem(key, val string) SpanContext

WithBaggageItem returns an entirely new loggabletracer SpanContext with the given key:value baggage pair set.

type SpanEvent

type SpanEvent interface{}

A SpanEvent is emitted when a mutating command is called on a Span.

type SpanField

type SpanField struct {
	Key   string `json:"Key"`
	Value string `json:"Value"`
}

type SpanLog

type SpanLog struct {
	Timestamp time.Time   `json:"Timestamp"`
	Field     []SpanField `json:"Fields"`
}

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.

type Tracer

type Tracer interface {
	opentracing.Tracer

	// Options gets the Options used in New() or NewWithOptions().
	Options() Options
}

Tracer extends the opentracing.Tracer interface with methods to probe implementation state, for use by loggabletracer consumers.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL