-
Notifications
You must be signed in to change notification settings - Fork 418
/
ddtrace.go
180 lines (144 loc) · 7.59 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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
// 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 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 (
"context"
"time"
"gopkg.in/DataDog/dd-trace-go.v1/internal/log"
)
// SpanContextW3C represents a SpanContext with an additional method to allow
// access of the 128-bit trace id of the span, if present.
type SpanContextW3C interface {
SpanContext
// TraceID128 returns the hex-encoded 128-bit trace ID that this context is carrying.
// The string will be exactly 32 bytes and may include leading zeroes.
TraceID128() string
// TraceID128 returns the raw bytes of the 128-bit trace ID that this context is carrying.
TraceID128Bytes() [16]byte
}
// 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 tracer. 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)
}
// SpanLink represents a reference to a span that exists outside of the trace.
//
//go:generate msgp -unexported -marshal=false -o=span_link_msgp.go -tests=false
type SpanLink struct {
// TraceID represents the low 64 bits of the linked span's trace id. This field is required.
TraceID uint64 `msg:"trace_id" json:"trace_id"`
// TraceIDHigh represents the high 64 bits of the linked span's trace id. This field is only set if the linked span's trace id is 128 bits.
TraceIDHigh uint64 `msg:"trace_id_high,omitempty" json:"trace_id_high"`
// SpanID represents the linked span's span id.
SpanID uint64 `msg:"span_id" json:"span_id"`
// Attributes is a mapping of keys to string values. These values are used to add additional context to the span link.
Attributes map[string]string `msg:"attributes,omitempty" json:"attributes"`
// Tracestate is the tracestate of the linked span. This field is optional.
Tracestate string `msg:"tracestate,omitempty" json:"tracestate"`
// Flags represents the W3C trace flags of the linked span. This field is optional.
Flags uint32 `msg:"flags,omitempty" json:"flags"`
}
// 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{}
// SpanID will be the SpanID of the Span, overriding the random number that would
// be generated. If no Parent SpanContext is present, then this will also set the
// TraceID to the same value.
SpanID uint64
// Context is the parent context where the span should be stored.
Context context.Context
// SpanLink represents a causal relationship between two spans. A span can have multiple links.
SpanLinks []SpanLink
}
// Logger implementations are able to log given messages that the tracer or profiler might output.
type Logger interface {
// Log prints the given message.
Log(msg string)
}
// UseLogger sets l as the logger for all tracer and profiler logs.
func UseLogger(l Logger) {
log.UseLogger(l)
}