|
| 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/stdout/stdoutlog/internal/observ" |
| 7 | + |
| 8 | +import ( |
| 9 | + "context" |
| 10 | + "errors" |
| 11 | + "fmt" |
| 12 | + "sync" |
| 13 | + "time" |
| 14 | + |
| 15 | + "go.opentelemetry.io/otel/exporters/stdout/stdoutlog/internal/x" |
| 16 | + |
| 17 | + "go.opentelemetry.io/otel" |
| 18 | + "go.opentelemetry.io/otel/attribute" |
| 19 | + "go.opentelemetry.io/otel/exporters/stdout/stdoutlog/internal" |
| 20 | + "go.opentelemetry.io/otel/metric" |
| 21 | + semconv "go.opentelemetry.io/otel/semconv/v1.40.0" |
| 22 | + "go.opentelemetry.io/otel/semconv/v1.40.0/otelconv" |
| 23 | +) |
| 24 | + |
| 25 | +const ( |
| 26 | + // ScopeName is the unique name of the meter used for instrumentation. |
| 27 | + ScopeName = "go.opentelemetry.io/otel/exporters/stdoutlog/internal/observ" |
| 28 | + |
| 29 | + // ComponentType uniquely identifies the OpenTelemetry Exporter component |
| 30 | + // being instrumented. |
| 31 | + // |
| 32 | + // The STDOUT log exporter is not a standardized OTel component type, so |
| 33 | + // it uses the Go package prefixed type name to ensure uniqueness and |
| 34 | + // identity. |
| 35 | + ComponentType = "go.opentelemetry.io/otel/exporters/stdout/stdoutlog.Exporter" |
| 36 | + |
| 37 | + // Version is the current version of this instrumentation. |
| 38 | + // |
| 39 | + // This matches the version of the exporter. |
| 40 | + Version = internal.Version |
| 41 | +) |
| 42 | + |
| 43 | +var ( |
| 44 | + addOptPool = &sync.Pool{ |
| 45 | + New: func() any { |
| 46 | + const n = 1 |
| 47 | + s := make([]metric.AddOption, 0, n) |
| 48 | + return &s |
| 49 | + }, |
| 50 | + } |
| 51 | + attrsPool = &sync.Pool{ |
| 52 | + New: func() any { |
| 53 | + const n = 1 + // component.name |
| 54 | + 1 + // component.type |
| 55 | + 1 // error.type |
| 56 | + s := make([]attribute.KeyValue, 0, n) |
| 57 | + return &s |
| 58 | + }, |
| 59 | + } |
| 60 | + recordOptPool = &sync.Pool{ |
| 61 | + New: func() any { |
| 62 | + const n = 1 |
| 63 | + s := make([]metric.RecordOption, 0, n) |
| 64 | + return &s |
| 65 | + }, |
| 66 | + } |
| 67 | +) |
| 68 | + |
| 69 | +func get[T any](pool *sync.Pool) *[]T { |
| 70 | + return pool.Get().(*[]T) |
| 71 | +} |
| 72 | + |
| 73 | +func put[T any](pool *sync.Pool, value *[]T) { |
| 74 | + *value = (*value)[:0] |
| 75 | + pool.Put(value) |
| 76 | +} |
| 77 | + |
| 78 | +// Instrumentation is experimental instrumentation for the exporter. |
| 79 | +type Instrumentation struct { |
| 80 | + inflight metric.Int64UpDownCounter |
| 81 | + exported metric.Int64Counter |
| 82 | + duration metric.Float64Histogram |
| 83 | + |
| 84 | + attrs []attribute.KeyValue |
| 85 | + addOpt metric.AddOption |
| 86 | + recOpt metric.RecordOption |
| 87 | +} |
| 88 | + |
| 89 | +// GetComponentName returns the constant name for the exporter with the |
| 90 | +// provided id. |
| 91 | +func GetComponentName(id int64) string { |
| 92 | + return fmt.Sprintf("%s/%d", ComponentType, id) |
| 93 | +} |
| 94 | + |
| 95 | +func getAttrs(id int64) []attribute.KeyValue { |
| 96 | + attrs := make([]attribute.KeyValue, 0, 2) |
| 97 | + attrs = append(attrs, |
| 98 | + semconv.OTelComponentName(GetComponentName(id)), |
| 99 | + semconv.OTelComponentNameKey.String(ComponentType)) |
| 100 | + |
| 101 | + return attrs |
| 102 | +} |
| 103 | + |
| 104 | +// NewInstrumentation returns instrumentation for stdlog exporter. |
| 105 | +func NewInstrumentation(id int64) (*Instrumentation, error) { |
| 106 | + if !x.Observability.Enabled() { |
| 107 | + return nil, nil |
| 108 | + } |
| 109 | + |
| 110 | + inst := &Instrumentation{} |
| 111 | + |
| 112 | + mp := otel.GetMeterProvider() |
| 113 | + m := mp.Meter( |
| 114 | + ScopeName, |
| 115 | + metric.WithInstrumentationVersion(Version), |
| 116 | + metric.WithSchemaURL(semconv.SchemaURL), |
| 117 | + ) |
| 118 | + |
| 119 | + var err error |
| 120 | + |
| 121 | + inflight, e := otelconv.NewSDKExporterLogInflight(m) |
| 122 | + if e != nil { |
| 123 | + e = fmt.Errorf("failed to create the inflight metric: %w", e) |
| 124 | + err = errors.Join(err, e) |
| 125 | + } |
| 126 | + inst.inflight = inflight.Inst() |
| 127 | + |
| 128 | + exported, e := otelconv.NewSDKExporterLogExported(m) |
| 129 | + if e != nil { |
| 130 | + e = fmt.Errorf("failed to create the exported metric: %w", e) |
| 131 | + err = errors.Join(err, e) |
| 132 | + } |
| 133 | + inst.exported = exported.Inst() |
| 134 | + |
| 135 | + duration, e := otelconv.NewSDKExporterOperationDuration(m) |
| 136 | + if e != nil { |
| 137 | + e = fmt.Errorf("failed to create the duration metric: %w", e) |
| 138 | + err = errors.Join(err, e) |
| 139 | + } |
| 140 | + inst.duration = duration.Inst() |
| 141 | + |
| 142 | + if err != nil { |
| 143 | + return nil, err |
| 144 | + } |
| 145 | + inst.attrs = getAttrs(id) |
| 146 | + inst.addOpt = metric.WithAttributeSet(attribute.NewSet(inst.attrs...)) |
| 147 | + inst.recOpt = metric.WithAttributeSet(attribute.NewSet(inst.attrs...)) |
| 148 | + return inst, nil |
| 149 | +} |
| 150 | + |
| 151 | +// ExportLogs instruments the ExportLogs method of the exporter. It returns |
| 152 | +// an [ExportOp] that must have its [ExportOp.End] method called when the |
| 153 | +// ExportLogs method returns. |
| 154 | +func (i *Instrumentation) ExportLogs(ctx context.Context, count int64) ExportOp { |
| 155 | + start := time.Now() |
| 156 | + |
| 157 | + addOpt := get[metric.AddOption](addOptPool) |
| 158 | + defer put(addOptPool, addOpt) |
| 159 | + *addOpt = append(*addOpt, i.addOpt) |
| 160 | + |
| 161 | + i.inflight.Add(ctx, count, *addOpt...) |
| 162 | + |
| 163 | + return ExportOp{ |
| 164 | + count: count, |
| 165 | + ctx: ctx, |
| 166 | + inst: i, |
| 167 | + start: start, |
| 168 | + } |
| 169 | +} |
| 170 | + |
| 171 | +// ExportOp tracks the operation being observed by [Instrumentation.ExportLogs]. |
| 172 | +type ExportOp struct { |
| 173 | + count int64 |
| 174 | + ctx context.Context |
| 175 | + inst *Instrumentation |
| 176 | + start time.Time |
| 177 | +} |
| 178 | + |
| 179 | +// End completes the observation of the operation being observed by a call to |
| 180 | +// [Instrumentation.ExportLogs]. |
| 181 | +// Any error that is encountered is provided as err. |
| 182 | +// |
| 183 | +// If err is not nil, all logs will be recorded as failures unless error is of |
| 184 | +// type [internal.PartialSuccess]. In the case of a PartialSuccess, the number |
| 185 | +// of successfully exported logs will be determined by inspecting the |
| 186 | +// RejectedItems field of the PartialSuccess. |
| 187 | +func (e ExportOp) End(err error) { |
| 188 | + addOpt := get[metric.AddOption](addOptPool) |
| 189 | + defer put(addOptPool, addOpt) |
| 190 | + *addOpt = append(*addOpt, e.inst.addOpt) |
| 191 | + |
| 192 | + e.inst.inflight.Add(e.ctx, -e.count, *addOpt...) |
| 193 | + |
| 194 | + success := successful(err, e.count) |
| 195 | + e.inst.exported.Add(e.ctx, success, *addOpt...) |
| 196 | + |
| 197 | + if err != nil { |
| 198 | + // Add the error.type attribute to the attribute set. |
| 199 | + attrs := get[attribute.KeyValue](attrsPool) |
| 200 | + defer put(attrsPool, attrs) |
| 201 | + *attrs = append(*attrs, e.inst.attrs...) |
| 202 | + *attrs = append(*attrs, semconv.ErrorType(err)) |
| 203 | + |
| 204 | + o := metric.WithAttributeSet(attribute.NewSet(*attrs...)) |
| 205 | + |
| 206 | + *addOpt = append((*addOpt)[:0], o) |
| 207 | + e.inst.exported.Add(e.ctx, e.count-success, *addOpt...) |
| 208 | + } |
| 209 | + |
| 210 | + recordOpt := get[metric.RecordOption](recordOptPool) |
| 211 | + defer put(recordOptPool, recordOpt) |
| 212 | + |
| 213 | + *recordOpt = append(*recordOpt, e.inst.recordOption(err)) |
| 214 | + e.inst.duration.Record(e.ctx, time.Since(e.start).Seconds(), *recordOpt...) |
| 215 | +} |
| 216 | + |
| 217 | +func (i *Instrumentation) recordOption(err error) metric.RecordOption { |
| 218 | + if err == nil { |
| 219 | + return i.recOpt |
| 220 | + } |
| 221 | + attrs := get[attribute.KeyValue](attrsPool) |
| 222 | + defer put(attrsPool, attrs) |
| 223 | + |
| 224 | + *attrs = append(*attrs, i.attrs...) |
| 225 | + *attrs = append(*attrs, semconv.ErrorType(err)) |
| 226 | + return metric.WithAttributeSet(attribute.NewSet(*attrs...)) |
| 227 | +} |
| 228 | + |
| 229 | +// successful returns the number of successfully exported logs out of the n |
| 230 | +// that were exported based on the provided error. |
| 231 | +// |
| 232 | +// If err is nil, n is returned. All logs were successfully exported. |
| 233 | +// |
| 234 | +// If err is not nil and not an [internal.PartialSuccess] error, 0 is returned. |
| 235 | +// It is assumed all logs failed to be exported. |
| 236 | +// |
| 237 | +// If err is an [internal.PartialSuccess] error, the number of successfully |
| 238 | +// exported logs is computed by subtracting the RejectedItems field from n. If |
| 239 | +// RejectedItems is negative, n is returned. If RejectedItems is greater than |
| 240 | +// n, 0 is returned. |
| 241 | +func successful(err error, n int64) int64 { |
| 242 | + if err == nil { |
| 243 | + return n // All logs successfully exported. |
| 244 | + } |
| 245 | + // Split rejected calculation so successful is inlineable. |
| 246 | + return n - rejectedCount(n, err) |
| 247 | +} |
| 248 | + |
| 249 | +var errPool = sync.Pool{ |
| 250 | + New: func() any { |
| 251 | + return new(internal.PartialSuccess) |
| 252 | + }, |
| 253 | +} |
| 254 | + |
| 255 | +// rejectedCount returns how many out of the n logs exported were rejected based on |
| 256 | +// the provided non-nil err. |
| 257 | +func rejectedCount(n int64, err error) int64 { |
| 258 | + ps := errPool.Get().(*internal.PartialSuccess) |
| 259 | + defer errPool.Put(ps) |
| 260 | + |
| 261 | + // check for partial success |
| 262 | + if errors.As(err, ps) { |
| 263 | + return min(max(ps.RejectedItems, 0), n) |
| 264 | + } |
| 265 | + // all logs exported |
| 266 | + return n |
| 267 | +} |
0 commit comments