Debian Codegraph @

exporters/otlp/otlplog/otlploggrpc/internal/observ/instrumentation.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 // Package observ provides observability metrics for OTLP log exporters.
5 // This is an experimental feature controlled by the x.Observability feature flag.
6 package observ // import "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc/internal/observ"
7
8 import (
9 "context"
10 "errors"
11 "fmt"
12 "sync"
13 "time"
14
15 "google.golang.org/grpc/codes"
16 "google.golang.org/grpc/status"
17
18 "go.opentelemetry.io/otel"
19 "go.opentelemetry.io/otel/attribute"
20 "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc/internal"
21 "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc/internal/x"
22 "go.opentelemetry.io/otel/internal/global"
23 "go.opentelemetry.io/otel/metric"
24 semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
25 "go.opentelemetry.io/otel/semconv/v1.40.0/otelconv"
26 )
27
28 const (
29 // ScopeName is the unique name of the meter used for instrumentation.
30 ScopeName = "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc/internal/observ"
31
32 // Version is the current version of this instrumentation.
33 //
34 // This matches the version of the exporter.
35 Version = internal.Version
36 )
37
38 var (
39 attrsPool = &sync.Pool{
40 New: func() any {
41 const n = 1 + // component.name
42 1 + // component.type
43 1 + // server.addr
44 1 + // server.port
45 1 + // error.type
46 1 // rpc.grpc.status_code
47 s := make([]attribute.KeyValue, 0, n)
48 // Return a pointer to a slice instead of a slice itself
49 // to avoid allocations on every call.
50 return &s
51 },
52 }
53 addOpPool = &sync.Pool{
54 New: func() any {
55 const n = 1 // WithAttributeSet
56 o := make([]metric.AddOption, 0, n)
57 return &o
58 },
59 }
60 recordOptPool = &sync.Pool{
61 New: func() any {
62 const n = 1 // WithAttributeSet
63 o := make([]metric.RecordOption, 0, n)
64 return &o
65 },
66 }
67 )
68
69 func get[T any](p *sync.Pool) *[]T { return p.Get().(*[]T) }
70 func put[T any](p *sync.Pool, s *[]T) {
71 *s = (*s)[:0]
72 p.Put(s)
73 }
74
75 // GetComponentName returns the constant name for the exporter with the
76 // provided id.
77 func GetComponentName(id int64) string {
78 return fmt.Sprintf("%s/%d", otelconv.ComponentTypeOtlpGRPCLogExporter, id)
79 }
80
81 // getPresetAttrs builds the preset attributes for instrumentation.
82 func getPresetAttrs(id int64, target string) []attribute.KeyValue {
83 serverAttrs := ServerAddrAttrs(target)
84 attrs := make([]attribute.KeyValue, 0, 2+len(serverAttrs))
85
86 attrs = append(
87 attrs,
88 semconv.OTelComponentName(GetComponentName(id)),
89 semconv.OTelComponentTypeOtlpGRPCLogExporter,
90 )
91 attrs = append(attrs, serverAttrs...)
92
93 return attrs
94 }
95
96 // Instrumentation is experimental instrumentation for the exporter.
97 type Instrumentation struct {
98 logInflightMetric metric.Int64UpDownCounter
99 logExportedMetric metric.Int64Counter
100 logExportedDurationMetric metric.Float64Histogram
101
102 presetAttrs []attribute.KeyValue
103 addOpt metric.AddOption
104 recOpt metric.RecordOption
105 }
106
107 // NewInstrumentation returns instrumentation for otlplog grpc exporter.
108 func NewInstrumentation(id int64, target string) (*Instrumentation, error) {
109 if !x.Observability.Enabled() {
110 return nil, nil
111 }
112
113 i := &Instrumentation{}
114
115 mp := otel.GetMeterProvider()
116 m := mp.Meter(
117 ScopeName,
118 metric.WithInstrumentationVersion(Version),
119 metric.WithSchemaURL(semconv.SchemaURL),
120 )
121
122 var err error
123
124 logInflightMetric, e := otelconv.NewSDKExporterLogInflight(m)
125 if e != nil {
126 e = fmt.Errorf("failed to create log inflight metric: %w", e)
127 err = errors.Join(err, e)
128 }
129 i.logInflightMetric = logInflightMetric.Inst()
130
131 logExportedMetric, e := otelconv.NewSDKExporterLogExported(m)
132 if e != nil {
133 e = fmt.Errorf("failed to create log exported metric: %w", e)
134 err = errors.Join(err, e)
135 }
136 i.logExportedMetric = logExportedMetric.Inst()
137
138 logOpDurationMetric, e := otelconv.NewSDKExporterOperationDuration(m)
139 if e != nil {
140 e = fmt.Errorf("failed to create log operation duration metric: %w", e)
141 err = errors.Join(err, e)
142 }
143 i.logExportedDurationMetric = logOpDurationMetric.Inst()
144 if err != nil {
145 return nil, err
146 }
147
148 i.presetAttrs = getPresetAttrs(id, target)
149
150 i.addOpt = metric.WithAttributeSet(attribute.NewSet(i.presetAttrs...))
151 i.recOpt = metric.WithAttributeSet(attribute.NewSet(append(
152 // Default to OK status code.
153 []attribute.KeyValue{semconv.RPCResponseStatusCode(codes.OK.String())},
154 i.presetAttrs...,
155 )...))
156 return i, nil
157 }
158
159 // ExportLogs instruments the ExportLogs method of the exporter. It returns
160 // an [ExportOp] that must have its [ExportOp.End] method called when the
161 // ExportLogs method returns.
162 func (i *Instrumentation) ExportLogs(ctx context.Context, count int64) ExportOp {
163 start := time.Now()
164 if i.logInflightMetric.Enabled(ctx) {
165 addOpt := get[metric.AddOption](addOpPool)
166 defer put(addOpPool, addOpt)
167 *addOpt = append(*addOpt, i.addOpt)
168 i.logInflightMetric.Add(ctx, count, *addOpt...)
169 }
170
171 return ExportOp{
172 nLogs: count,
173 ctx: ctx,
174 start: start,
175 inst: i,
176 }
177 }
178
179 // ExportOp tracks the operation being observed by [Instrumentation.ExportLogs].
180 type ExportOp struct {
181 nLogs int64
182 ctx context.Context
183 start time.Time
184
185 inst *Instrumentation
186 }
187
188 // End completes the observation of the operation being observed by a call to
189 // [Instrumentation.ExportLogs].
190 // Any error that is encountered is provided as err.
191 //
192 // If err is not nil, all logs will be recorded as failures unless error is of
193 // type [internal.PartialSuccess]. In the case of a PartialSuccess, the number
194 // of successfully exported logs will be determined by inspecting the
195 // RejectedItems field of the PartialSuccess.
196 func (e ExportOp) End(err error) {
197 addOpt := get[metric.AddOption](addOpPool)
198 defer put(addOpPool, addOpt)
199 *addOpt = append(*addOpt, e.inst.addOpt)
200
201 if e.inst.logInflightMetric.Enabled(e.ctx) {
202 e.inst.logInflightMetric.Add(e.ctx, -e.nLogs, *addOpt...)
203 }
204 success := successful(e.nLogs, err)
205 if e.inst.logExportedMetric.Enabled(e.ctx) {
206 e.inst.logExportedMetric.Add(e.ctx, success, *addOpt...)
207 }
208 if err != nil && e.inst.logExportedMetric.Enabled(e.ctx) {
209 // Add the error.type attribute to the attribute set.
210 attrs := get[attribute.KeyValue](attrsPool)
211 defer put(attrsPool, attrs)
212 *attrs = append(*attrs, e.inst.presetAttrs...)
213 *attrs = append(*attrs, semconv.ErrorType(err))
214
215 o := metric.WithAttributeSet(attribute.NewSet(*attrs...))
216
217 // Reset addOpt with new attribute set
218 *addOpt = append((*addOpt)[:0], o)
219
220 e.inst.logExportedMetric.Add(e.ctx, e.nLogs-success, *addOpt...)
221 }
222
223 recordOpt := get[metric.RecordOption](recordOptPool)
224 defer put(recordOptPool, recordOpt)
225 *recordOpt = append(*recordOpt, e.inst.recordOption(err))
226 e.inst.logExportedDurationMetric.Record(e.ctx, time.Since(e.start).Seconds(), *recordOpt...)
227 }
228
229 func (i *Instrumentation) recordOption(err error) metric.RecordOption {
230 if err == nil {
231 return i.recOpt
232 }
233 attrs := get[attribute.KeyValue](attrsPool)
234 defer put(attrsPool, attrs)
235
236 *attrs = append(*attrs, i.presetAttrs...)
237 code := status.Code(err)
238 *attrs = append(
239 *attrs,
240 semconv.RPCResponseStatusCode(code.String()),
241 semconv.ErrorType(err),
242 )
243
244 return metric.WithAttributeSet(attribute.NewSet(*attrs...))
245 }
246
247 // successful returns the number of successfully exported logs out of the n
248 // that were exported based on the provided error.
249 //
250 // If err is nil, n is returned. All logs were successfully exported.
251 //
252 // If err is not nil and not an [internal.PartialSuccess] error, 0 is returned.
253 // It is assumed all logs failed to be exported.
254 //
255 // If err is an [internal.PartialSuccess] error, the number of successfully
256 // exported logs is computed by subtracting the RejectedItems field from n. If
257 // RejectedItems is negative, n is returned. If RejectedItems is greater than
258 // n, 0 is returned.
259 func successful(n int64, err error) int64 {
260 if err == nil {
261 return n // All logs successfully exported.
262 }
263 // Split rejection calculation so successful is inlineable.
264 return n - rejectedCount(n, err)
265 }
266
267 var errPool = sync.Pool{
268 New: func() any {
269 return new(internal.PartialSuccess)
270 },
271 }
272
273 // rejectedCount returns how many out of the n logs exporter were rejected based on
274 // the provided non-nil err.
275 func rejectedCount(n int64, err error) int64 {
276 ps := errPool.Get().(*internal.PartialSuccess)
277 defer errPool.Put(ps)
278
279 // check for partial success
280 if errors.As(err, ps) {
281 return min(max(ps.RejectedItems, 0), n)
282 }
283 // all logs exporter
284 return n
285 }
286
287 // ServerAddrAttrs is a function that extracts server address and port attributes
288 // from a target string.
289 func ServerAddrAttrs(target string) []attribute.KeyValue {
290 addr, port, err := ParseCanonicalTarget(target)
291 if err != nil || (addr == "" && port < 0) {
292 if err != nil {
293 global.Debug("failed to parse target", "target", target, "error", err)
294 }
295 return nil
296 }
297
298 // Unix domain sockets: return only the path as server.address
299 if port == -1 {
300 return []attribute.KeyValue{semconv.ServerAddress(addr)}
301 }
302
303 // For network addresses, only include port if it's valid (> 0)
304 if port > 0 {
305 return []attribute.KeyValue{
306 semconv.ServerAddress(addr),
307 semconv.ServerPort(port),
308 }
309 }
310
311 // Port is 0 or invalid, only return address
312 return []attribute.KeyValue{semconv.ServerAddress(addr)}
313 }