Debian Codegraph @

trace/trace.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 "encoding/json"
8 )
9
10 const (
11 // FlagsSampled is a bitmask with the sampled bit set. A SpanContext
12 // with the sampling bit set means the span is sampled.
13 FlagsSampled = TraceFlags(0x01)
14
15 // FlagsRandom is a bitmask with the random trace ID flag set. When
16 // set, it signals that the trace ID was generated randomly with at
17 // least 56 bits of randomness (W3C Trace Context Level 2).
18 FlagsRandom = TraceFlags(0x02)
19
20 errInvalidHexID errorConst = "trace-id and span-id can only contain [0-9a-f] characters, all lowercase"
21
22 errInvalidTraceIDLength errorConst = "hex encoded trace-id must have length equals to 32"
23 errNilTraceID errorConst = "trace-id can't be all zero"
24
25 errInvalidSpanIDLength errorConst = "hex encoded span-id must have length equals to 16"
26 errNilSpanID errorConst = "span-id can't be all zero"
27 )
28
29 type errorConst string
30
31 func (e errorConst) Error() string {
32 return string(e)
33 }
34
35 // TraceID is a unique identity of a trace.
36 // nolint:revive // revive complains about stutter of `trace.TraceID`.
37 type TraceID [16]byte
38
39 var (
40 nilTraceID TraceID
41 _ json.Marshaler = nilTraceID
42 )
43
44 // IsValid reports whether the trace TraceID is valid. A valid trace ID does
45 // not consist of zeros only.
46 func (t TraceID) IsValid() bool {
47 return t != nilTraceID
48 }
49
50 // MarshalJSON implements a custom marshal function to encode TraceID
51 // as a hex string.
52 func (t TraceID) MarshalJSON() ([]byte, error) {
53 b := [32 + 2]byte{0: '"', 33: '"'}
54 h := t.hexBytes()
55 copy(b[1:], h[:])
56 return b[:], nil
57 }
58
59 // String returns the hex string representation form of a TraceID.
60 func (t TraceID) String() string {
61 h := t.hexBytes()
62 return string(h[:])
63 }
64
65 // hexBytes returns the hex string representation form of a TraceID.
66 func (t TraceID) hexBytes() [32]byte {
67 return [32]byte{
68 hexLU[t[0x0]>>4], hexLU[t[0x0]&0xf],
69 hexLU[t[0x1]>>4], hexLU[t[0x1]&0xf],
70 hexLU[t[0x2]>>4], hexLU[t[0x2]&0xf],
71 hexLU[t[0x3]>>4], hexLU[t[0x3]&0xf],
72 hexLU[t[0x4]>>4], hexLU[t[0x4]&0xf],
73 hexLU[t[0x5]>>4], hexLU[t[0x5]&0xf],
74 hexLU[t[0x6]>>4], hexLU[t[0x6]&0xf],
75 hexLU[t[0x7]>>4], hexLU[t[0x7]&0xf],
76 hexLU[t[0x8]>>4], hexLU[t[0x8]&0xf],
77 hexLU[t[0x9]>>4], hexLU[t[0x9]&0xf],
78 hexLU[t[0xa]>>4], hexLU[t[0xa]&0xf],
79 hexLU[t[0xb]>>4], hexLU[t[0xb]&0xf],
80 hexLU[t[0xc]>>4], hexLU[t[0xc]&0xf],
81 hexLU[t[0xd]>>4], hexLU[t[0xd]&0xf],
82 hexLU[t[0xe]>>4], hexLU[t[0xe]&0xf],
83 hexLU[t[0xf]>>4], hexLU[t[0xf]&0xf],
84 }
85 }
86
87 // SpanID is a unique identity of a span in a trace.
88 type SpanID [8]byte
89
90 var (
91 nilSpanID SpanID
92 _ json.Marshaler = nilSpanID
93 )
94
95 // IsValid reports whether the SpanID is valid. A valid SpanID does not consist
96 // of zeros only.
97 func (s SpanID) IsValid() bool {
98 return s != nilSpanID
99 }
100
101 // MarshalJSON implements a custom marshal function to encode SpanID
102 // as a hex string.
103 func (s SpanID) MarshalJSON() ([]byte, error) {
104 b := [16 + 2]byte{0: '"', 17: '"'}
105 h := s.hexBytes()
106 copy(b[1:], h[:])
107 return b[:], nil
108 }
109
110 // String returns the hex string representation form of a SpanID.
111 func (s SpanID) String() string {
112 b := s.hexBytes()
113 return string(b[:])
114 }
115
116 func (s SpanID) hexBytes() [16]byte {
117 return [16]byte{
118 hexLU[s[0]>>4], hexLU[s[0]&0xf],
119 hexLU[s[1]>>4], hexLU[s[1]&0xf],
120 hexLU[s[2]>>4], hexLU[s[2]&0xf],
121 hexLU[s[3]>>4], hexLU[s[3]&0xf],
122 hexLU[s[4]>>4], hexLU[s[4]&0xf],
123 hexLU[s[5]>>4], hexLU[s[5]&0xf],
124 hexLU[s[6]>>4], hexLU[s[6]&0xf],
125 hexLU[s[7]>>4], hexLU[s[7]&0xf],
126 }
127 }
128
129 // TraceIDFromHex returns a TraceID from a hex string if it is compliant with
130 // the W3C trace-context specification. See more at
131 // https://www.w3.org/TR/trace-context/#trace-id
132 // nolint:revive // revive complains about stutter of `trace.TraceIDFromHex`.
133 func TraceIDFromHex(h string) (TraceID, error) {
134 if len(h) != 32 {
135 return [16]byte{}, errInvalidTraceIDLength
136 }
137 var b [16]byte
138 invalidMark := byte(0)
139 for i := 0; i < len(h); i += 4 {
140 b[i/2] = (hexRev[h[i]] << 4) | hexRev[h[i+1]]
141 b[i/2+1] = (hexRev[h[i+2]] << 4) | hexRev[h[i+3]]
142 invalidMark |= hexRev[h[i]] | hexRev[h[i+1]] | hexRev[h[i+2]] | hexRev[h[i+3]]
143 }
144 // If the upper 4 bits of any byte are not zero, there was an invalid hex
145 // character since invalid hex characters are 0xff in hexRev.
146 if invalidMark&0xf0 != 0 {
147 return [16]byte{}, errInvalidHexID
148 }
149 // If we didn't set any bits, then h was all zeros.
150 if invalidMark == 0 {
151 return [16]byte{}, errNilTraceID
152 }
153 return b, nil
154 }
155
156 // SpanIDFromHex returns a SpanID from a hex string if it is compliant
157 // with the w3c trace-context specification.
158 // See more at https://www.w3.org/TR/trace-context/#parent-id
159 func SpanIDFromHex(h string) (SpanID, error) {
160 if len(h) != 16 {
161 return [8]byte{}, errInvalidSpanIDLength
162 }
163 var b [8]byte
164 invalidMark := byte(0)
165 for i := 0; i < len(h); i += 4 {
166 b[i/2] = (hexRev[h[i]] << 4) | hexRev[h[i+1]]
167 b[i/2+1] = (hexRev[h[i+2]] << 4) | hexRev[h[i+3]]
168 invalidMark |= hexRev[h[i]] | hexRev[h[i+1]] | hexRev[h[i+2]] | hexRev[h[i+3]]
169 }
170 // If the upper 4 bits of any byte are not zero, there was an invalid hex
171 // character since invalid hex characters are 0xff in hexRev.
172 if invalidMark&0xf0 != 0 {
173 return [8]byte{}, errInvalidHexID
174 }
175 // If we didn't set any bits, then h was all zeros.
176 if invalidMark == 0 {
177 return [8]byte{}, errNilSpanID
178 }
179 return b, nil
180 }
181
182 // TraceFlags contains flags that can be set on a SpanContext.
183 type TraceFlags byte //nolint:revive // revive complains about stutter of `trace.TraceFlags`.
184
185 // IsSampled reports whether the sampling bit is set in the TraceFlags.
186 func (tf TraceFlags) IsSampled() bool {
187 return tf&FlagsSampled == FlagsSampled
188 }
189
190 // WithSampled sets the sampling bit in a new copy of the TraceFlags.
191 func (tf TraceFlags) WithSampled(sampled bool) TraceFlags { // nolint:revive // sampled is not a control flag.
192 if sampled {
193 return tf | FlagsSampled
194 }
195
196 return tf &^ FlagsSampled
197 }
198
199 // IsRandom reports whether the random bit is set in the TraceFlags.
200 func (tf TraceFlags) IsRandom() bool {
201 return tf&FlagsRandom == FlagsRandom
202 }
203
204 // WithRandom sets the random bit in a new copy of the TraceFlags.
205 func (tf TraceFlags) WithRandom(random bool) TraceFlags { // nolint:revive // random is not a control flag.
206 if random {
207 return tf | FlagsRandom
208 }
209
210 return tf &^ FlagsRandom
211 }
212
213 // MarshalJSON implements a custom marshal function to encode TraceFlags
214 // as a hex string.
215 func (tf TraceFlags) MarshalJSON() ([]byte, error) {
216 b := [2 + 2]byte{0: '"', 3: '"'}
217 h := tf.hexBytes()
218 copy(b[1:], h[:])
219 return b[:], nil
220 }
221
222 // String returns the hex string representation form of TraceFlags.
223 func (tf TraceFlags) String() string {
224 h := tf.hexBytes()
225 return string(h[:])
226 }
227
228 func (tf TraceFlags) hexBytes() [2]byte {
229 return [2]byte{hexLU[tf>>4], hexLU[tf&0xf]}
230 }
231
232 // SpanContextConfig contains mutable fields usable for constructing
233 // an immutable SpanContext.
234 type SpanContextConfig struct {
235 TraceID TraceID
236 SpanID SpanID
237 TraceFlags TraceFlags
238 TraceState TraceState
239 Remote bool
240 }
241
242 // NewSpanContext constructs a SpanContext using values from the provided
243 // SpanContextConfig.
244 func NewSpanContext(config SpanContextConfig) SpanContext {
245 return SpanContext{
246 traceID: config.TraceID,
247 spanID: config.SpanID,
248 traceFlags: config.TraceFlags,
249 traceState: config.TraceState,
250 remote: config.Remote,
251 }
252 }
253
254 // SpanContext contains identifying trace information about a Span.
255 type SpanContext struct {
256 traceID TraceID
257 spanID SpanID
258 traceFlags TraceFlags
259 traceState TraceState
260 remote bool
261 }
262
263 var _ json.Marshaler = SpanContext{}
264
265 // IsValid reports whether the SpanContext is valid. A valid span context has a
266 // valid TraceID and SpanID.
267 func (sc SpanContext) IsValid() bool {
268 return sc.HasTraceID() && sc.HasSpanID()
269 }
270
271 // IsRemote reports whether the SpanContext represents a remotely-created Span.
272 func (sc SpanContext) IsRemote() bool {
273 return sc.remote
274 }
275
276 // WithRemote returns a copy of sc with the Remote property set to remote.
277 func (sc SpanContext) WithRemote(remote bool) SpanContext {
278 return SpanContext{
279 traceID: sc.traceID,
280 spanID: sc.spanID,
281 traceFlags: sc.traceFlags,
282 traceState: sc.traceState,
283 remote: remote,
284 }
285 }
286
287 // TraceID returns the TraceID from the SpanContext.
288 func (sc SpanContext) TraceID() TraceID {
289 return sc.traceID
290 }
291
292 // HasTraceID reports whether the SpanContext has a valid TraceID.
293 func (sc SpanContext) HasTraceID() bool {
294 return sc.traceID.IsValid()
295 }
296
297 // WithTraceID returns a new SpanContext with the TraceID replaced.
298 func (sc SpanContext) WithTraceID(traceID TraceID) SpanContext {
299 return SpanContext{
300 traceID: traceID,
301 spanID: sc.spanID,
302 traceFlags: sc.traceFlags,
303 traceState: sc.traceState,
304 remote: sc.remote,
305 }
306 }
307
308 // SpanID returns the SpanID from the SpanContext.
309 func (sc SpanContext) SpanID() SpanID {
310 return sc.spanID
311 }
312
313 // HasSpanID reports whether the SpanContext has a valid SpanID.
314 func (sc SpanContext) HasSpanID() bool {
315 return sc.spanID.IsValid()
316 }
317
318 // WithSpanID returns a new SpanContext with the SpanID replaced.
319 func (sc SpanContext) WithSpanID(spanID SpanID) SpanContext {
320 return SpanContext{
321 traceID: sc.traceID,
322 spanID: spanID,
323 traceFlags: sc.traceFlags,
324 traceState: sc.traceState,
325 remote: sc.remote,
326 }
327 }
328
329 // TraceFlags returns the flags from the SpanContext.
330 func (sc SpanContext) TraceFlags() TraceFlags {
331 return sc.traceFlags
332 }
333
334 // IsSampled reports whether the sampling bit is set in the SpanContext's TraceFlags.
335 func (sc SpanContext) IsSampled() bool {
336 return sc.traceFlags.IsSampled()
337 }
338
339 // IsRandom reports whether the random bit is set in the SpanContext's TraceFlags.
340 func (sc SpanContext) IsRandom() bool {
341 return sc.traceFlags.IsRandom()
342 }
343
344 // WithTraceFlags returns a new SpanContext with the TraceFlags replaced.
345 func (sc SpanContext) WithTraceFlags(flags TraceFlags) SpanContext {
346 return SpanContext{
347 traceID: sc.traceID,
348 spanID: sc.spanID,
349 traceFlags: flags,
350 traceState: sc.traceState,
351 remote: sc.remote,
352 }
353 }
354
355 // TraceState returns the TraceState from the SpanContext.
356 func (sc SpanContext) TraceState() TraceState {
357 return sc.traceState
358 }
359
360 // WithTraceState returns a new SpanContext with the TraceState replaced.
361 func (sc SpanContext) WithTraceState(state TraceState) SpanContext {
362 return SpanContext{
363 traceID: sc.traceID,
364 spanID: sc.spanID,
365 traceFlags: sc.traceFlags,
366 traceState: state,
367 remote: sc.remote,
368 }
369 }
370
371 // Equal reports whether two SpanContext values are equal.
372 func (sc SpanContext) Equal(other SpanContext) bool {
373 return sc.traceID == other.traceID &&
374 sc.spanID == other.spanID &&
375 sc.traceFlags == other.traceFlags &&
376 sc.traceState.String() == other.traceState.String() &&
377 sc.remote == other.remote
378 }
379
380 // MarshalJSON implements a custom marshal function to encode a SpanContext.
381 func (sc SpanContext) MarshalJSON() ([]byte, error) {
382 return json.Marshal(SpanContextConfig{
383 TraceID: sc.traceID,
384 SpanID: sc.spanID,
385 TraceFlags: sc.traceFlags,
386 TraceState: sc.traceState,
387 Remote: sc.remote,
388 })
389 }