1// Copyright The OpenTelemetry Authors
2// SPDX-License-Identifier: Apache-2.0
3
4package telemetry // import "go.opentelemetry.io/otel/trace/internal/telemetry"
5
6import (
7 "bytes"
8 "encoding/hex"
9 "encoding/json"
10 "errors"
11 "fmt"
12 "io"
13 "math"
14 "time"
15)
16
17// A Span represents a single operation performed by a single component of the
18// system.
19type Span struct {
20 // A unique identifier for a trace. All spans from the same trace share
21 // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes OR
22 // of length other than 16 bytes is considered invalid (empty string in OTLP/JSON
23 // is zero-length and thus is also invalid).
24 //
25 // This field is required.
26 TraceID TraceID `json:"traceId,omitempty"`
27 // A unique identifier for a span within a trace, assigned when the span
28 // is created. The ID is an 8-byte array. An ID with all zeroes OR of length
29 // other than 8 bytes is considered invalid (empty string in OTLP/JSON
30 // is zero-length and thus is also invalid).
31 //
32 // This field is required.
33 SpanID SpanID `json:"spanId,omitempty"`
34 // trace_state conveys information about request position in multiple distributed tracing graphs.
35 // It is a trace_state in w3c-trace-context format: https://www.w3.org/TR/trace-context/#tracestate-header
36 // See also https://github.com/w3c/distributed-tracing for more details about this field.
37 TraceState string `json:"traceState,omitempty"`
38 // The `span_id` of this span's parent span. If this is a root span, then this
39 // field must be empty. The ID is an 8-byte array.
40 ParentSpanID SpanID `json:"parentSpanId,omitempty"`
41 // Flags, a bit field.
42 //
43 // Bits 0-7 (8 least significant bits) are the trace flags as defined in W3C Trace
44 // Context specification. To read the 8-bit W3C trace flag, use
45 // `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
46 //
47 // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
48 //
49 // Bits 8 and 9 represent the 3 states of whether a span's parent
50 // is remote. The states are (unknown, is not remote, is remote).
51 // To read whether the value is known, use `(flags & SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK) != 0`.
52 // To read whether the span is remote, use `(flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
53 //
54 // When creating span messages, if the message is logically forwarded from another source
55 // with an equivalent flags fields (i.e., usually another OTLP span message), the field SHOULD
56 // be copied as-is. If creating from a source that does not have an equivalent flags field
57 // (such as a runtime representation of an OpenTelemetry span), the high 22 bits MUST
58 // be set to zero.
59 // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero.
60 //
61 // [Optional].
62 Flags uint32 `json:"flags,omitempty"`
63 // A description of the span's operation.
64 //
65 // For example, the name can be a qualified method name or a file name
66 // and a line number where the operation is called. A best practice is to use
67 // the same display name at the same call point in an application.
68 // This makes it easier to correlate spans in different traces.
69 //
70 // This field is semantically required to be set to non-empty string.
71 // Empty value is equivalent to an unknown span name.
72 //
73 // This field is required.
74 Name string `json:"name"`
75 // Distinguishes between spans generated in a particular context. For example,
76 // two spans with the same name may be distinguished using `CLIENT` (caller)
77 // and `SERVER` (callee) to identify queueing latency associated with the span.
78 Kind SpanKind `json:"kind,omitempty"`
79 // start_time_unix_nano is the start time of the span. On the client side, this is the time
80 // kept by the local machine where the span execution starts. On the server side, this
81 // is the time when the server's application handler starts running.
82 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
83 //
84 // This field is semantically required and it is expected that end_time >= start_time.
85 StartTime time.Time `json:"startTimeUnixNano,omitempty"`
86 // end_time_unix_nano is the end time of the span. On the client side, this is the time
87 // kept by the local machine where the span execution ends. On the server side, this
88 // is the time when the server application handler stops running.
89 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
90 //
91 // This field is semantically required and it is expected that end_time >= start_time.
92 EndTime time.Time `json:"endTimeUnixNano,omitempty"`
93 // attributes is a collection of key/value pairs. Note, global attributes
94 // like server name can be set using the resource API. Examples of attributes:
95 //
96 // "/http/user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"
97 // "/http/server_latency": 300
98 // "example.com/myattribute": true
99 // "example.com/score": 10.239
100 //
101 // The OpenTelemetry API specification further restricts the allowed value types:
102 // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute
103 // Attribute keys MUST be unique (it is not allowed to have more than one
104 // attribute with the same key).
105 Attrs []Attr `json:"attributes,omitempty"`
106 // dropped_attributes_count is the number of attributes that were discarded. Attributes
107 // can be discarded because their keys are too long or because there are too many
108 // attributes. If this value is 0, then no attributes were dropped.
109 DroppedAttrs uint32 `json:"droppedAttributesCount,omitempty"`
110 // events is a collection of Event items.
111 Events []*SpanEvent `json:"events,omitempty"`
112 // dropped_events_count is the number of dropped events. If the value is 0, then no
113 // events were dropped.
114 DroppedEvents uint32 `json:"droppedEventsCount,omitempty"`
115 // links is a collection of Links, which are references from this span to a span
116 // in the same or different trace.
117 Links []*SpanLink `json:"links,omitempty"`
118 // dropped_links_count is the number of dropped links after the maximum size was
119 // enforced. If this value is 0, then no links were dropped.
120 DroppedLinks uint32 `json:"droppedLinksCount,omitempty"`
121 // An optional final status for this span. Semantically when Status isn't set, it means
122 // span's status code is unset, i.e. assume STATUS_CODE_UNSET (code = 0).
123 Status *Status `json:"status,omitempty"`
124}
125
126// MarshalJSON encodes s into OTLP formatted JSON.
127func (s Span) MarshalJSON() ([]byte, error) {
128 startT := s.StartTime.UnixNano()
129 if s.StartTime.IsZero() || startT < 0 {
130 startT = 0
131 }
132
133 endT := s.EndTime.UnixNano()
134 if s.EndTime.IsZero() || endT < 0 {
135 endT = 0
136 }
137
138 // Override non-empty default SpanID marshal and omitempty.
139 var parentSpanId string
140 if !s.ParentSpanID.IsEmpty() {
141 b := make([]byte, hex.EncodedLen(spanIDSize))
142 hex.Encode(b, s.ParentSpanID[:])
143 parentSpanId = string(b)
144 }
145
146 type Alias Span
147 return json.Marshal(struct {
148 Alias
149 ParentSpanID string `json:"parentSpanId,omitempty"`
150 StartTime uint64 `json:"startTimeUnixNano,omitempty"`
151 EndTime uint64 `json:"endTimeUnixNano,omitempty"`
152 }{
153 Alias: Alias(s),
154 ParentSpanID: parentSpanId,
155 StartTime: uint64(startT), // nolint:gosec // >0 checked above.
156 EndTime: uint64(endT), // nolint:gosec // >0 checked above.
157 })
158}
159
160// UnmarshalJSON decodes the OTLP formatted JSON contained in data into s.
161func (s *Span) UnmarshalJSON(data []byte) error {
162 decoder := json.NewDecoder(bytes.NewReader(data))
163
164 t, err := decoder.Token()
165 if err != nil {
166 return err
167 }
168 if t != json.Delim('{') {
169 return errors.New("invalid Span type")
170 }
171
172 for decoder.More() {
173 keyIface, err := decoder.Token()
174 if err != nil {
175 if errors.Is(err, io.EOF) {
176 // Empty.
177 return nil
178 }
179 return err
180 }
181
182 key, ok := keyIface.(string)
183 if !ok {
184 return fmt.Errorf("invalid Span field: %#v", keyIface)
185 }
186
187 switch key {
188 case "traceId", "trace_id":
189 err = decoder.Decode(&s.TraceID)
190 case "spanId", "span_id":
191 err = decoder.Decode(&s.SpanID)
192 case "traceState", "trace_state":
193 err = decoder.Decode(&s.TraceState)
194 case "parentSpanId", "parent_span_id":
195 err = decoder.Decode(&s.ParentSpanID)
196 case "flags":
197 err = decoder.Decode(&s.Flags)
198 case "name":
199 err = decoder.Decode(&s.Name)
200 case "kind":
201 err = decoder.Decode(&s.Kind)
202 case "startTimeUnixNano", "start_time_unix_nano":
203 var val protoUint64
204 err = decoder.Decode(&val)
205 v := int64(min(val.Uint64(), math.MaxInt64)) // nolint: gosec // Overflow checked.
206 s.StartTime = time.Unix(0, v)
207 case "endTimeUnixNano", "end_time_unix_nano":
208 var val protoUint64
209 err = decoder.Decode(&val)
210 v := int64(min(val.Uint64(), math.MaxInt64)) // nolint: gosec // Overflow checked.
211 s.EndTime = time.Unix(0, v)
212 case "attributes":
213 err = decoder.Decode(&s.Attrs)
214 case "droppedAttributesCount", "dropped_attributes_count":
215 err = decoder.Decode(&s.DroppedAttrs)
216 case "events":
217 err = decoder.Decode(&s.Events)
218 case "droppedEventsCount", "dropped_events_count":
219 err = decoder.Decode(&s.DroppedEvents)
220 case "links":
221 err = decoder.Decode(&s.Links)
222 case "droppedLinksCount", "dropped_links_count":
223 err = decoder.Decode(&s.DroppedLinks)
224 case "status":
225 err = decoder.Decode(&s.Status)
226 default:
227 // Skip unknown.
228 }
229
230 if err != nil {
231 return err
232 }
233 }
234 return nil
235}
236
237// SpanFlags represents constants used to interpret the
238// Span.flags field, which is protobuf 'fixed32' type and is to
239// be used as bit-fields. Each non-zero value defined in this enum is
240// a bit-mask. To extract the bit-field, for example, use an
241// expression like:
242//
243// (span.flags & SPAN_FLAGS_TRACE_FLAGS_MASK)
244//
245// See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
246//
247// Note that Span flags were introduced in version 1.1 of the
248// OpenTelemetry protocol. Older Span producers do not set this
249// field, consequently consumers should not rely on the absence of a
250// particular flag bit to indicate the presence of a particular feature.
251type SpanFlags int32
252
253const (
254 // Bits 0-7 are used for trace flags.
255 SpanFlagsTraceFlagsMask SpanFlags = 255
256 // Bits 8 and 9 are used to indicate that the parent span or link span is remote.
257 // Bit 8 (`HAS_IS_REMOTE`) indicates whether the value is known.
258 // Bit 9 (`IS_REMOTE`) indicates whether the span or link is remote.
259 SpanFlagsContextHasIsRemoteMask SpanFlags = 256
260 // SpanFlagsContextHasIsRemoteMask indicates the Span is remote.
261 SpanFlagsContextIsRemoteMask SpanFlags = 512
262)
263
264// SpanKind is the type of span. Can be used to specify additional relationships between spans
265// in addition to a parent/child relationship.
266type SpanKind int32
267
268const (
269 // Indicates that the span represents an internal operation within an application,
270 // as opposed to an operation happening at the boundaries. Default value.
271 SpanKindInternal SpanKind = 1
272 // Indicates that the span covers server-side handling of an RPC or other
273 // remote network request.
274 SpanKindServer SpanKind = 2
275 // Indicates that the span describes a request to some remote service.
276 SpanKindClient SpanKind = 3
277 // Indicates that the span describes a producer sending a message to a broker.
278 // Unlike CLIENT and SERVER, there is often no direct critical path latency relationship
279 // between producer and consumer spans. A PRODUCER span ends when the message was accepted
280 // by the broker while the logical processing of the message might span a much longer time.
281 SpanKindProducer SpanKind = 4
282 // Indicates that the span describes consumer receiving a message from a broker.
283 // Like the PRODUCER kind, there is often no direct critical path latency relationship
284 // between producer and consumer spans.
285 SpanKindConsumer SpanKind = 5
286)
287
288// Event is a time-stamped annotation of the span, consisting of user-supplied
289// text description and key-value pairs.
290type SpanEvent struct {
291 // time_unix_nano is the time the event occurred.
292 Time time.Time `json:"timeUnixNano,omitempty"`
293 // name of the event.
294 // This field is semantically required to be set to non-empty string.
295 Name string `json:"name,omitempty"`
296 // attributes is a collection of attribute key/value pairs on the event.
297 // Attribute keys MUST be unique (it is not allowed to have more than one
298 // attribute with the same key).
299 Attrs []Attr `json:"attributes,omitempty"`
300 // dropped_attributes_count is the number of dropped attributes. If the value is 0,
301 // then no attributes were dropped.
302 DroppedAttrs uint32 `json:"droppedAttributesCount,omitempty"`
303}
304
305// MarshalJSON encodes e into OTLP formatted JSON.
306func (e SpanEvent) MarshalJSON() ([]byte, error) {
307 t := e.Time.UnixNano()
308 if e.Time.IsZero() || t < 0 {
309 t = 0
310 }
311
312 type Alias SpanEvent
313 return json.Marshal(struct {
314 Alias
315 Time uint64 `json:"timeUnixNano,omitempty"`
316 }{
317 Alias: Alias(e),
318 Time: uint64(t), // nolint: gosec // >0 checked above
319 })
320}
321
322// UnmarshalJSON decodes the OTLP formatted JSON contained in data into se.
323func (se *SpanEvent) UnmarshalJSON(data []byte) error {
324 decoder := json.NewDecoder(bytes.NewReader(data))
325
326 t, err := decoder.Token()
327 if err != nil {
328 return err
329 }
330 if t != json.Delim('{') {
331 return errors.New("invalid SpanEvent type")
332 }
333
334 for decoder.More() {
335 keyIface, err := decoder.Token()
336 if err != nil {
337 if errors.Is(err, io.EOF) {
338 // Empty.
339 return nil
340 }
341 return err
342 }
343
344 key, ok := keyIface.(string)
345 if !ok {
346 return fmt.Errorf("invalid SpanEvent field: %#v", keyIface)
347 }
348
349 switch key {
350 case "timeUnixNano", "time_unix_nano":
351 var val protoUint64
352 err = decoder.Decode(&val)
353 v := int64(min(val.Uint64(), math.MaxInt64)) // nolint: gosec // Overflow checked.
354 se.Time = time.Unix(0, v)
355 case "name":
356 err = decoder.Decode(&se.Name)
357 case "attributes":
358 err = decoder.Decode(&se.Attrs)
359 case "droppedAttributesCount", "dropped_attributes_count":
360 err = decoder.Decode(&se.DroppedAttrs)
361 default:
362 // Skip unknown.
363 }
364
365 if err != nil {
366 return err
367 }
368 }
369 return nil
370}
371
372// A pointer from the current span to another span in the same trace or in a
373// different trace. For example, this can be used in batching operations,
374// where a single batch handler processes multiple requests from different
375// traces or when the handler receives a request from a different project.
376type SpanLink struct {
377 // A unique identifier of a trace that this linked span is part of. The ID is a
378 // 16-byte array.
379 TraceID TraceID `json:"traceId,omitempty"`
380 // A unique identifier for the linked span. The ID is an 8-byte array.
381 SpanID SpanID `json:"spanId,omitempty"`
382 // The trace_state associated with the link.
383 TraceState string `json:"traceState,omitempty"`
384 // attributes is a collection of attribute key/value pairs on the link.
385 // Attribute keys MUST be unique (it is not allowed to have more than one
386 // attribute with the same key).
387 Attrs []Attr `json:"attributes,omitempty"`
388 // dropped_attributes_count is the number of dropped attributes. If the value is 0,
389 // then no attributes were dropped.
390 DroppedAttrs uint32 `json:"droppedAttributesCount,omitempty"`
391 // Flags, a bit field.
392 //
393 // Bits 0-7 (8 least significant bits) are the trace flags as defined in W3C Trace
394 // Context specification. To read the 8-bit W3C trace flag, use
395 // `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
396 //
397 // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
398 //
399 // Bits 8 and 9 represent the 3 states of whether the link is remote.
400 // The states are (unknown, is not remote, is remote).
401 // To read whether the value is known, use `(flags & SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK) != 0`.
402 // To read whether the link is remote, use `(flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
403 //
404 // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero.
405 // When creating new spans, bits 10-31 (most-significant 22-bits) MUST be zero.
406 //
407 // [Optional].
408 Flags uint32 `json:"flags,omitempty"`
409}
410
411// UnmarshalJSON decodes the OTLP formatted JSON contained in data into sl.
412func (sl *SpanLink) UnmarshalJSON(data []byte) error {
413 decoder := json.NewDecoder(bytes.NewReader(data))
414
415 t, err := decoder.Token()
416 if err != nil {
417 return err
418 }
419 if t != json.Delim('{') {
420 return errors.New("invalid SpanLink type")
421 }
422
423 for decoder.More() {
424 keyIface, err := decoder.Token()
425 if err != nil {
426 if errors.Is(err, io.EOF) {
427 // Empty.
428 return nil
429 }
430 return err
431 }
432
433 key, ok := keyIface.(string)
434 if !ok {
435 return fmt.Errorf("invalid SpanLink field: %#v", keyIface)
436 }
437
438 switch key {
439 case "traceId", "trace_id":
440 err = decoder.Decode(&sl.TraceID)
441 case "spanId", "span_id":
442 err = decoder.Decode(&sl.SpanID)
443 case "traceState", "trace_state":
444 err = decoder.Decode(&sl.TraceState)
445 case "attributes":
446 err = decoder.Decode(&sl.Attrs)
447 case "droppedAttributesCount", "dropped_attributes_count":
448 err = decoder.Decode(&sl.DroppedAttrs)
449 case "flags":
450 err = decoder.Decode(&sl.Flags)
451 default:
452 // Skip unknown.
453 }
454
455 if err != nil {
456 return err
457 }
458 }
459 return nil
460}