| 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 |
} |