Debian Codegraph @

exporters/otlp/otlptrace/otlptracehttp/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 for the
5 // otlptracehttp exporter.
6 package observ // import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp/internal/observ"
7
8 import (
9 "context"
10 "errors"
11 "fmt"
12 "net"
13 "net/http"
14 "net/netip"
15 "strconv"
16 "strings"
17 "sync"
18 "time"
19
20 "go.opentelemetry.io/otel"
21 "go.opentelemetry.io/otel/attribute"
22 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp/internal"
23 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp/internal/x"
24 "go.opentelemetry.io/otel/internal/global"
25 "go.opentelemetry.io/otel/metric"
26 semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
27 "go.opentelemetry.io/otel/semconv/v1.40.0/otelconv"
28 )
29
30 const (
31 // ScopeName is the unique name of the meter used for instrumentation.
32 ScopeName = "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp/internal/observ"
33
34 // SchemaURL is the schema URL of the metrics produced by this
35 // instrumentation.
36 SchemaURL = semconv.SchemaURL
37
38 // Version is the current version of this instrumentation.
39 //
40 // This matches the version of the exporter.
41 Version = internal.Version
42 )
43
44 var (
45 measureAttrsPool = &sync.Pool{
46 New: func() any {
47 const n = 1 + // component.name
48 1 + // component.type
49 1 + // server.addr
50 1 + // server.port
51 1 + // error.type
52 1 // http.response.status_code
53 s := make([]attribute.KeyValue, 0, n)
54 // Return a pointer to a slice instead of a slice itself
55 // to avoid allocations on every call.
56 return &s
57 },
58 }
59
60 addOptPool = &sync.Pool{
61 New: func() any {
62 const n = 1 // WithAttributeSet
63 o := make([]metric.AddOption, 0, n)
64 return &o
65 },
66 }
67
68 recordOptPool = &sync.Pool{
69 New: func() any {
70 const n = 1 // WithAttributeSet
71 o := make([]metric.RecordOption, 0, n)
72 return &o
73 },
74 }
75 )
76
77 func get[T any](p *sync.Pool) *[]T { return p.Get().(*[]T) }
78
79 func put[T any](p *sync.Pool, s *[]T) {
80 *s = (*s)[:0] // Reset.
81 p.Put(s)
82 }
83
84 // ComponentName returns the component name for the exporter with the
85 // provided ID.
86 func ComponentName(id int64) string {
87 t := semconv.OTelComponentTypeOtlpHTTPSpanExporter.Value.AsString()
88 return fmt.Sprintf("%s/%d", t, id)
89 }
90
91 // Instrumentation is experimental instrumentation for the exporter.
92 type Instrumentation struct {
93 inflightSpans metric.Int64UpDownCounter
94 exportedSpans metric.Int64Counter
95 opDuration metric.Float64Histogram
96
97 attrs []attribute.KeyValue
98 addOpt metric.AddOption
99 recOpt metric.RecordOption
100 }
101
102 // NewInstrumentation returns instrumentation for an OTLP over HTTP trace
103 // exporter with the provided ID and endpoint. It uses the global
104 // MeterProvider to create the instrumentation.
105 //
106 // The id should be the unique exporter instance ID. It is used
107 // to set the "component.name" attribute.
108 //
109 // The endpoint is the HTTP endpoint the exporter is exporting to.
110 //
111 // If the experimental observability is disabled, nil is returned.
112 func NewInstrumentation(id int64, endpoint string) (*Instrumentation, error) {
113 if !x.Observability.Enabled() {
114 return nil, nil
115 }
116
117 attrs := BaseAttrs(id, endpoint)
118 i := &Instrumentation{
119 attrs: attrs,
120 addOpt: metric.WithAttributeSet(attribute.NewSet(attrs...)),
121
122 // Do not modify attrs (NewSet sorts in-place), make a new slice.
123 recOpt: metric.WithAttributeSet(attribute.NewSet(append(
124 // Default to OK status code (200).
125 []attribute.KeyValue{semconv.HTTPResponseStatusCode(http.StatusOK)},
126 attrs...,
127 )...)),
128 }
129
130 mp := otel.GetMeterProvider()
131 m := mp.Meter(
132 ScopeName,
133 metric.WithInstrumentationVersion(Version),
134 metric.WithSchemaURL(SchemaURL),
135 )
136
137 var err error
138
139 inflightSpans, e := otelconv.NewSDKExporterSpanInflight(m)
140 if e != nil {
141 e = fmt.Errorf("failed to create span inflight metric: %w", e)
142 err = errors.Join(err, e)
143 }
144 i.inflightSpans = inflightSpans.Inst()
145
146 exportedSpans, e := otelconv.NewSDKExporterSpanExported(m)
147 if e != nil {
148 e = fmt.Errorf("failed to create span exported metric: %w", e)
149 err = errors.Join(err, e)
150 }
151 i.exportedSpans = exportedSpans.Inst()
152
153 opDuration, e := otelconv.NewSDKExporterOperationDuration(m)
154 if e != nil {
155 e = fmt.Errorf("failed to create operation duration metric: %w", e)
156 err = errors.Join(err, e)
157 }
158 i.opDuration = opDuration.Inst()
159
160 return i, err
161 }
162
163 // BaseAttrs returns the base attributes for the exporter with the provided ID
164 // and endpoint.
165 //
166 // The id should be the unique exporter instance ID. It is used
167 // to set the "component.name" attribute.
168 //
169 // The endpoint is the HTTP endpoint the exporter is exporting to. It should be
170 // in the format "host:port" or a full URL.
171 func BaseAttrs(id int64, endpoint string) []attribute.KeyValue {
172 host, port, err := parseEndpoint(endpoint)
173 if err != nil || (host == "" && port < 0) {
174 if err != nil {
175 global.Debug("failed to parse endpoint", "endpoint", endpoint, "error", err)
176 }
177 return []attribute.KeyValue{
178 semconv.OTelComponentName(ComponentName(id)),
179 semconv.OTelComponentTypeOtlpHTTPSpanExporter,
180 }
181 }
182
183 // Do not use append so the slice is exactly allocated.
184
185 if port < 0 {
186 return []attribute.KeyValue{
187 semconv.OTelComponentName(ComponentName(id)),
188 semconv.OTelComponentTypeOtlpHTTPSpanExporter,
189 semconv.ServerAddress(host),
190 }
191 }
192
193 if host == "" {
194 return []attribute.KeyValue{
195 semconv.OTelComponentName(ComponentName(id)),
196 semconv.OTelComponentTypeOtlpHTTPSpanExporter,
197 semconv.ServerPort(port),
198 }
199 }
200
201 return []attribute.KeyValue{
202 semconv.OTelComponentName(ComponentName(id)),
203 semconv.OTelComponentTypeOtlpHTTPSpanExporter,
204 semconv.ServerAddress(host),
205 semconv.ServerPort(port),
206 }
207 }
208
209 // parseEndpoint parses the host and port from endpoint that has the form
210 // "host[:port]", or it returns an error if the endpoint is not parsable.
211 //
212 // If no port is specified, -1 is returned.
213 //
214 // If no host is specified, an empty string is returned.
215 func parseEndpoint(endpoint string) (string, int, error) {
216 // First check if the endpoint is just an IP address.
217 if ip := parseIP(endpoint); ip != "" {
218 return ip, -1, nil
219 }
220
221 // If there's no colon, there is no port (IPv6 with no port checked above).
222 if !strings.Contains(endpoint, ":") {
223 return endpoint, -1, nil
224 }
225
226 // Otherwise, parse as host:port.
227 host, portStr, err := net.SplitHostPort(endpoint)
228 if err != nil {
229 return "", -1, fmt.Errorf("invalid host:port %q: %w", endpoint, err)
230 }
231
232 const base, bitSize = 10, 16
233 port16, err := strconv.ParseUint(portStr, base, bitSize)
234 if err != nil {
235 return "", -1, fmt.Errorf("invalid port %q: %w", portStr, err)
236 }
237 port := int(port16) // port is guaranteed to be in the range [0, 65535].
238
239 return host, port, nil
240 }
241
242 // parseIP attempts to parse the entire endpoint as an IP address.
243 // It returns the normalized string form of the IP if successful,
244 // or an empty string if parsing fails.
245 func parseIP(ip string) string {
246 // Strip leading and trailing brackets for IPv6 addresses.
247 if len(ip) >= 2 && ip[0] == '[' && ip[len(ip)-1] == ']' {
248 ip = ip[1 : len(ip)-1]
249 }
250 addr, err := netip.ParseAddr(ip)
251 if err != nil {
252 return ""
253 }
254 // Return the normalized string form of the IP.
255 return addr.String()
256 }
257
258 // ExportSpans instruments the UploadTraces method of the client. It returns an
259 // [ExportOp] that must have its [ExportOp.End] method called when the
260 // operation end.
261 func (i *Instrumentation) ExportSpans(ctx context.Context, nSpans int) ExportOp {
262 start := time.Now()
263
264 if i.inflightSpans.Enabled(ctx) {
265 addOpt := get[metric.AddOption](addOptPool)
266 defer put(addOptPool, addOpt)
267 *addOpt = append(*addOpt, i.addOpt)
268 i.inflightSpans.Add(ctx, int64(nSpans), *addOpt...)
269 }
270
271 return ExportOp{
272 ctx: ctx,
273 start: start,
274 nSpans: int64(nSpans),
275 inst: i,
276 }
277 }
278
279 // ExportOp tracks the export operation being observed by
280 // [Instrumentation.ExportSpans].
281 type ExportOp struct {
282 ctx context.Context
283 start time.Time
284 nSpans int64
285
286 inst *Instrumentation
287 }
288
289 // End completes the observation of the operation being observed by a call to
290 // [Instrumentation.ExportSpans].
291 //
292 // Any error that is encountered is provided as err.
293 // The HTTP status code from the response is provided as status.
294 //
295 // If err is not nil, all spans will be recorded as failures unless error is of
296 // type [internal.PartialSuccess]. In the case of a PartialSuccess, the number
297 // of successfully exported spans will be determined by inspecting the
298 // RejectedItems field of the PartialSuccess.
299 func (e ExportOp) End(err error, status int) {
300 addOpt := get[metric.AddOption](addOptPool)
301 defer put(addOptPool, addOpt)
302 *addOpt = append(*addOpt, e.inst.addOpt)
303
304 if e.inst.inflightSpans.Enabled(e.ctx) {
305 e.inst.inflightSpans.Add(e.ctx, -e.nSpans, *addOpt...)
306 }
307
308 success := successful(e.nSpans, err)
309 // Record successfully exported spans, even if the value is 0 which are
310 // meaningful to distribution aggregations.
311 if e.inst.exportedSpans.Enabled(e.ctx) {
312 e.inst.exportedSpans.Add(e.ctx, success, *addOpt...)
313 }
314
315 if err != nil && e.inst.exportedSpans.Enabled(e.ctx) {
316 attrs := get[attribute.KeyValue](measureAttrsPool)
317 defer put(measureAttrsPool, attrs)
318 *attrs = append(*attrs, e.inst.attrs...)
319 *attrs = append(*attrs, semconv.ErrorType(err))
320
321 // Do not inefficiently make a copy of attrs by using
322 // WithAttributes instead of WithAttributeSet.
323 o := metric.WithAttributeSet(attribute.NewSet(*attrs...))
324 // Reset addOpt with new attribute set.
325 *addOpt = append((*addOpt)[:0], o)
326
327 e.inst.exportedSpans.Add(e.ctx, e.nSpans-success, *addOpt...)
328 }
329
330 if e.inst.opDuration.Enabled(e.ctx) {
331 recOpt := get[metric.RecordOption](recordOptPool)
332 defer put(recordOptPool, recOpt)
333 *recOpt = append(*recOpt, e.inst.recordOption(err, status))
334
335 d := time.Since(e.start).Seconds()
336 e.inst.opDuration.Record(e.ctx, d, *recOpt...)
337 }
338 }
339
340 // recordOption returns a RecordOption with attributes representing the
341 // outcome of the operation being recorded.
342 //
343 // If err is nil and status is 200, the default recOpt of the
344 // Instrumentation is returned.
345 //
346 // Otherwise, a new RecordOption is returned with the base attributes of the
347 // Instrumentation plus the http.response.status_code attribute set to the
348 // provided status, and if err is not nil, the error.type attribute set
349 // to the type of the error.
350 func (i *Instrumentation) recordOption(err error, status int) metric.RecordOption {
351 if err == nil && status == http.StatusOK {
352 return i.recOpt
353 }
354
355 attrs := get[attribute.KeyValue](measureAttrsPool)
356 defer put(measureAttrsPool, attrs)
357 *attrs = append(*attrs, i.attrs...)
358
359 *attrs = append(*attrs, semconv.HTTPResponseStatusCode(status))
360 if err != nil {
361 *attrs = append(*attrs, semconv.ErrorType(err))
362 }
363
364 // Do not inefficiently make a copy of attrs by using WithAttributes
365 // instead of WithAttributeSet.
366 return metric.WithAttributeSet(attribute.NewSet(*attrs...))
367 }
368
369 // successful returns the number of successfully exported spans out of the n
370 // that were exported based on the provided error.
371 //
372 // If err is nil, n is returned. All spans were successfully exported.
373 //
374 // If err is not nil and not an [internal.PartialSuccess] error, 0 is returned.
375 // It is assumed all spans failed to be exported.
376 //
377 // If err is an [internal.PartialSuccess] error, the number of successfully
378 // exported spans is computed by subtracting the RejectedItems field from n. If
379 // RejectedItems is negative, n is returned. If RejectedItems is greater than
380 // n, 0 is returned.
381 func successful(n int64, err error) int64 {
382 if err == nil {
383 return n // All spans successfully exported.
384 }
385 // Split rejection calculation so successful is inlinable.
386 return n - rejected(n, err)
387 }
388
389 var errPartialPool = &sync.Pool{
390 New: func() any { return new(internal.PartialSuccess) },
391 }
392
393 // rejected returns how many out of the n spans exporter were rejected based on
394 // the provided non-nil err.
395 func rejected(n int64, err error) int64 {
396 ps := errPartialPool.Get().(*internal.PartialSuccess)
397 defer errPartialPool.Put(ps)
398 // Check for partial success.
399 if errors.As(err, ps) {
400 // Bound RejectedItems to [0, n]. This should not be needed,
401 // but be defensive as this is from an external source.
402 return min(max(ps.RejectedItems, 0), n)
403 }
404 return n // All spans rejected.
405 }