Documentation
¶
Overview ¶
Package tracing provides very basic distributed tracing. The key type in this package is Span, which contains metadata about the execution of an arbitrary section of code.
Index ¶
Examples ¶
Constants ¶
const NoErrorSupplied = "<no error supplied for this span error>"
NoErrorSupplied is the string returned from SpanError.Error() if no causal error is supplied to NewSpanError
Variables ¶
This section is empty.
Functions ¶
func MergeSpans ¶
func MergeSpans(container interface{}, spans ...interface{}) (interface{}, bool)
MergeSpans attempts to merge the given spans into a container. If container does not implement Mergeable, or if spans is empty, then this function returns container as is with a false. Otherwise, each element of spans is merged with container, and result of container.WithSpans is returned with a true.
Similar to Spans, each element of spans may be of type Span, []Span, or Spanned. Any other type is skipped without error.
Types ¶
type Mergeable ¶
type Mergeable interface {
Spanned
// WithSpans returns an instance of this object with the new Spans, possibly
// merged into those returned by Spans. This method should generally return
// a shallow copy of itself with the new spans, to preserve immutability.
WithSpans(...Span) interface{}
}
Mergeable represents a Spanned which can be merged with other spans
type NopMergeable ¶
type NopMergeable []Span
NopMergeable is just a Mergeable with no other state. This is useful for tests.
func (NopMergeable) Spans ¶
func (nm NopMergeable) Spans() []Span
func (NopMergeable) WithSpans ¶
func (nm NopMergeable) WithSpans(spans ...Span) interface{}
type Span ¶
type Span interface {
// Name is the name of the operation
Name() string
// Start is the time at which the operation started
Start() time.Time
// Duration is how long the operation took. This value is computed once, when the
// closure from Spanner.Start is called.
Duration() time.Duration
// Error is any error that occurred. This will be the error passed to the closure
// returned from Spanner.Start. This error can be nil.
Error() error
}
Span represents the result of some arbitrary section of code. Clients create Span objects via a Spanner. A Span is immutable once it has been created via a Spanner closure.
func Spans ¶
Spans extracts the slice of Span instances from a container, if possible.
If container implements Spanned, then container.Spans() is returned with a true. If container is a Span, a slice of that one element is returned with a true. If container is a []Span, it's returned as is with a true. Otherwise, this function returns nil, false.
type SpanError ¶
type SpanError interface {
error
Mergeable
// Err returns the causal error object which is associated with the spans. Error() returns
// the value from this instance. Although it would be unusual, this value can be nil.
Err() error
}
SpanError represents an error that has one or more spans associated with it. A SpanError augments an original error, accessible via Err(), with zero or more spans.
This error type also implements Mergeable from this package, allowing it to aggregate spans under a single causal error.
func NewSpanError ¶
NewSpanError "span-izes" an existing error object, returning the SpanError which annotates that error with one or more spans.
type Spanned ¶
type Spanned interface {
Spans() []Span
}
Spanned can be implemented by message objects to describe the spans involved in producing the message. Generally, this interface should be implemented on transient objects that pass through the layers of an application.
type Spanner ¶
type Spanner interface {
// Start begins a new, unfinished span. The returned closure must be called
// to finished the span, recording it with a duration and the given error. The
// returned closure is idempotent and only records the duration and error of the first call.
// It always returns the same Span instance, and that instance is immutable once the
// closure is called.
Start(string) func(error) Span
}
Spanner acts as a factory for Spans
Example ¶
var (
now time.Time
duration = 100 * time.Millisecond
// production code can ignore now and since
// we do this just to get consistent output
spanner = NewSpanner(
Now(func() time.Time { return now }),
Since(func(time.Time) time.Duration { return duration }),
)
spans = make(chan Span, 2)
firstDone = new(sync.WaitGroup)
)
firstDone.Add(1)
go func() {
defer firstDone.Done()
finisher := spanner.Start("success")
// a successful operation happens here ...
spans <- finisher(nil)
}()
go func() {
defer close(spans)
firstDone.Wait()
finisher := spanner.Start("failure")
// an operation that fails happens here ...
spans <- finisher(errors.New("this operation failed"))
}()
for s := range spans {
fmt.Println(s.Name(), s.Start(), s.Duration(), s.Error())
}
Output: success 0001-01-01 00:00:00 +0000 UTC 100ms <nil> failure 0001-01-01 00:00:00 +0000 UTC 100ms this operation failed
func NewSpanner ¶
func NewSpanner(o ...SpannerOption) Spanner
NewSpanner constructs a new Spanner with the given options. By default, a Spanner will use time.Now() to get the current time and time.Since() to compute durations.
type SpannerOption ¶
type SpannerOption func(*spanner)
SpannerOption supplies a configuration option to a Spanner.
func Now ¶
func Now(now func() time.Time) SpannerOption
Now sets a now function on a spanner. If now is nil, this option does nothing. This options is primarily useful for testing, however it can be useful in production situations. For example, this option can be used to emit times with a consistent time zone, like UTC.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package tracinghttp provides marshaling support for tracing data into HTTP requests and responses
|
Package tracinghttp provides marshaling support for tracing data into HTTP requests and responses |