1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3 4 /*
5 Package trace provides an implementation of the tracing part of the
6 OpenTelemetry API.
7 8 To participate in distributed traces a Span needs to be created for the
9 operation being performed as part of a traced workflow. In its simplest form:
10 11 var tracer trace.Tracer
12 13 func init() {
14 tracer = otel.Tracer("instrumentation/package/name")
15 }
16 17 func operation(ctx context.Context) {
18 var span trace.Span
19 ctx, span = tracer.Start(ctx, "operation")
20 defer span.End()
21 // ...
22 }
23 24 A Tracer is unique to the instrumentation and is used to create Spans.
25 Instrumentation should be designed to accept a TracerProvider from which it
26 can create its own unique Tracer. Alternatively, the registered global
27 TracerProvider from the go.opentelemetry.io/otel package can be used as
28 a default.
29 30 const (
31 name = "instrumentation/package/name"
32 version = "0.1.0"
33 )
34 35 type Instrumentation struct {
36 tracer trace.Tracer
37 }
38 39 func NewInstrumentation(tp trace.TracerProvider) *Instrumentation {
40 if tp == nil {
41 tp = otel.TracerProvider()
42 }
43 return &Instrumentation{
44 tracer: tp.Tracer(name, trace.WithInstrumentationVersion(version)),
45 }
46 }
47 48 func operation(ctx context.Context, inst *Instrumentation) {
49 var span trace.Span
50 ctx, span = inst.tracer.Start(ctx, "operation")
51 defer span.End()
52 // ...
53 }
54 55 # API Implementations
56 57 This package does not conform to the standard Go versioning policy; all of its
58 interfaces may have methods added to them without a package major version bump.
59 This non-standard API evolution could surprise an uninformed implementation
60 author. They could unknowingly build their implementation in a way that would
61 result in a runtime panic for their users that update to the new API.
62 63 The API is designed to help inform an instrumentation author about this
64 non-standard API evolution. It requires them to choose a default behavior for
65 unimplemented interface methods. There are three behavior choices they can
66 make:
67 68 - Compilation failure
69 - Panic
70 - Default to another implementation
71 72 All interfaces in this API embed a corresponding interface from
73 [go.opentelemetry.io/otel/trace/embedded]. If an author wants the default
74 behavior of their implementations to be a compilation failure, signaling to
75 their users they need to update to the latest version of that implementation,
76 they need to embed the corresponding interface from
77 [go.opentelemetry.io/otel/trace/embedded] in their implementation. For
78 example,
79 80 import "go.opentelemetry.io/otel/trace/embedded"
81 82 type TracerProvider struct {
83 embedded.TracerProvider
84 // ...
85 }
86 87 If an author wants the default behavior of their implementations to panic, they
88 can embed the API interface directly.
89 90 import "go.opentelemetry.io/otel/trace"
91 92 type TracerProvider struct {
93 trace.TracerProvider
94 // ...
95 }
96 97 This option is not recommended. It will lead to publishing packages that
98 contain runtime panics when users update to newer versions of
99 [go.opentelemetry.io/otel/trace], which may be done with a transitive
100 dependency.
101 102 Finally, an author can embed another implementation in theirs. The embedded
103 implementation will be used for methods not defined by the author. For example,
104 an author who wants to default to silently dropping the call can use
105 [go.opentelemetry.io/otel/trace/noop]:
106 107 import "go.opentelemetry.io/otel/trace/noop"
108 109 type TracerProvider struct {
110 noop.TracerProvider
111 // ...
112 }
113 114 It is strongly recommended that authors only embed
115 [go.opentelemetry.io/otel/trace/noop] if they choose this default behavior.
116 That implementation is the only one OpenTelemetry authors can guarantee will
117 fully implement all the API interfaces when a user updates their API.
118 */
119 package trace // import "go.opentelemetry.io/otel/trace"
120