Debian Codegraph @

trace/span.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 "context"
8
9 "go.opentelemetry.io/otel/attribute"
10 "go.opentelemetry.io/otel/codes"
11 "go.opentelemetry.io/otel/trace/embedded"
12 )
13
14 // Span is the individual component of a trace. It represents a single named
15 // and timed operation of a workflow that is traced. A Tracer is used to
16 // create a Span and it is then up to the operation the Span represents to
17 // properly end the Span when the operation itself ends.
18 //
19 // Warning: Methods may be added to this interface in minor releases. See
20 // package documentation on API implementation for information on how to set
21 // default behavior for unimplemented methods.
22 type Span interface {
23 // Users of the interface can ignore this. This embedded type is only used
24 // by implementations of this interface. See the "API Implementations"
25 // section of the package documentation for more information.
26 embedded.Span
27
28 // End completes the Span. The Span is considered complete and ready to be
29 // delivered through the rest of the telemetry pipeline after this method
30 // is called. Therefore, updates to the Span are not allowed after this
31 // method has been called.
32 End(options ...SpanEndOption)
33
34 // AddEvent adds an event with the provided name and options.
35 AddEvent(name string, options ...EventOption)
36
37 // AddLink adds a link.
38 // Adding links at span creation using WithLinks is preferred to calling AddLink
39 // later, for contexts that are available during span creation, because head
40 // sampling decisions can only consider information present during span creation.
41 AddLink(link Link)
42
43 // IsRecording returns the recording state of the Span. It will return
44 // true if the Span is active and events can be recorded.
45 IsRecording() bool
46
47 // RecordError will record err as an exception span event for this span. An
48 // additional call to SetStatus is required if the Status of the Span should
49 // be set to Error, as this method does not change the Span status. If this
50 // span is not being recorded or err is nil then this method does nothing.
51 RecordError(err error, options ...EventOption)
52
53 // SpanContext returns the SpanContext of the Span. The returned SpanContext
54 // is usable even after the End method has been called for the Span.
55 SpanContext() SpanContext
56
57 // SetStatus sets the status of the Span in the form of a code and a
58 // description, provided the status hasn't already been set to a higher
59 // value before (OK > Error > Unset). The description is only included in a
60 // status when the code is for an error.
61 SetStatus(code codes.Code, description string)
62
63 // SetName sets the Span name.
64 SetName(name string)
65
66 // SetAttributes sets kv as attributes of the Span. If a key from kv
67 // already exists for an attribute of the Span it will be overwritten with
68 // the value contained in kv.
69 //
70 // Note that adding attributes at span creation using [WithAttributes] is preferred
71 // to calling SetAttribute later, as samplers can only consider information
72 // already present during span creation.
73 SetAttributes(kv ...attribute.KeyValue)
74
75 // TracerProvider returns a TracerProvider that can be used to generate
76 // additional Spans on the same telemetry pipeline as the current Span.
77 TracerProvider() TracerProvider
78 }
79
80 // Link is the relationship between two Spans. The relationship can be within
81 // the same Trace or across different Traces.
82 //
83 // For example, a Link is used in the following situations:
84 //
85 // 1. Batch Processing: A batch of operations may contain operations
86 // associated with one or more traces/spans. Since there can only be one
87 // parent SpanContext, a Link is used to keep reference to the
88 // SpanContext of all operations in the batch.
89 // 2. Public Endpoint: A SpanContext for an in incoming client request on a
90 // public endpoint should be considered untrusted. In such a case, a new
91 // trace with its own identity and sampling decision needs to be created,
92 // but this new trace needs to be related to the original trace in some
93 // form. A Link is used to keep reference to the original SpanContext and
94 // track the relationship.
95 type Link struct {
96 // SpanContext of the linked Span.
97 SpanContext SpanContext
98
99 // Attributes describe the aspects of the link.
100 Attributes []attribute.KeyValue
101 }
102
103 // LinkFromContext returns a link encapsulating the SpanContext in the provided
104 // ctx.
105 func LinkFromContext(ctx context.Context, attrs ...attribute.KeyValue) Link {
106 return Link{
107 SpanContext: SpanContextFromContext(ctx),
108 Attributes: attrs,
109 }
110 }
111
112 // SpanKind is the role a Span plays in a Trace.
113 type SpanKind int
114
115 // As a convenience, these match the proto definition, see
116 // https://github.com/open-telemetry/opentelemetry-proto/blob/30d237e1ff3ab7aa50e0922b5bebdd93505090af/opentelemetry/proto/trace/v1/trace.proto#L101-L129
117 //
118 // The unspecified value is not a valid `SpanKind`. Use `ValidateSpanKind()`
119 // to coerce a span kind to a valid value.
120 const (
121 // SpanKindUnspecified is an unspecified SpanKind and is not a valid
122 // SpanKind. SpanKindUnspecified should be replaced with SpanKindInternal
123 // if it is received.
124 SpanKindUnspecified SpanKind = 0
125 // SpanKindInternal is a SpanKind for a Span that represents an internal
126 // operation within an application.
127 SpanKindInternal SpanKind = 1
128 // SpanKindServer is a SpanKind for a Span that represents the operation
129 // of handling a request from a client.
130 SpanKindServer SpanKind = 2
131 // SpanKindClient is a SpanKind for a Span that represents the operation
132 // of client making a request to a server.
133 SpanKindClient SpanKind = 3
134 // SpanKindProducer is a SpanKind for a Span that represents the operation
135 // of a producer sending a message to a message broker. Unlike
136 // SpanKindClient and SpanKindServer, there is often no direct
137 // relationship between this kind of Span and a SpanKindConsumer kind. A
138 // SpanKindProducer Span will end once the message is accepted by the
139 // message broker which might not overlap with the processing of that
140 // message.
141 SpanKindProducer SpanKind = 4
142 // SpanKindConsumer is a SpanKind for a Span that represents the operation
143 // of a consumer receiving a message from a message broker. Like
144 // SpanKindProducer Spans, there is often no direct relationship between
145 // this Span and the Span that produced the message.
146 SpanKindConsumer SpanKind = 5
147 )
148
149 // ValidateSpanKind returns a valid span kind value. This will coerce
150 // invalid values into the default value, SpanKindInternal.
151 func ValidateSpanKind(spanKind SpanKind) SpanKind {
152 switch spanKind {
153 case SpanKindInternal,
154 SpanKindServer,
155 SpanKindClient,
156 SpanKindProducer,
157 SpanKindConsumer:
158 // valid
159 return spanKind
160 default:
161 return SpanKindInternal
162 }
163 }
164
165 // String returns the specified name of the SpanKind in lower-case.
166 func (sk SpanKind) String() string {
167 switch sk {
168 case SpanKindInternal:
169 return "internal"
170 case SpanKindServer:
171 return "server"
172 case SpanKindClient:
173 return "client"
174 case SpanKindProducer:
175 return "producer"
176 case SpanKindConsumer:
177 return "consumer"
178 default:
179 return "unspecified"
180 }
181 }