Debian Codegraph @

trace/config.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package trace // import "go.opentelemetry.io/otel/trace"
5
6 import (
7 "slices"
8 "time"
9
10 "go.opentelemetry.io/otel/attribute"
11 )
12
13 // TracerConfig is a group of options for a Tracer.
14 type TracerConfig struct {
15 instrumentationVersion string
16 // Schema URL of the telemetry emitted by the Tracer.
17 schemaURL string
18 attrs attribute.Set
19 }
20
21 // InstrumentationVersion returns the version of the library providing instrumentation.
22 func (t *TracerConfig) InstrumentationVersion() string {
23 return t.instrumentationVersion
24 }
25
26 // InstrumentationAttributes returns the attributes associated with the library
27 // providing instrumentation.
28 func (t *TracerConfig) InstrumentationAttributes() attribute.Set {
29 return t.attrs
30 }
31
32 // SchemaURL returns the Schema URL of the telemetry emitted by the Tracer.
33 func (t *TracerConfig) SchemaURL() string {
34 return t.schemaURL
35 }
36
37 // NewTracerConfig applies all the options to a returned TracerConfig.
38 func NewTracerConfig(options ...TracerOption) TracerConfig {
39 var config TracerConfig
40 for _, option := range options {
41 config = option.apply(config)
42 }
43 return config
44 }
45
46 // TracerOption applies an option to a TracerConfig.
47 type TracerOption interface {
48 apply(TracerConfig) TracerConfig
49 }
50
51 type tracerOptionFunc func(TracerConfig) TracerConfig
52
53 func (fn tracerOptionFunc) apply(cfg TracerConfig) TracerConfig {
54 return fn(cfg)
55 }
56
57 // SpanConfig is a group of options for a Span.
58 type SpanConfig struct {
59 attributes []attribute.KeyValue
60 timestamp time.Time
61 links []Link
62 newRoot bool
63 spanKind SpanKind
64 stackTrace bool
65 }
66
67 // Attributes describe the associated qualities of a Span.
68 func (cfg *SpanConfig) Attributes() []attribute.KeyValue {
69 return cfg.attributes
70 }
71
72 // Timestamp is a time in a Span life-cycle.
73 func (cfg *SpanConfig) Timestamp() time.Time {
74 return cfg.timestamp
75 }
76
77 // StackTrace reports whether stack trace capturing is enabled.
78 func (cfg *SpanConfig) StackTrace() bool {
79 return cfg.stackTrace
80 }
81
82 // Links are the associations a Span has with other Spans.
83 func (cfg *SpanConfig) Links() []Link {
84 return cfg.links
85 }
86
87 // NewRoot identifies a Span as the root Span for a new trace. This is
88 // commonly used when an existing trace crosses trust boundaries and the
89 // remote parent span context should be ignored for security.
90 func (cfg *SpanConfig) NewRoot() bool {
91 return cfg.newRoot
92 }
93
94 // SpanKind is the role a Span has in a trace.
95 func (cfg *SpanConfig) SpanKind() SpanKind {
96 return cfg.spanKind
97 }
98
99 // NewSpanStartConfig applies all the options to a returned SpanConfig.
100 // No validation is performed on the returned SpanConfig (e.g. no uniqueness
101 // checking or bounding of data), it is left to the SDK to perform this
102 // action.
103 func NewSpanStartConfig(options ...SpanStartOption) SpanConfig {
104 var c SpanConfig
105 for _, option := range options {
106 c = option.applySpanStart(c)
107 }
108 return c
109 }
110
111 // NewSpanEndConfig applies all the options to a returned SpanConfig.
112 // No validation is performed on the returned SpanConfig (e.g. no uniqueness
113 // checking or bounding of data), it is left to the SDK to perform this
114 // action.
115 func NewSpanEndConfig(options ...SpanEndOption) SpanConfig {
116 var c SpanConfig
117 for _, option := range options {
118 c = option.applySpanEnd(c)
119 }
120 return c
121 }
122
123 // SpanStartOption applies an option to a SpanConfig. These options are applicable
124 // only when the span is created.
125 type SpanStartOption interface {
126 applySpanStart(SpanConfig) SpanConfig
127 }
128
129 type spanOptionFunc func(SpanConfig) SpanConfig
130
131 func (fn spanOptionFunc) applySpanStart(cfg SpanConfig) SpanConfig {
132 return fn(cfg)
133 }
134
135 // SpanEndOption applies an option to a SpanConfig. These options are
136 // applicable only when the span is ended.
137 type SpanEndOption interface {
138 applySpanEnd(SpanConfig) SpanConfig
139 }
140
141 // EventConfig is a group of options for an Event.
142 type EventConfig struct {
143 attributes []attribute.KeyValue
144 timestamp time.Time
145 stackTrace bool
146 }
147
148 // Attributes describe the associated qualities of an Event.
149 func (cfg *EventConfig) Attributes() []attribute.KeyValue {
150 return cfg.attributes
151 }
152
153 // Timestamp is a time in an Event life-cycle.
154 func (cfg *EventConfig) Timestamp() time.Time {
155 return cfg.timestamp
156 }
157
158 // StackTrace reports whether stack trace capturing is enabled.
159 func (cfg *EventConfig) StackTrace() bool {
160 return cfg.stackTrace
161 }
162
163 // NewEventConfig applies all the EventOptions to a returned EventConfig. If no
164 // timestamp option is passed, the returned EventConfig will have a Timestamp
165 // set to the call time, otherwise no validation is performed on the returned
166 // EventConfig.
167 func NewEventConfig(options ...EventOption) EventConfig {
168 var c EventConfig
169 for _, option := range options {
170 c = option.applyEvent(c)
171 }
172 if c.timestamp.IsZero() {
173 c.timestamp = time.Now()
174 }
175 return c
176 }
177
178 // EventOption applies span event options to an EventConfig.
179 type EventOption interface {
180 applyEvent(EventConfig) EventConfig
181 }
182
183 // SpanOption are options that can be used at both the beginning and end of a span.
184 type SpanOption interface {
185 SpanStartOption
186 SpanEndOption
187 }
188
189 // SpanStartEventOption are options that can be used at the start of a span, or with an event.
190 type SpanStartEventOption interface {
191 SpanStartOption
192 EventOption
193 }
194
195 // SpanEndEventOption are options that can be used at the end of a span, or with an event.
196 type SpanEndEventOption interface {
197 SpanEndOption
198 EventOption
199 }
200
201 type attributeOption []attribute.KeyValue
202
203 func (o attributeOption) applySpan(c SpanConfig) SpanConfig {
204 c.attributes = append(c.attributes, []attribute.KeyValue(o)...)
205 return c
206 }
207 func (o attributeOption) applySpanStart(c SpanConfig) SpanConfig { return o.applySpan(c) }
208 func (o attributeOption) applyEvent(c EventConfig) EventConfig {
209 c.attributes = append(c.attributes, []attribute.KeyValue(o)...)
210 return c
211 }
212
213 var _ SpanStartEventOption = attributeOption{}
214
215 // WithAttributes adds the attributes related to a span life-cycle event.
216 // These attributes are used to describe the work a Span represents when this
217 // option is provided to a Span's start event. Otherwise, these
218 // attributes provide additional information about the event being recorded
219 // (e.g. error, state change, processing progress, system event).
220 //
221 // If multiple of these options are passed the attributes of each successive
222 // option will extend the attributes instead of overwriting. There is no
223 // guarantee of uniqueness in the resulting attributes.
224 func WithAttributes(attributes ...attribute.KeyValue) SpanStartEventOption {
225 return attributeOption(attributes)
226 }
227
228 // SpanEventOption are options that can be used with an event or a span.
229 type SpanEventOption interface {
230 SpanOption
231 EventOption
232 }
233
234 type timestampOption time.Time
235
236 func (o timestampOption) applySpan(c SpanConfig) SpanConfig {
237 c.timestamp = time.Time(o)
238 return c
239 }
240 func (o timestampOption) applySpanStart(c SpanConfig) SpanConfig { return o.applySpan(c) }
241 func (o timestampOption) applySpanEnd(c SpanConfig) SpanConfig { return o.applySpan(c) }
242 func (o timestampOption) applyEvent(c EventConfig) EventConfig {
243 c.timestamp = time.Time(o)
244 return c
245 }
246
247 var _ SpanEventOption = timestampOption{}
248
249 // WithTimestamp sets the time of a Span or Event life-cycle moment (e.g.
250 // started, stopped, errored).
251 func WithTimestamp(t time.Time) SpanEventOption {
252 return timestampOption(t)
253 }
254
255 type stackTraceOption bool
256
257 func (o stackTraceOption) applyEvent(c EventConfig) EventConfig {
258 c.stackTrace = bool(o)
259 return c
260 }
261
262 func (o stackTraceOption) applySpan(c SpanConfig) SpanConfig {
263 c.stackTrace = bool(o)
264 return c
265 }
266 func (o stackTraceOption) applySpanEnd(c SpanConfig) SpanConfig { return o.applySpan(c) }
267
268 // WithStackTrace sets the flag to capture the error with stack trace (e.g. true, false).
269 func WithStackTrace(b bool) SpanEndEventOption {
270 return stackTraceOption(b)
271 }
272
273 // WithLinks adds links to a Span. The links are added to the existing Span
274 // links, i.e. this does not overwrite. Links with invalid span context are ignored.
275 func WithLinks(links ...Link) SpanStartOption {
276 return spanOptionFunc(func(cfg SpanConfig) SpanConfig {
277 cfg.links = append(cfg.links, links...)
278 return cfg
279 })
280 }
281
282 // WithNewRoot specifies that the Span should be treated as a root Span. Any
283 // existing parent span context will be ignored when defining the Span's trace
284 // identifiers.
285 func WithNewRoot() SpanStartOption {
286 return spanOptionFunc(func(cfg SpanConfig) SpanConfig {
287 cfg.newRoot = true
288 return cfg
289 })
290 }
291
292 // WithSpanKind sets the SpanKind of a Span.
293 func WithSpanKind(kind SpanKind) SpanStartOption {
294 return spanOptionFunc(func(cfg SpanConfig) SpanConfig {
295 cfg.spanKind = kind
296 return cfg
297 })
298 }
299
300 // WithInstrumentationVersion sets the instrumentation version.
301 func WithInstrumentationVersion(version string) TracerOption {
302 return tracerOptionFunc(func(cfg TracerConfig) TracerConfig {
303 cfg.instrumentationVersion = version
304 return cfg
305 })
306 }
307
308 // mergeSets returns the union of keys between a and b. Any duplicate keys will
309 // use the value associated with b.
310 func mergeSets(a, b attribute.Set) attribute.Set {
311 // NewMergeIterator uses the first value for any duplicates.
312 iter := attribute.NewMergeIterator(&b, &a)
313 merged := make([]attribute.KeyValue, 0, a.Len()+b.Len())
314 for iter.Next() {
315 merged = append(merged, iter.Attribute())
316 }
317 return attribute.NewSet(merged...)
318 }
319
320 // WithInstrumentationAttributes adds the instrumentation attributes.
321 //
322 // This is equivalent to calling [WithInstrumentationAttributeSet] with an
323 // [attribute.Set] created from a clone of the passed attributes.
324 // [WithInstrumentationAttributeSet] is recommended for more control.
325 //
326 // If multiple [WithInstrumentationAttributes] or [WithInstrumentationAttributeSet]
327 // options are passed, the attributes will be merged together in the order
328 // they are passed. Attributes with duplicate keys will use the last value passed.
329 func WithInstrumentationAttributes(attr ...attribute.KeyValue) TracerOption {
330 set := attribute.NewSet(slices.Clone(attr)...)
331 return WithInstrumentationAttributeSet(set)
332 }
333
334 // WithInstrumentationAttributeSet adds the instrumentation attributes.
335 //
336 // If multiple [WithInstrumentationAttributes] or [WithInstrumentationAttributeSet]
337 // options are passed, the attributes will be merged together in the order
338 // they are passed. Attributes with duplicate keys will use the last value passed.
339 func WithInstrumentationAttributeSet(set attribute.Set) TracerOption {
340 if set.Len() == 0 {
341 return tracerOptionFunc(func(config TracerConfig) TracerConfig {
342 return config
343 })
344 }
345
346 return tracerOptionFunc(func(config TracerConfig) TracerConfig {
347 if config.attrs.Len() == 0 {
348 config.attrs = set
349 } else {
350 config.attrs = mergeSets(config.attrs, set)
351 }
352 return config
353 })
354 }
355
356 // WithSchemaURL sets the schema URL for the Tracer.
357 func WithSchemaURL(schemaURL string) TracerOption {
358 return tracerOptionFunc(func(cfg TracerConfig) TracerConfig {
359 cfg.schemaURL = schemaURL
360 return cfg
361 })
362 }