forked from DataDog/dd-trace-go
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ddtrace.go
132 lines (105 loc) · 5.64 KB
/
ddtrace.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
// Unless explicitly stated otherwise all files in this repository are licensed
// under the Apache License Version 2.0.
// This product includes software developed at Datadog (https://www.datadoghq.com/).
// Copyright 2016-2019 Datadog, Inc.
// Package ddtrace contains the interfaces that specify the implementations of Datadog's
// tracing library, as well as a set of sub-packages containing various implementations:
// our native implementation ("tracer"), a wrapper that can be used with Opentracing
// ("opentracer") and a mock tracer to be used for testing ("mocktracer"). Additionally,
// package "ext" provides a set of tag names and values specific to Datadog's APM product.
//
// To get started, visit the documentation for any of the packages you'd like to begin
// with by accessing the subdirectories of this package: https://godoc.org/gopkg.in/DataDog/dd-trace-go.v1/ddtrace#pkg-subdirectories.
package ddtrace // import "gopkg.in/DataDog/dd-trace-go.v1/ddtrace"
import "time"
// Tracer specifies an implementation of the Datadog tracer which allows starting
// and propagating spans. The official implementation if exposed as functions
// within the "tracer" package.
type Tracer interface {
// StartSpan starts a span with the given operation name and options.
StartSpan(operationName string, opts ...StartSpanOption) Span
// Extract extracts a span context from a given carrier. Note that baggage item
// keys will always be lower-cased to maintain consistency. It is impossible to
// maintain the original casing due to MIME header canonicalization standards.
Extract(carrier interface{}) (SpanContext, error)
// Inject injects a span context into the given carrier.
Inject(context SpanContext, carrier interface{}) error
// Stop stops the active tracer and sets the global tracer to a no-op. Calls to
// Stop should be idempotent.
Stop()
}
// Span represents a chunk of computation time. Spans have names, durations,
// timestamps and other metadata. A Tracer is used to create hierarchies of
// spans in a request, buffer and submit them to the server.
type Span interface {
// SetTag sets a key/value pair as metadata on the span.
SetTag(key string, value interface{})
// SetOperationName sets the operation name for this span. An operation name should be
// a representative name for a group of spans (e.g. "grpc.server" or "http.request").
SetOperationName(operationName string)
// BaggageItem returns the baggage item held by the given key.
BaggageItem(key string) string
// SetBaggageItem sets a new baggage item at the given key. The baggage
// item should propagate to all descendant spans, both in- and cross-process.
SetBaggageItem(key, val string)
// Finish finishes the current span with the given options. Finish calls should be idempotent.
Finish(opts ...FinishOption)
// Context returns the SpanContext of this Span.
Context() SpanContext
}
// SpanContext represents a span state that can propagate to descendant spans
// and across process boundaries. It contains all the information needed to
// spawn a direct descendant of the span that it belongs to. It can be used
// to create distributed tracing by propagating it using the provided interfaces.
type SpanContext interface {
// SpanID returns the span ID that this context is carrying.
SpanID() uint64
// TraceID returns the trace ID that this context is carrying.
TraceID() uint64
// ForeachBaggageItem provides an iterator over the key/value pairs set as
// baggage within this context. Iteration stops when the handler returns
// false.
ForeachBaggageItem(handler func(k, v string) bool)
}
// StartSpanOption is a configuration option that can be used with a Tracer's StartSpan method.
type StartSpanOption func(cfg *StartSpanConfig)
// FinishOption is a configuration option that can be used with a Span's Finish method.
type FinishOption func(cfg *FinishConfig)
// FinishConfig holds the configuration for finishing a span. It is usually passed around by
// reference to one or more FinishOption functions which shape it into its final form.
type FinishConfig struct {
// FinishTime represents the time that should be set as finishing time for the
// span. Implementations should use the current time when FinishTime.IsZero().
FinishTime time.Time
// Error holds an optional error that should be set on the span before
// finishing.
Error error
// NoDebugStack will prevent any set errors from generating an attached stack trace tag.
NoDebugStack bool
// StackFrames specifies the number of stack frames to be attached in spans that finish with errors.
StackFrames uint
// SkipStackFrames specifies the offset at which to start reporting stack frames from the stack.
SkipStackFrames uint
}
// StartSpanConfig holds the configuration for starting a new span. It is usually passed
// around by reference to one or more StartSpanOption functions which shape it into its
// final form.
type StartSpanConfig struct {
// Parent holds the SpanContext that should be used as a parent for the
// new span. If nil, implementations should return a root span.
Parent SpanContext
// StartTime holds the time that should be used as the start time of the span.
// Implementations should use the current time when StartTime.IsZero().
StartTime time.Time
// Tags holds a set of key/value pairs that should be set as metadata on the
// new span.
Tags map[string]interface{}
// Force-set the SpanID, rather than use a random number. If no Parent SpanContext is present,
// then this will also set the TraceID to the same value.
SpanID uint64
}
// Logger implementations are able to log given messages that the tracer might output.
type Logger interface {
// Log prints the given message.
Log(msg string)
}