package opentracing
Import Path
github.com/opentracing/opentracing-go (on go.dev)
Dependency Relation
imports 5 packages, and imported by one package
Package-Level Type Names (total 20)
BuiltinFormat is used to demarcate the values within package `opentracing`
that are intended for use with the Tracer.Inject() and Tracer.Extract()
methods.
const Binary
const HTTPHeaders
const TextMap
FinishOptions allows Span.FinishWithOptions callers to override the finish
timestamp and provide log data via a bulk interface.
BulkLogData is DEPRECATED.
FinishTime overrides the Span's finish time, or implicitly becomes
time.Now() if FinishTime.IsZero().
FinishTime must resolve to a timestamp that's >= the Span's StartTime
(per StartSpanOptions).
LogRecords allows the caller to specify the contents of many LogFields()
calls with a single slice. May be nil.
None of the LogRecord.Timestamp values may be .IsZero() (i.e., they must
be set explicitly). Also, they must be >= the Span's start timestamp and
<= the FinishTime (or time.Now() if FinishTime.IsZero()). Otherwise the
behavior of FinishWithOptions() is undefined.
If specified, the caller hands off ownership of LogRecords at
FinishWithOptions() invocation time.
If specified, the (deprecated) BulkLogData must be nil or empty.
func Span.FinishWithOptions(opts FinishOptions)
HTTPHeadersCarrier satisfies both TextMapWriter and TextMapReader.
Example usage for server side:
carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
clientContext, err := tracer.Extract(opentracing.HTTPHeaders, carrier)
Example usage for client side:
carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
err := tracer.Inject(
span.Context(),
opentracing.HTTPHeaders,
carrier)
ForeachKey conforms to the TextMapReader interface.
Set conforms to the TextMapWriter interface.
HTTPHeadersCarrier : TextMapReader
HTTPHeadersCarrier : TextMapWriter
LogData is DEPRECATED
Event string
Payload interface{}
Timestamp time.Time
ToLogRecord converts a deprecated LogData to a non-deprecated LogRecord
func Span.Log(data LogData)
LogRecord is data associated with a single Span log. Every LogRecord
instance must specify at least one Field.
Fields []log.Field
Timestamp time.Time
func (*LogData).ToLogRecord() LogRecord
A NoopTracer is a trivial, minimum overhead implementation of Tracer
for which all operations are no-ops.
The primary use of this implementation is in libraries, such as RPC
frameworks, that make tracing an optional feature controlled by the
end user. A no-op implementation allows said libraries to use it
as the default Tracer and to write instrumentation that does
not need to keep checking if the tracer instance is nil.
For the same reason, the NoopTracer is the default "global" tracer
(see GlobalTracer and SetGlobalTracer functions).
WARNING: NoopTracer does not support baggage propagation.
Extract belongs to the Tracer interface.
Inject belongs to the Tracer interface.
StartSpan belongs to the Tracer interface.
NoopTracer : Tracer
Span represents an active, un-finished span in the OpenTracing system.
Spans are created by the Tracer interface.
Gets the value for a baggage item given its key. Returns the empty string
if the value isn't found in this Span.
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().
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.
FinishWithOptions is like Finish() but with explicit control over
timestamps and log data.
Deprecated: use LogFields or LogKV
Deprecated: use LogFields or LogKV
Deprecated: use LogFields or LogKV
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.
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)
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.
Sets or changes the operation name.
Returns a reference to this Span for chaining.
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.
Returns a reference to this Span for chaining.
Provides access to the Tracer that created this Span.
func SpanFromContext(ctx context.Context) Span
func StartSpan(operationName string, opts ...StartSpanOption) Span
func StartSpanFromContext(ctx context.Context, operationName string, opts ...StartSpanOption) (Span, context.Context)
func StartSpanFromContextWithTracer(ctx context.Context, tracer Tracer, operationName string, opts ...StartSpanOption) (Span, context.Context)
func NoopTracer.StartSpan(operationName string, opts ...StartSpanOption) Span
func Span.SetBaggageItem(restrictedKey, value string) Span
func Span.SetOperationName(operationName string) Span
func Span.SetTag(key string, value interface{}) Span
func Tracer.StartSpan(operationName string, opts ...StartSpanOption) Span
func ContextWithSpan(ctx context.Context, span Span) context.Context
func Tag.Set(s Span)
func TracerContextWithSpanExtension.ContextWithSpanHook(ctx context.Context, span Span) context.Context
SpanContext represents Span state that must propagate to descendant Spans and across process
boundaries (e.g., a <trace_id, span_id, sampled> tuple).
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 NoopTracer.Extract(format interface{}, carrier interface{}) (SpanContext, error)
func Span.Context() SpanContext
func Tracer.Extract(format interface{}, carrier interface{}) (SpanContext, error)
func ChildOf(sc SpanContext) SpanReference
func FollowsFrom(sc SpanContext) SpanReference
func NoopTracer.Inject(sp SpanContext, format interface{}, carrier interface{}) error
func Tracer.Inject(sm SpanContext, format interface{}, carrier interface{}) error
SpanReference is a StartSpanOption that pairs a SpanReferenceType and a
referenced SpanContext. See the SpanReferenceType documentation for
supported relationships. If SpanReference is created with
ReferencedContext==nil, it has no effect. Thus it allows for a more concise
syntax for starting spans:
sc, _ := tracer.Extract(someFormat, someCarrier)
span := tracer.StartSpan("operation", opentracing.ChildOf(sc))
The `ChildOf(sc)` option above will not panic if sc == nil, it will just
not add the parent span reference to the options.
ReferencedContext SpanContext
Type SpanReferenceType
Apply satisfies the StartSpanOption interface.
SpanReference : StartSpanOption
func ChildOf(sc SpanContext) SpanReference
func FollowsFrom(sc SpanContext) SpanReference
SpanReferenceType is an enum type describing different categories of
relationships between two Spans. If Span-2 refers to Span-1, the
SpanReferenceType describes Span-1 from Span-2's perspective. For example,
ChildOfRef means that Span-1 created Span-2.
NOTE: Span-1 and Span-2 do *not* necessarily depend on each other for
completion; e.g., Span-2 may be part of a background job enqueued by Span-1,
or Span-2 may be sitting in a distributed queue behind Span-1.
const ChildOfRef
const FollowsFromRef
StartSpanOption instances (zero or more) may be passed to Tracer.StartSpan.
StartSpanOption borrows from the "functional options" pattern, per
http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis
( StartSpanOption) Apply(*StartSpanOptions)
SpanReference
StartTime
Tag
Tags
func StartSpan(operationName string, opts ...StartSpanOption) Span
func StartSpanFromContext(ctx context.Context, operationName string, opts ...StartSpanOption) (Span, context.Context)
func StartSpanFromContextWithTracer(ctx context.Context, tracer Tracer, operationName string, opts ...StartSpanOption) (Span, context.Context)
func NoopTracer.StartSpan(operationName string, opts ...StartSpanOption) Span
func Tracer.StartSpan(operationName string, opts ...StartSpanOption) Span
StartSpanOptions allows Tracer.StartSpan() callers and implementors a
mechanism to override the start timestamp, specify Span References, and make
a single Tag or multiple Tags available at Span start time.
StartSpan() callers should look at the StartSpanOption interface and
implementations available in this package.
Tracer implementations can convert a slice of `StartSpanOption` instances
into a `StartSpanOptions` struct like so:
func StartSpan(opName string, opts ...opentracing.StartSpanOption) {
sso := opentracing.StartSpanOptions{}
for _, o := range opts {
o.Apply(&sso)
}
...
}
Zero or more causal references to other Spans (via their SpanContext).
If empty, start a "root" Span (i.e., start a new trace).
StartTime overrides the Span's start time, or implicitly becomes
time.Now() if StartTime.IsZero().
Tags may have zero or more entries; the restrictions on map values are
identical to those for Span.SetTag(). May be nil.
If specified, the caller hands off ownership of Tags at
StartSpan() invocation time.
func SpanReference.Apply(o *StartSpanOptions)
func StartSpanOption.Apply(*StartSpanOptions)
func StartTime.Apply(o *StartSpanOptions)
func Tag.Apply(o *StartSpanOptions)
func Tags.Apply(o *StartSpanOptions)
StartTime is a StartSpanOption that sets an explicit start timestamp for the
new Span.
Apply satisfies the StartSpanOption interface.
StartTime : StartSpanOption
Tag may be passed as a StartSpanOption to add a tag to new spans,
or its Set method may be used to apply the tag to an existing Span,
for example:
tracer.StartSpan("opName", Tag{"Key", value})
or
Tag{"key", value}.Set(span)
Key string
Value interface{}
Apply satisfies the StartSpanOption interface.
Set applies the tag to an existing Span.
Tag : StartSpanOption
Tags are a generic map from an arbitrary string key to an opaque value type.
The underlying tracing system is responsible for interpreting and
serializing the values.
Apply satisfies the StartSpanOption interface.
Tags : StartSpanOption
TextMapCarrier allows the use of regular map[string]string
as both TextMapWriter and TextMapReader.
ForeachKey conforms to the TextMapReader interface.
Set implements Set() of opentracing.TextMapWriter
TextMapCarrier : TextMapReader
TextMapCarrier : TextMapWriter
TextMapReader is the Extract() carrier for the TextMap builtin format. With it,
the caller can decode a propagated SpanContext as entries in a map of
unicode strings.
ForeachKey returns TextMap contents via repeated calls to the `handler`
function. If any call to `handler` returns a non-nil error, ForeachKey
terminates and returns that error.
NOTE: The backing store for the TextMapReader may contain data unrelated
to SpanContext. As such, Inject() and Extract() implementations that
call the TextMapWriter and TextMapReader interfaces must agree on a
prefix or other convention to distinguish their own key:value pairs.
The "foreach" callback pattern reduces unnecessary copying in some cases
and also allows implementations to hold locks while the map is read.
HTTPHeadersCarrier
TextMapCarrier
TextMapWriter is the Inject() carrier for the TextMap builtin format. With
it, the caller can encode a SpanContext for propagation as entries in a map
of unicode strings.
Set a key:value pair to the carrier. Multiple calls to Set() for the
same key leads to undefined behavior.
NOTE: The backing store for the TextMapWriter may contain data unrelated
to SpanContext. As such, Inject() and Extract() implementations that
call the TextMapWriter and TextMapReader interfaces must agree on a
prefix or other convention to distinguish their own key:value pairs.
HTTPHeadersCarrier
TextMapCarrier
*github.com/gofiber/fiber/v2.Ctx
*github.com/valyala/fasthttp.Args
*github.com/valyala/fasthttp.RequestHeader
*github.com/valyala/fasthttp.ResponseHeader
net/http.Header
net/textproto.MIMEHeader
net/url.Values
Tracer is a simple, thin interface for Span creation and SpanContext
propagation.
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().
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/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().
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),
)
NoopTracer
func GlobalTracer() Tracer
func Span.Tracer() Tracer
func InitGlobalTracer(tracer Tracer)
func SetGlobalTracer(tracer Tracer)
func StartSpanFromContextWithTracer(ctx context.Context, tracer Tracer, operationName string, opts ...StartSpanOption) (Span, context.Context)
func github.com/Nerzal/gocloak/v13.WithTracer(ctx context.Context, tracer Tracer) context.Context
TracerContextWithSpanExtension is an extension interface that the
implementation of the Tracer interface may want to implement. It
allows to have some control over the go context when the
ContextWithSpan is invoked.
The primary purpose of this extension are adapters from opentracing
API to some other tracing API.
ContextWithSpanHook gets called by the ContextWithSpan
function, when the Tracer implementation also implements
this interface. It allows to put extra information into the
context and make it available to the callers of the
ContextWithSpan.
This hook is invoked before the ContextWithSpan function
actually puts the span into the context.
Package-Level Functions (total 11)
ChildOf returns a StartSpanOption pointing to a dependent parent span.
If sc == nil, the option has no effect.
See ChildOfRef, SpanReference
ContextWithSpan returns a new `context.Context` that holds a reference to
the span. If span is nil, a new context without an active span is returned.
FollowsFrom returns a StartSpanOption pointing to a parent Span that caused
the child Span but does not directly depend on its result in any way.
If sc == nil, the option has no effect.
See FollowsFromRef, SpanReference
GlobalTracer returns the global singleton `Tracer` implementation.
Before `SetGlobalTracer()` is called, the `GlobalTracer()` is a noop
implementation that drops all data handed to it.
InitGlobalTracer is deprecated. Please use SetGlobalTracer.
IsGlobalTracerRegistered returns a `bool` to indicate if a tracer has been globally registered
SetGlobalTracer sets the [singleton] opentracing.Tracer returned by
GlobalTracer(). Those who use GlobalTracer (rather than directly manage an
opentracing.Tracer instance) should call SetGlobalTracer as early as
possible in main(), prior to calling the `StartSpan` global func below.
Prior to calling `SetGlobalTracer`, any Spans started via the `StartSpan`
(etc) globals are noops.
SpanFromContext returns the `Span` previously associated with `ctx`, or
`nil` if no such `Span` could be found.
NOTE: context.Context != SpanContext: the former is Go's intra-process
context propagation mechanism, and the latter houses OpenTracing's per-Span
identity and baggage information.
StartSpan defers to `Tracer.StartSpan`. See `GlobalTracer()`.
StartSpanFromContext starts and returns a Span with `operationName`, using
any Span found within `ctx` as a ChildOfRef. If no such parent could be
found, StartSpanFromContext creates a root (parentless) Span.
The second return value is a context.Context object built around the
returned Span.
Example usage:
SomeFunction(ctx context.Context, ...) {
sp, ctx := opentracing.StartSpanFromContext(ctx, "SomeFunction")
defer sp.Finish()
...
}
StartSpanFromContextWithTracer starts and returns a span with `operationName`
using a span found within the context as a ChildOfRef. If that doesn't exist
it creates a root span. It also returns a context.Context object built
around the returned span.
It's behavior is identical to StartSpanFromContext except that it takes an explicit
tracer as opposed to using the global tracer.
Package-Level Variables (total 5)
ErrInvalidCarrier errors occur when Tracer.Inject() or Tracer.Extract()
implementations expect a different type of `carrier` than they are
given.
ErrInvalidSpanContext errors occur when Tracer.Inject() is asked to
operate on a SpanContext which it is not prepared to handle (for
example, since it was created by a different tracer implementation).
ErrSpanContextCorrupted occurs when the `carrier` passed to
Tracer.Extract() is of the expected type but is corrupted.
ErrSpanContextNotFound occurs when the `carrier` passed to
Tracer.Extract() is valid and uncorrupted but has insufficient
information to extract a SpanContext.
ErrUnsupportedFormat occurs when the `format` passed to Tracer.Inject() or
Tracer.Extract() is not recognized by the Tracer implementation.
Package-Level Constants (total 5)
Binary represents SpanContexts as opaque binary data.
For Tracer.Inject(): the carrier must be an `io.Writer`.
For Tracer.Extract(): the carrier must be an `io.Reader`.
ChildOfRef refers to a parent Span that caused *and* somehow depends
upon the new child Span. Often (but not always), the parent Span cannot
finish until the child Span does.
An timing diagram for a ChildOfRef that's blocked on the new Span:
[-Parent Span---------]
[-Child Span----]
See http://opentracing.io/spec/
See opentracing.ChildOf()
FollowsFromRef refers to a parent Span that does not depend in any way
on the result of the new child Span. For instance, one might use
FollowsFromRefs to describe pipeline stages separated by queues,
or a fire-and-forget cache insert at the tail end of a web request.
A FollowsFromRef Span is part of the same logical trace as the new Span:
i.e., the new Span is somehow caused by the work of its FollowsFromRef.
All of the following could be valid timing diagrams for children that
"FollowFrom" a parent.
[-Parent Span-] [-Child Span-]
[-Parent Span--]
[-Child Span-]
[-Parent Span-]
[-Child Span-]
See http://opentracing.io/spec/
See opentracing.FollowsFrom()
HTTPHeaders represents SpanContexts as HTTP header string pairs.
Unlike TextMap, the HTTPHeaders format requires that the keys and values
be valid as HTTP headers as-is (i.e., character casing may be unstable
and special characters are disallowed in keys, values should be
URL-escaped, etc).
For Tracer.Inject(): the carrier must be a `TextMapWriter`.
For Tracer.Extract(): the carrier must be a `TextMapReader`.
See HTTPHeadersCarrier for an implementation of both TextMapWriter
and TextMapReader that defers to an http.Header instance for storage.
For example, Inject():
carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
err := span.Tracer().Inject(
span.Context(), opentracing.HTTPHeaders, carrier)
Or Extract():
carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
clientContext, err := tracer.Extract(
opentracing.HTTPHeaders, carrier)
TextMap represents SpanContexts as key:value string pairs.
Unlike HTTPHeaders, the TextMap format does not restrict the key or
value character sets in any way.
For Tracer.Inject(): the carrier must be a `TextMapWriter`.
For Tracer.Extract(): the carrier must be a `TextMapReader`.
 |
The pages are generated with Golds v0.6.7. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds. |