Debian Codegraph @

sdk/log/record.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package log // import "go.opentelemetry.io/otel/sdk/log"
5
6 import (
7 "slices"
8 "strings"
9 "sync"
10 "time"
11 "unicode/utf8"
12
13 "go.opentelemetry.io/otel/internal/global"
14 "go.opentelemetry.io/otel/log"
15 "go.opentelemetry.io/otel/sdk/instrumentation"
16 "go.opentelemetry.io/otel/sdk/resource"
17 "go.opentelemetry.io/otel/trace"
18 )
19
20 // attributesInlineCount is the number of attributes that are efficiently
21 // stored in an array within a Record. This value is borrowed from slog which
22 // performed a quantitative survey of log library use and found this value to
23 // cover 95% of all use-cases (https://go.dev/blog/slog#performance).
24 const attributesInlineCount = 5
25
26 var logAttrDropped = sync.OnceFunc(func() {
27 global.Warn("limit reached: dropping log Record attributes")
28 })
29
30 var logKeyValuePairDropped = sync.OnceFunc(func() {
31 global.Warn("key duplication: dropping key-value pair")
32 })
33
34 // uniquePool is a pool of unique attributes used for attributes de-duplication.
35 var uniquePool = sync.Pool{
36 New: func() any { return new([]log.KeyValue) },
37 }
38
39 func getUnique() *[]log.KeyValue {
40 return uniquePool.Get().(*[]log.KeyValue)
41 }
42
43 func putUnique(v *[]log.KeyValue) {
44 // To reduce peak allocation.
45 const maxUniqueSize = 1028
46 if cap(*v) <= maxUniqueSize {
47 *v = (*v)[:0]
48 uniquePool.Put(v)
49 }
50 }
51
52 // indexPool is a pool of index maps used for attributes de-duplication.
53 var indexPool = sync.Pool{
54 New: func() any { return make(map[string]int) },
55 }
56
57 func getIndex() map[string]int {
58 return indexPool.Get().(map[string]int)
59 }
60
61 func putIndex(index map[string]int) {
62 clear(index)
63 indexPool.Put(index)
64 }
65
66 // seenPool is a pool of seen keys used for maps de-duplication.
67 var seenPool = sync.Pool{
68 New: func() any { return make(map[string]struct{}) },
69 }
70
71 func getSeen() map[string]struct{} {
72 return seenPool.Get().(map[string]struct{})
73 }
74
75 func putSeen(seen map[string]struct{}) {
76 clear(seen)
77 seenPool.Put(seen)
78 }
79
80 // Record is a log record emitted by the Logger.
81 // A log record with non-empty event name is interpreted as an event record.
82 //
83 // Do not create instances of Record on your own in production code.
84 // You can use [go.opentelemetry.io/otel/sdk/log/logtest.RecordFactory]
85 // for testing purposes.
86 type Record struct {
87 // Do not embed the log.Record. Attributes need to be overwrite-able and
88 // deep-copying needs to be possible.
89
90 eventName string
91 timestamp time.Time
92 observedTimestamp time.Time
93 severity log.Severity
94 severityText string
95 body log.Value
96
97 // The fields below are for optimizing the implementation of Attributes and
98 // AddAttributes. This design is borrowed from the slog Record type:
99 // https://cs.opensource.google/go/go/+/refs/tags/go1.22.0:src/log/slog/record.go;l=20
100
101 // Allocation optimization: an inline array sized to hold
102 // the majority of log calls (based on examination of open-source
103 // code). It holds the start of the list of attributes.
104 front [attributesInlineCount]log.KeyValue
105
106 // The number of attributes in front.
107 nFront int
108
109 // The list of attributes except for those in front.
110 // Invariants:
111 // - len(back) > 0 if nFront == len(front)
112 // - Unused array elements are zero-ed. Used to detect mistakes.
113 back []log.KeyValue
114
115 // dropped is the count of attributes that have been dropped when limits
116 // were reached.
117 dropped int
118
119 traceID trace.TraceID
120 spanID trace.SpanID
121 traceFlags trace.TraceFlags
122
123 // resource represents the entity that collected the log.
124 resource *resource.Resource
125
126 // scope is the Scope that the Logger was created with.
127 scope *instrumentation.Scope
128
129 attributeValueLengthLimit int
130 attributeCountLimit int
131
132 // specifies whether we should deduplicate any key value collections or not
133 allowDupKeys bool
134
135 noCmp [0]func() //nolint: unused // This is indeed used.
136 }
137
138 func (r *Record) addDropped(n int) {
139 r.dropped += n
140 if n > 0 {
141 logAttrDropped()
142 }
143 }
144
145 // EventName returns the event name.
146 // A log record with non-empty event name is interpreted as an event record.
147 func (r *Record) EventName() string {
148 return r.eventName
149 }
150
151 // SetEventName sets the event name.
152 // A log record with non-empty event name is interpreted as an event record.
153 func (r *Record) SetEventName(s string) {
154 r.eventName = s
155 }
156
157 // Timestamp returns the time when the log record occurred.
158 func (r *Record) Timestamp() time.Time {
159 return r.timestamp
160 }
161
162 // SetTimestamp sets the time when the log record occurred.
163 func (r *Record) SetTimestamp(t time.Time) {
164 r.timestamp = t
165 }
166
167 // ObservedTimestamp returns the time when the log record was observed.
168 func (r *Record) ObservedTimestamp() time.Time {
169 return r.observedTimestamp
170 }
171
172 // SetObservedTimestamp sets the time when the log record was observed.
173 func (r *Record) SetObservedTimestamp(t time.Time) {
174 r.observedTimestamp = t
175 }
176
177 // Severity returns the severity of the log record.
178 func (r *Record) Severity() log.Severity {
179 return r.severity
180 }
181
182 // SetSeverity sets the severity level of the log record.
183 func (r *Record) SetSeverity(level log.Severity) {
184 r.severity = level
185 }
186
187 // SeverityText returns severity (also known as log level) text. This is the
188 // original string representation of the severity as it is known at the source.
189 func (r *Record) SeverityText() string {
190 return r.severityText
191 }
192
193 // SetSeverityText sets severity (also known as log level) text. This is the
194 // original string representation of the severity as it is known at the source.
195 func (r *Record) SetSeverityText(text string) {
196 r.severityText = text
197 }
198
199 // Body returns the body of the log record.
200 func (r *Record) Body() log.Value {
201 return r.body
202 }
203
204 // SetBody sets the body of the log record.
205 func (r *Record) SetBody(v log.Value) {
206 if !r.allowDupKeys {
207 r.body = r.dedupeBodyCollections(v)
208 } else {
209 r.body = v
210 }
211 }
212
213 // WalkAttributes walks all attributes the log record holds by calling f for
214 // each on each [log.KeyValue] in the [Record]. Iteration stops if f returns false.
215 func (r *Record) WalkAttributes(f func(log.KeyValue) bool) {
216 for i := 0; i < r.nFront; i++ {
217 if !f(r.front[i]) {
218 return
219 }
220 }
221 for _, a := range r.back {
222 if !f(a) {
223 return
224 }
225 }
226 }
227
228 // AddAttributes adds attributes to the log record.
229 // Attributes in attrs will overwrite any attribute already added to r with the same key.
230 func (r *Record) AddAttributes(attrs ...log.KeyValue) {
231 n := r.AttributesLen()
232 if n == 0 {
233 // Avoid the more complex duplicate map lookups below.
234 var drop int
235 if !r.allowDupKeys {
236 attrs, drop = dedup(attrs)
237 if drop > 0 {
238 logKeyValuePairDropped()
239 }
240 }
241
242 attrs, drop := head(attrs, r.attributeCountLimit)
243 r.addDropped(drop)
244
245 r.addAttrs(attrs)
246 return
247 }
248
249 if !r.allowDupKeys {
250 // Use a slice from the pool to avoid modifying the original.
251 // Note, do not iterate attrs twice by just calling dedup(attrs) here.
252 unique := getUnique()
253 defer putUnique(unique)
254
255 // Used to find duplicates between attrs and existing attributes in r.
256 rIndex := r.attrIndex()
257 defer putIndex(rIndex)
258
259 // Used to find duplicates within attrs itself.
260 // The index value is the index of the element in unique.
261 uIndex := getIndex()
262 defer putIndex(uIndex)
263
264 dropped := 0
265
266 // Deduplicate attrs within the scope of all existing attributes.
267 for _, a := range attrs {
268 // Last-value-wins for any duplicates in attrs.
269 idx, found := uIndex[a.Key]
270 if found {
271 dropped++
272 logKeyValuePairDropped()
273 (*unique)[idx] = a
274 continue
275 }
276
277 idx, found = rIndex[a.Key]
278 if found {
279 // New attrs overwrite any existing with the same key.
280 dropped++
281 logKeyValuePairDropped()
282 if idx < 0 {
283 r.front[-(idx + 1)] = a
284 } else {
285 r.back[idx] = a
286 }
287 } else {
288 // Unique attribute.
289 (*unique) = append(*unique, a)
290 uIndex[a.Key] = len(*unique) - 1
291 }
292 }
293
294 if dropped > 0 {
295 attrs = make([]log.KeyValue, len(*unique))
296 copy(attrs, *unique)
297 }
298 }
299
300 if r.attributeCountLimit > 0 && n+len(attrs) > r.attributeCountLimit {
301 // Truncate the now unique attributes to comply with limit.
302 //
303 // Do not use head(attrs, r.attributeCountLimit - n) here. If
304 // (r.attributeCountLimit - n) <= 0 attrs needs to be emptied.
305 last := max(0, r.attributeCountLimit-n)
306 r.addDropped(len(attrs) - last)
307 attrs = attrs[:last]
308 }
309
310 r.addAttrs(attrs)
311 }
312
313 // attrIndex returns an index map for all attributes in the Record r. The index
314 // maps the attribute key to location the attribute is stored. If the value is
315 // < 0 then -(value + 1) (e.g. -1 -> 0, -2 -> 1, -3 -> 2) represents the index
316 // in r.nFront. Otherwise, the index is the exact index of r.back.
317 //
318 // The returned index is taken from the indexPool. It is the callers
319 // responsibility to return the index to that pool (putIndex) when done.
320 func (r *Record) attrIndex() map[string]int {
321 index := getIndex()
322 for i := 0; i < r.nFront; i++ {
323 key := r.front[i].Key
324 index[key] = -i - 1 // stored in front: negative index.
325 }
326 for i := 0; i < len(r.back); i++ {
327 key := r.back[i].Key
328 index[key] = i // stored in back: positive index.
329 }
330 return index
331 }
332
333 // addAttrs adds attrs to the Record r. This does not validate any limits or
334 // duplication of attributes, these tasks are left to the caller to handle
335 // prior to calling.
336 func (r *Record) addAttrs(attrs []log.KeyValue) {
337 var i int
338 for i = 0; i < len(attrs) && r.nFront < len(r.front); i++ {
339 a := attrs[i]
340 r.front[r.nFront] = r.applyAttrLimitsAndDedup(a)
341 r.nFront++
342 }
343
344 // Make a copy to avoid modifying the original.
345 j := len(r.back)
346 r.back = slices.Grow(r.back, len(attrs[i:]))
347 r.back = append(r.back, attrs[i:]...)
348 for i, a := range r.back[j:] {
349 r.back[i+j] = r.applyAttrLimitsAndDedup(a)
350 }
351 }
352
353 // SetAttributes sets (and overrides) attributes to the log record.
354 func (r *Record) SetAttributes(attrs ...log.KeyValue) {
355 var drop int
356 r.dropped = 0
357 if !r.allowDupKeys {
358 attrs, drop = dedup(attrs)
359 if drop > 0 {
360 logKeyValuePairDropped()
361 }
362 }
363
364 attrs, drop = head(attrs, r.attributeCountLimit)
365 r.addDropped(drop)
366
367 r.nFront = 0
368 var i int
369 for i = 0; i < len(attrs) && r.nFront < len(r.front); i++ {
370 a := attrs[i]
371 r.front[r.nFront] = r.applyAttrLimitsAndDedup(a)
372 r.nFront++
373 }
374
375 r.back = slices.Clone(attrs[i:])
376 for i, a := range r.back {
377 r.back[i] = r.applyAttrLimitsAndDedup(a)
378 }
379 }
380
381 // head returns the first n values of kvs along with the number of elements
382 // dropped. If n is less than or equal to zero, kvs is returned with 0.
383 func head(kvs []log.KeyValue, n int) (out []log.KeyValue, dropped int) {
384 if n > 0 && len(kvs) > n {
385 return kvs[:n], len(kvs) - n
386 }
387 return kvs, 0
388 }
389
390 // dedup deduplicates kvs front-to-back with the last value saved.
391 func dedup(kvs []log.KeyValue) (unique []log.KeyValue, dropped int) {
392 if len(kvs) <= 1 {
393 return kvs, 0 // No deduplication needed.
394 }
395
396 index := getIndex()
397 defer putIndex(index)
398 u := getUnique()
399 defer putUnique(u)
400 for _, a := range kvs {
401 idx, found := index[a.Key]
402 if found {
403 dropped++
404 (*u)[idx] = a
405 } else {
406 *u = append(*u, a)
407 index[a.Key] = len(*u) - 1
408 }
409 }
410
411 if dropped == 0 {
412 return kvs, 0
413 }
414
415 unique = make([]log.KeyValue, len(*u))
416 copy(unique, *u)
417 return unique, dropped
418 }
419
420 // AttributesLen returns the number of attributes in the log record.
421 func (r *Record) AttributesLen() int {
422 return r.nFront + len(r.back)
423 }
424
425 // DroppedAttributes returns the number of attributes dropped due to limits
426 // being reached.
427 func (r *Record) DroppedAttributes() int {
428 return r.dropped
429 }
430
431 // TraceID returns the trace ID or empty array.
432 func (r *Record) TraceID() trace.TraceID {
433 return r.traceID
434 }
435
436 // SetTraceID sets the trace ID.
437 func (r *Record) SetTraceID(id trace.TraceID) {
438 r.traceID = id
439 }
440
441 // SpanID returns the span ID or empty array.
442 func (r *Record) SpanID() trace.SpanID {
443 return r.spanID
444 }
445
446 // SetSpanID sets the span ID.
447 func (r *Record) SetSpanID(id trace.SpanID) {
448 r.spanID = id
449 }
450
451 // TraceFlags returns the trace flags.
452 func (r *Record) TraceFlags() trace.TraceFlags {
453 return r.traceFlags
454 }
455
456 // SetTraceFlags sets the trace flags.
457 func (r *Record) SetTraceFlags(flags trace.TraceFlags) {
458 r.traceFlags = flags
459 }
460
461 // Resource returns the entity that collected the log.
462 func (r *Record) Resource() *resource.Resource {
463 return r.resource
464 }
465
466 // InstrumentationScope returns the scope that the Logger was created with.
467 func (r *Record) InstrumentationScope() instrumentation.Scope {
468 if r.scope == nil {
469 return instrumentation.Scope{}
470 }
471 return *r.scope
472 }
473
474 // Clone returns a copy of the record with no shared state. The original record
475 // and the clone can both be modified without interfering with each other.
476 func (r *Record) Clone() Record {
477 res := *r
478 res.back = slices.Clone(r.back)
479 return res
480 }
481
482 func (r *Record) applyAttrLimitsAndDedup(attr log.KeyValue) log.KeyValue {
483 attr.Value = r.applyValueLimitsAndDedup(attr.Value)
484 return attr
485 }
486
487 func (r *Record) applyValueLimitsAndDedup(val log.Value) log.Value {
488 switch val.Kind() {
489 case log.KindString:
490 s := val.AsString()
491 if r.attributeValueLengthLimit >= 0 && len(s) > r.attributeValueLengthLimit {
492 val = log.StringValue(truncate(r.attributeValueLengthLimit, s))
493 }
494 case log.KindSlice:
495 sl := val.AsSlice()
496
497 // First check if any limits need to be applied.
498 if slices.ContainsFunc(sl, r.needsValueLimitsOrDedup) {
499 // Create a new slice to avoid modifying the original.
500 newSl := make([]log.Value, len(sl))
501 for i, item := range sl {
502 newSl[i] = r.applyValueLimitsAndDedup(item)
503 }
504 val = log.SliceValue(newSl...)
505 }
506
507 case log.KindMap:
508 kvs := val.AsMap()
509 var newKvs []log.KeyValue
510 var dropped int
511
512 if !r.allowDupKeys {
513 // Deduplicate then truncate.
514 // Do not do at the same time to avoid wasted truncation operations.
515 newKvs, dropped = dedup(kvs)
516 if dropped > 0 {
517 logKeyValuePairDropped()
518 }
519 } else {
520 newKvs = kvs
521 }
522
523 // Check if any attribute limits need to be applied.
524 needsChange := false
525 if dropped > 0 {
526 needsChange = true // Already changed by dedup.
527 } else {
528 for _, kv := range newKvs {
529 if r.needsValueLimitsOrDedup(kv.Value) {
530 needsChange = true
531 break
532 }
533 }
534 }
535
536 if needsChange {
537 // Only create new slice if changes are needed.
538 if dropped == 0 {
539 // Make a copy to avoid modifying the original.
540 newKvs = make([]log.KeyValue, len(kvs))
541 copy(newKvs, kvs)
542 }
543
544 for i := range newKvs {
545 newKvs[i] = r.applyAttrLimitsAndDedup(newKvs[i])
546 }
547 val = log.MapValue(newKvs...)
548 }
549 }
550 return val
551 }
552
553 // needsValueLimitsOrDedup checks if a value would be modified by applyValueLimitsAndDedup.
554 func (r *Record) needsValueLimitsOrDedup(val log.Value) bool {
555 switch val.Kind() {
556 case log.KindString:
557 return r.attributeValueLengthLimit >= 0 && len(val.AsString()) > r.attributeValueLengthLimit
558 case log.KindSlice:
559 if slices.ContainsFunc(val.AsSlice(), r.needsValueLimitsOrDedup) {
560 return true
561 }
562 case log.KindMap:
563 kvs := val.AsMap()
564 if !r.allowDupKeys && len(kvs) > 1 {
565 // Check for duplicates.
566 hasDuplicates := func() bool {
567 seen := getSeen()
568 defer putSeen(seen)
569 for _, kv := range kvs {
570 if _, ok := seen[kv.Key]; ok {
571 return true
572 }
573 seen[kv.Key] = struct{}{}
574 }
575 return false
576 }()
577 if hasDuplicates {
578 return true
579 }
580 }
581 for _, kv := range kvs {
582 if r.needsValueLimitsOrDedup(kv.Value) {
583 return true
584 }
585 }
586 }
587 return false
588 }
589
590 func (r *Record) dedupeBodyCollections(val log.Value) log.Value {
591 switch val.Kind() {
592 case log.KindSlice:
593 sl := val.AsSlice()
594
595 // Check if any nested values need deduplication.
596 if slices.ContainsFunc(sl, r.needsBodyDedup) {
597 // Create a new slice to avoid modifying the original.
598 newSl := make([]log.Value, len(sl))
599 for i, item := range sl {
600 newSl[i] = r.dedupeBodyCollections(item)
601 }
602 val = log.SliceValue(newSl...)
603 }
604
605 case log.KindMap:
606 kvs := val.AsMap()
607 newKvs, dropped := dedup(kvs)
608
609 // Check if any nested values need deduplication.
610 needsValueChange := false
611 for _, kv := range newKvs {
612 if r.needsBodyDedup(kv.Value) {
613 needsValueChange = true
614 break
615 }
616 }
617
618 if dropped > 0 || needsValueChange {
619 // Only create new value if changes are needed.
620 if dropped == 0 {
621 // Make a copy to avoid modifying the original.
622 newKvs = make([]log.KeyValue, len(kvs))
623 copy(newKvs, kvs)
624 }
625
626 for i := range newKvs {
627 newKvs[i].Value = r.dedupeBodyCollections(newKvs[i].Value)
628 }
629 val = log.MapValue(newKvs...)
630 }
631 }
632 return val
633 }
634
635 // needsBodyDedup checks if a value would be modified by dedupeBodyCollections.
636 func (r *Record) needsBodyDedup(val log.Value) bool {
637 switch val.Kind() {
638 case log.KindSlice:
639 if slices.ContainsFunc(val.AsSlice(), r.needsBodyDedup) {
640 return true
641 }
642 case log.KindMap:
643 kvs := val.AsMap()
644 if len(kvs) > 1 {
645 // Check for duplicates.
646 hasDuplicates := func() bool {
647 seen := getSeen()
648 defer putSeen(seen)
649 for _, kv := range kvs {
650 if _, ok := seen[kv.Key]; ok {
651 return true
652 }
653 seen[kv.Key] = struct{}{}
654 }
655 return false
656 }()
657 if hasDuplicates {
658 return true
659 }
660 }
661 for _, kv := range kvs {
662 if r.needsBodyDedup(kv.Value) {
663 return true
664 }
665 }
666 }
667 return false
668 }
669
670 // truncate returns a truncated version of s such that it contains less than
671 // the limit number of characters. Truncation is applied by returning the limit
672 // number of valid characters contained in s.
673 //
674 // If limit is negative, it returns the original string.
675 //
676 // UTF-8 is supported. When truncating, all invalid characters are dropped
677 // before applying truncation.
678 //
679 // If s already contains less than the limit number of bytes, it is returned
680 // unchanged. No invalid characters are removed.
681 func truncate(limit int, s string) string {
682 // This prioritize performance in the following order based on the most
683 // common expected use-cases.
684 //
685 // - Short values less than the default limit (128).
686 // - Strings with valid encodings that exceed the limit.
687 // - No limit.
688 // - Strings with invalid encodings that exceed the limit.
689 if limit < 0 || len(s) <= limit {
690 return s
691 }
692
693 // Optimistically, assume all valid UTF-8.
694 var b strings.Builder
695 count := 0
696 for i, c := range s {
697 if c != utf8.RuneError {
698 count++
699 if count > limit {
700 return s[:i]
701 }
702 continue
703 }
704
705 _, size := utf8.DecodeRuneInString(s[i:])
706 if size == 1 {
707 // Invalid encoding.
708 b.Grow(len(s) - 1)
709 _, _ = b.WriteString(s[:i])
710 s = s[i:]
711 break
712 }
713 }
714
715 // Fast-path, no invalid input.
716 if b.Cap() == 0 {
717 return s
718 }
719
720 // Truncate while validating UTF-8.
721 for i := 0; i < len(s) && count < limit; {
722 c := s[i]
723 if c < utf8.RuneSelf {
724 // Optimization for single byte runes (common case).
725 _ = b.WriteByte(c)
726 i++
727 count++
728 continue
729 }
730
731 _, size := utf8.DecodeRuneInString(s[i:])
732 if size == 1 {
733 // We checked for all 1-byte runes above, this is a RuneError.
734 i++
735 continue
736 }
737
738 _, _ = b.WriteString(s[i : i+size])
739 i += size
740 count++
741 }
742
743 return b.String()
744 }