Debian Codegraph @

exporters/stdout/stdouttrace/internal/observ/instrumentation.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 // Package observ provides experimental observability instrumentation
5 // for the stdout trace exporter.
6 package observ // import "go.opentelemetry.io/otel/exporters/stdout/stdouttrace/internal/observ"
7
8 import (
9 "context"
10 "errors"
11 "fmt"
12 "sync"
13 "time"
14
15 "go.opentelemetry.io/otel"
16 "go.opentelemetry.io/otel/attribute"
17 "go.opentelemetry.io/otel/exporters/stdout/stdouttrace/internal"
18 "go.opentelemetry.io/otel/exporters/stdout/stdouttrace/internal/x"
19 "go.opentelemetry.io/otel/metric"
20 semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
21 "go.opentelemetry.io/otel/semconv/v1.40.0/otelconv"
22 )
23
24 const (
25 // ComponentType uniquely identifies the OpenTelemetry Exporter component
26 // being instrumented.
27 //
28 // The STDOUT trace exporter is not a standardized OTel component type, so
29 // it uses the Go package prefixed type name to ensure uniqueness and
30 // identity.
31 ComponentType = "go.opentelemetry.io/otel/exporters/stdout/stdouttrace.Exporter"
32
33 // ScopeName is the unique name of the meter used for instrumentation.
34 ScopeName = "go.opentelemetry.io/otel/exporters/stdout/stdouttrace/internal/observ"
35
36 // SchemaURL is the schema URL of the metrics produced by this
37 // instrumentation.
38 SchemaURL = semconv.SchemaURL
39
40 // Version is the current version of this instrumentation.
41 //
42 // This matches the version of the exporter.
43 Version = internal.Version
44 )
45
46 var (
47 measureAttrsPool = &sync.Pool{
48 New: func() any {
49 // "component.name" + "component.type" + "error.type"
50 const n = 1 + 1 + 1
51 s := make([]attribute.KeyValue, 0, n)
52 // Return a pointer to a slice instead of a slice itself
53 // to avoid allocations on every call.
54 return &s
55 },
56 }
57
58 addOptPool = &sync.Pool{
59 New: func() any {
60 const n = 1 // WithAttributeSet
61 o := make([]metric.AddOption, 0, n)
62 return &o
63 },
64 }
65
66 recordOptPool = &sync.Pool{
67 New: func() any {
68 const n = 1 // WithAttributeSet
69 o := make([]metric.RecordOption, 0, n)
70 return &o
71 },
72 }
73 )
74
75 func get[T any](p *sync.Pool) *[]T { return p.Get().(*[]T) }
76
77 func put[T any](p *sync.Pool, s *[]T) {
78 *s = (*s)[:0] // Reset.
79 p.Put(s)
80 }
81
82 func ComponentName(id int64) string {
83 return fmt.Sprintf("%s/%d", ComponentType, id)
84 }
85
86 // Instrumentation is experimental instrumentation for the exporter.
87 type Instrumentation struct {
88 inflightSpans metric.Int64UpDownCounter
89 exportedSpans metric.Int64Counter
90 opDuration metric.Float64Histogram
91
92 attrs []attribute.KeyValue
93 setOpt metric.MeasurementOption
94 }
95
96 // NewInstrumentation returns instrumentation for a STDOUT trace exporter with
97 // the provided ID using the global MeterProvider.
98 //
99 // If the experimental observability is disabled, nil is returned.
100 func NewInstrumentation(id int64) (*Instrumentation, error) {
101 if !x.Observability.Enabled() {
102 return nil, nil
103 }
104
105 i := &Instrumentation{
106 attrs: []attribute.KeyValue{
107 semconv.OTelComponentName(ComponentName(id)),
108 semconv.OTelComponentTypeKey.String(ComponentType),
109 },
110 }
111
112 s := attribute.NewSet(i.attrs...)
113 i.setOpt = metric.WithAttributeSet(s)
114
115 mp := otel.GetMeterProvider()
116 m := mp.Meter(
117 ScopeName,
118 metric.WithInstrumentationVersion(Version),
119 metric.WithSchemaURL(SchemaURL),
120 )
121
122 var err error
123
124 inflightSpans, e := otelconv.NewSDKExporterSpanInflight(m)
125 if e != nil {
126 e = fmt.Errorf("failed to create span inflight metric: %w", e)
127 err = errors.Join(err, e)
128 }
129 i.inflightSpans = inflightSpans.Inst()
130
131 exportedSpans, e := otelconv.NewSDKExporterSpanExported(m)
132 if e != nil {
133 e = fmt.Errorf("failed to create span exported metric: %w", e)
134 err = errors.Join(err, e)
135 }
136 i.exportedSpans = exportedSpans.Inst()
137
138 opDuration, e := otelconv.NewSDKExporterOperationDuration(m)
139 if e != nil {
140 e = fmt.Errorf("failed to create operation duration metric: %w", e)
141 err = errors.Join(err, e)
142 }
143 i.opDuration = opDuration.Inst()
144
145 return i, err
146 }
147
148 // ExportSpans instruments the ExportSpans method of the exporter. It returns a
149 // function that needs to be deferred so it is called when the method returns.
150 func (i *Instrumentation) ExportSpans(ctx context.Context, nSpans int) ExportOp {
151 start := time.Now()
152
153 if i.inflightSpans.Enabled(ctx) {
154 addOpt := get[metric.AddOption](addOptPool)
155 defer put(addOptPool, addOpt)
156 *addOpt = append(*addOpt, i.setOpt)
157 i.inflightSpans.Add(ctx, int64(nSpans), *addOpt...)
158 }
159
160 return ExportOp{
161 ctx: ctx,
162 start: start,
163 nSpans: int64(nSpans),
164 inst: i,
165 }
166 }
167
168 // ExportOp is an in-progress ExportSpans operation.
169 type ExportOp struct {
170 ctx context.Context
171 start time.Time
172 nSpans int64
173 inst *Instrumentation
174 }
175
176 // End ends the ExportSpans operation, recording its success and duration.
177 //
178 // The success parameter indicates how many spans were successfully exported.
179 // The err parameter indicates whether the operation failed. If err is not nil,
180 // the number of failed spans (nSpans - success) is also recorded.
181 func (e ExportOp) End(success int64, err error) {
182 inflightSpansEnable := e.inst.inflightSpans.Enabled(e.ctx)
183 exportedSpansEnable := e.inst.exportedSpans.Enabled(e.ctx)
184 opDurationEnable := e.inst.opDuration.Enabled(e.ctx)
185
186 if !inflightSpansEnable && !exportedSpansEnable && !opDurationEnable {
187 return
188 }
189
190 addOpt := get[metric.AddOption](addOptPool)
191 defer put(addOptPool, addOpt)
192 *addOpt = append(*addOpt, e.inst.setOpt)
193
194 if inflightSpansEnable {
195 e.inst.inflightSpans.Add(e.ctx, -e.nSpans, *addOpt...)
196 }
197
198 // Record the success and duration of the operation.
199 //
200 // Do not exclude 0 values, as they are valid and indicate no spans
201 // were exported which is meaningful for certain aggregations.
202 if exportedSpansEnable {
203 e.inst.exportedSpans.Add(e.ctx, success, *addOpt...)
204 }
205
206 mOpt := e.inst.setOpt
207 if err != nil && exportedSpansEnable {
208 attrs := get[attribute.KeyValue](measureAttrsPool)
209 defer put(measureAttrsPool, attrs)
210 *attrs = append(*attrs, e.inst.attrs...)
211 *attrs = append(*attrs, semconv.ErrorType(err))
212
213 // Do not inefficiently make a copy of attrs by using
214 // WithAttributes instead of WithAttributeSet.
215 set := attribute.NewSet(*attrs...)
216 mOpt = metric.WithAttributeSet(set)
217
218 // Reset addOpt with new attribute set.
219 *addOpt = append((*addOpt)[:0], mOpt)
220
221 e.inst.exportedSpans.Add(e.ctx, e.nSpans-success, *addOpt...)
222 }
223
224 if opDurationEnable {
225 recordOpt := get[metric.RecordOption](recordOptPool)
226 defer put(recordOptPool, recordOpt)
227 *recordOpt = append(*recordOpt, mOpt)
228 e.inst.opDuration.Record(e.ctx, time.Since(e.start).Seconds(), *recordOpt...)
229 }
230 }