123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304 |
- package opentracing
- import "time"
- // Tracer is a simple, thin interface for Span creation and SpanContext
- // propagation.
- type Tracer interface {
- // 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),
- // )
- //
- StartSpan(operationName string, opts ...StartSpanOption) Span
- // 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().
- Inject(sm SpanContext, format interface{}, carrier interface{}) 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().
- Extract(format interface{}, carrier interface{}) (SpanContext, error)
- }
- // 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)
- // }
- // ...
- // }
- //
- type StartSpanOptions struct {
- // Zero or more causal references to other Spans (via their SpanContext).
- // If empty, start a "root" Span (i.e., start a new trace).
- References []SpanReference
- // StartTime overrides the Span's start time, or implicitly becomes
- // time.Now() if StartTime.IsZero().
- StartTime time.Time
- // 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.
- Tags map[string]interface{}
- }
- // 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
- type StartSpanOption interface {
- Apply(*StartSpanOptions)
- }
- // 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.
- type SpanReferenceType int
- const (
- // 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()
- ChildOfRef SpanReferenceType = iota
- // 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()
- FollowsFromRef
- )
- // 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.
- type SpanReference struct {
- Type SpanReferenceType
- ReferencedContext SpanContext
- }
- // Apply satisfies the StartSpanOption interface.
- func (r SpanReference) Apply(o *StartSpanOptions) {
- if r.ReferencedContext != nil {
- o.References = append(o.References, r)
- }
- }
- // ChildOf returns a StartSpanOption pointing to a dependent parent span.
- // If sc == nil, the option has no effect.
- //
- // See ChildOfRef, SpanReference
- func ChildOf(sc SpanContext) SpanReference {
- return SpanReference{
- Type: ChildOfRef,
- ReferencedContext: sc,
- }
- }
- // 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
- func FollowsFrom(sc SpanContext) SpanReference {
- return SpanReference{
- Type: FollowsFromRef,
- ReferencedContext: sc,
- }
- }
- // StartTime is a StartSpanOption that sets an explicit start timestamp for the
- // new Span.
- type StartTime time.Time
- // Apply satisfies the StartSpanOption interface.
- func (t StartTime) Apply(o *StartSpanOptions) {
- o.StartTime = time.Time(t)
- }
- // 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.
- type Tags map[string]interface{}
- // Apply satisfies the StartSpanOption interface.
- func (t Tags) Apply(o *StartSpanOptions) {
- if o.Tags == nil {
- o.Tags = make(map[string]interface{})
- }
- for k, v := range t {
- o.Tags[k] = v
- }
- }
- // 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)
- type Tag struct {
- Key string
- Value interface{}
- }
- // Apply satisfies the StartSpanOption interface.
- func (t Tag) Apply(o *StartSpanOptions) {
- if o.Tags == nil {
- o.Tags = make(map[string]interface{})
- }
- o.Tags[t.Key] = t.Value
- }
- // Set applies the tag to an existing Span.
- func (t Tag) Set(s Span) {
- s.SetTag(t.Key, t.Value)
- }
|