Back to godoc.org

Package tracer

v0.0.0-...-bc6c5c1
Latest Go to latest

The latest major version is .

Published: Aug 31, 2018 | License: Apache-2.0 | Module: github.com/altairsix/pkg

Index

Variables

var (
	DefaultTracer opentracing.Tracer
	StderrTracer  opentracing.Tracer
)
var DebugEnabled = int64(0)

func AWS

func AWS(client *client.Client)

func Caller

func Caller(key string, skip int) log.Field

func Errorf

func Errorf(cause error, message string, args ...interface{}) error

func HasErr

func HasErr(err error, fn func(err error) bool) bool

func Multi

func Multi(tracers ...opentracing.Tracer) opentracing.Tracer

func SetDebug

func SetDebug(enabled bool)

type Causer

type Causer interface {
	Cause() error
}

type Emitter

type Emitter interface {
	Emit(span *Span, event string, fields ...log.Field)
}

type Encoder

type Encoder struct {
	Fields []zapcore.Field
}

func (*Encoder) EmitBool

func (e *Encoder) EmitBool(key string, value bool)

func (*Encoder) EmitFloat32

func (e *Encoder) EmitFloat32(key string, value float32)

func (*Encoder) EmitFloat64

func (e *Encoder) EmitFloat64(key string, value float64)

func (*Encoder) EmitInt

func (e *Encoder) EmitInt(key string, value int)

func (*Encoder) EmitInt32

func (e *Encoder) EmitInt32(key string, value int32)

func (*Encoder) EmitInt64

func (e *Encoder) EmitInt64(key string, value int64)

func (*Encoder) EmitLazyLogger

func (e *Encoder) EmitLazyLogger(value log.LazyLogger)

func (*Encoder) EmitObject

func (e *Encoder) EmitObject(key string, value interface{})

func (*Encoder) EmitString

func (e *Encoder) EmitString(key, value string)

func (*Encoder) EmitUint32

func (e *Encoder) EmitUint32(key string, value uint32)

func (*Encoder) EmitUint64

func (e *Encoder) EmitUint64(key string, value uint64)

type Segment

type Segment interface {
	Finish()
	LogFields(fields ...log.Field)
	SetBaggageItem(key, value string)
	Info(msg string, fields ...log.Field)
	Debug(msg string, fields ...log.Field)
	Errorf(cause error, msg string, args ...interface{}) error
}
var (
	NopSegment Segment = nopSegment{}
)

func NewSegment

func NewSegment(ctx context.Context, operationName string, fields ...log.Field) (Segment, context.Context)

func SegmentFromContext

func SegmentFromContext(ctx context.Context) Segment

SegmentFromContext returns an existing segment from the context

type Span

type Span struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func (*Span) BaggageItem

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

Gets the value for a baggage item given its key. Returns the empty string if the value isn't found in this Span.

func (*Span) Context

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

Context() yields the SpanContext for this Span. Note that the return value of Context() is still valid after a call to Span.Finish(), as is a call to Span.Context() after a call to Span.Finish().

func (*Span) Debug

func (s *Span) Debug(msg string, fields ...log.Field)

Debug allows the Span to log at arbitrary times

func (*Span) Finish

func (s *Span) Finish()

Sets the end timestamp and finalizes Span state.

With the exception of calls to Context() (which are always allowed), Finish() must be the last call made to any span instance, and to do otherwise leads to undefined behavior.

func (*Span) FinishWithOptions

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

FinishWithOptions is like Finish() but with explicit control over timestamps and log data.

func (*Span) ForeachBaggageItem

func (s *Span) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem grants access to all baggage items stored in the SpanContext. The handler function will be called for each baggage key/value pair. The ordering of items is not guaranteed.

The bool return value indicates if the handler wants to continue iterating through the rest of the baggage items; for example if the handler is trying to find some baggage item by pattern matching the name, it can return false as soon as the item is found to stop further iterations.

func (*Span) ForeachField

func (s *Span) ForeachField(handler func(k string, f log.Field) bool)

func (*Span) Info

func (s *Span) Info(msg string, fields ...log.Field)

Info allows the Span to log at arbitrary times

func (*Span) Log

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

Deprecated: use LogFields or LogKV

func (*Span) LogEvent

func (s *Span) LogEvent(event string)

Deprecated: use LogFields or LogKV

func (*Span) LogEventWithPayload

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

Deprecated: use LogFields or LogKV

func (*Span) LogFields

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

LogFields is an efficient and type-checked way to record key:value logging data about a Span, though the programming interface is a little more verbose than LogKV(). Here's an example:

span.LogFields(
    log.String("event", "soft error"),
    log.String("type", "cache timeout"),
    log.Int("waited.millis", 1500))

Also see Span.FinishWithOptions() and FinishOptions.BulkLogData.

func (*Span) LogKV

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

LogKV is a concise, readable way to record key:value logging data about a Span, though unfortunately this also makes it less efficient and less type-safe than LogFields(). Here's an example:

span.LogKV(
    "event", "soft error",
    "type", "cache timeout",
    "waited.millis", 1500)

For LogKV (as opposed to LogFields()), the parameters must appear as key-value pairs, like

span.LogKV(key1, val1, key2, val2, key3, val3, ...)

The keys must all be strings. The values may be strings, numeric types, bools, Go error instances, or arbitrary structs.

(Note to implementors: consider the log.InterleavedKVToFields() helper)

func (*Span) SetBaggageItem

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

SetBaggageItem sets a key:value pair on this Span and its SpanContext that also propagates to descendants of this Span.

SetBaggageItem() enables powerful functionality given a full-stack opentracing integration (e.g., arbitrary application data from a mobile app can make it, transparently, all the way into the depths of a storage system), and with it some powerful costs: use this feature with care.

IMPORTANT NOTE #1: SetBaggageItem() will only propagate baggage items to *future* causal descendants of the associated Span.

IMPORTANT NOTE #2: Use this thoughtfully and with care. Every key and value is copied into every local *and remote* child of the associated Span, and that can add up to a lot of network and cpu overhead.

Returns a reference to this Span for chaining.

func (*Span) SetOperationName

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

Sets or changes the operation name.

func (*Span) SetTag

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

Adds a tag to the span.

If there is a pre-existing tag set for `key`, it is overwritten.

Tag values can be numeric types, strings, or bools. The behavior of other tag value types is undefined at the OpenTracing level. If a tracing system does not know how to handle a particular value type, it may ignore the tag, but shall not panic.

func (*Span) Tracer

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

Provides access to the Tracer that created this Span.

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
}

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

type Tracer

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

func New

func New(emitter Emitter) *Tracer

func (*Tracer) Extract

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

Extract() returns a SpanContext instance given `format` and `carrier`.

OpenTracing defines a common set of `format` values (see BuiltinFormat), and each has an expected carrier type.

Other packages may declare their own `format` values, much like the keys used by `context.Context` (see https://godoc.org/golang.org/x/net/context#WithValue).

Example usage (with StartSpan):

carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
clientContext, err := tracer.Extract(opentracing.HTTPHeaders, carrier)

// ... assuming the ultimate goal here is to resume the trace with a
// server-side Span:
var serverSpan opentracing.Span
if err == nil {
    span = tracer.StartSpan(
        rpcMethodName, ext.RPCServerOption(clientContext))
} else {
    span = tracer.StartSpan(rpcMethodName)
}

NOTE: All opentracing.Tracer implementations MUST support all BuiltinFormats.

Return values:

- A successful Extract returns a SpanContext instance and a nil error
- If there was simply no SpanContext to extract in `carrier`, Extract()
  returns (nil, opentracing.ErrSpanContextNotFound)
- If `format` is unsupported or unrecognized, Extract() returns (nil,
  opentracing.ErrUnsupportedFormat)
- If there are more fundamental problems with the `carrier` object,
  Extract() may return opentracing.ErrInvalidCarrier,
  opentracing.ErrSpanContextCorrupted, or implementation-specific
  errors.

See Tracer.Inject().

func (*Tracer) Inject

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

Inject() takes the `sm` SpanContext instance and injects it for propagation within `carrier`. The actual type of `carrier` depends on the value of `format`.

OpenTracing defines a common set of `format` values (see BuiltinFormat), and each has an expected carrier type.

Other packages may declare their own `format` values, much like the keys used by `context.Context` (see https://godoc.org/golang.org/x/net/context#WithValue).

Example usage (sans error handling):

carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
err := tracer.Inject(
    span.Context(),
    opentracing.HTTPHeaders,
    carrier)

NOTE: All opentracing.Tracer implementations MUST support all BuiltinFormats.

Implementations may return opentracing.ErrUnsupportedFormat if `format` is not supported by (or not known by) the implementation.

Implementations may return opentracing.ErrInvalidCarrier or any other implementation-specific error if the format is supported but injection fails anyway.

See Tracer.Extract().

func (*Tracer) StartSpan

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

Create, start, and return a new Span with the given `operationName` and incorporate the given StartSpanOption `opts`. (Note that `opts` borrows from the "functional options" pattern, per http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis)

A Span with no SpanReference options (e.g., opentracing.ChildOf() or opentracing.FollowsFrom()) becomes the root of its own trace.

Examples:

var tracer opentracing.Tracer = ...

// The root-span case:
sp := tracer.StartSpan("GetFeed")

// The vanilla child span case:
sp := tracer.StartSpan(
    "GetFeed",
    opentracing.ChildOf(parentSpan.Context()))

// All the bells and whistles:
sp := tracer.StartSpan(
    "GetFeed",
    opentracing.ChildOf(parentSpan.Context()),
    opentracing.Tag{"user_agent", loggedReq.UserAgent},
    opentracing.StartTime(loggedReq.Timestamp),
)

type ZapEmitter

type ZapEmitter struct {
	Logger      *zap.Logger
	SkipCallers int
}

func (*ZapEmitter) Emit

func (z *ZapEmitter) Emit(span *Span, msg string, fields ...log.Field)

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier