Debian Codegraph @

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/log"
5
6 import (
7 "slices"
8 "time"
9 )
10
11 // attributesInlineCount is the number of attributes that are efficiently
12 // stored in an array within a Record. This value is borrowed from slog which
13 // performed a quantitative survey of log library use and found this value to
14 // cover 95% of all use-cases (https://go.dev/blog/slog#performance).
15 const attributesInlineCount = 5
16
17 // Record represents a log record.
18 // A log record with non-empty event name is interpreted as an event record.
19 type Record struct {
20 // Ensure forward compatibility by explicitly making this not comparable.
21 noCmp [0]func() //nolint: unused // This is indeed used.
22
23 eventName string
24 timestamp time.Time
25 observedTimestamp time.Time
26 severity Severity
27 severityText string
28 body Value
29 err error
30
31 // The fields below are for optimizing the implementation of Attributes and
32 // AddAttributes. This design is borrowed from the slog Record type:
33 // https://cs.opensource.google/go/go/+/refs/tags/go1.22.0:src/log/slog/record.go;l=20
34
35 // Allocation optimization: an inline array sized to hold
36 // the majority of log calls (based on examination of open-source
37 // code). It holds the start of the list of attributes.
38 front [attributesInlineCount]KeyValue
39
40 // The number of attributes in front.
41 nFront int
42
43 // The list of attributes except for those in front.
44 // Invariants:
45 // - len(back) > 0 if nFront == len(front)
46 // - Unused array elements are zero-ed. Used to detect mistakes.
47 back []KeyValue
48 }
49
50 // EventName returns the event name.
51 // A log record with non-empty event name is interpreted as an event record.
52 func (r *Record) EventName() string {
53 return r.eventName
54 }
55
56 // SetEventName sets the event name.
57 // A log record with non-empty event name is interpreted as an event record.
58 func (r *Record) SetEventName(s string) {
59 r.eventName = s
60 }
61
62 // Timestamp returns the time when the log record occurred.
63 func (r *Record) Timestamp() time.Time {
64 return r.timestamp
65 }
66
67 // SetTimestamp sets the time when the log record occurred.
68 func (r *Record) SetTimestamp(t time.Time) {
69 r.timestamp = t
70 }
71
72 // ObservedTimestamp returns the time when the log record was observed.
73 func (r *Record) ObservedTimestamp() time.Time {
74 return r.observedTimestamp
75 }
76
77 // SetObservedTimestamp sets the time when the log record was observed.
78 func (r *Record) SetObservedTimestamp(t time.Time) {
79 r.observedTimestamp = t
80 }
81
82 // Severity returns the [Severity] of the log record.
83 func (r *Record) Severity() Severity {
84 return r.severity
85 }
86
87 // SetSeverity sets the [Severity] level of the log record.
88 func (r *Record) SetSeverity(level Severity) {
89 r.severity = level
90 }
91
92 // SeverityText returns severity (also known as log level) text. This is the
93 // original string representation of the severity as it is known at the source.
94 func (r *Record) SeverityText() string {
95 return r.severityText
96 }
97
98 // SetSeverityText sets severity (also known as log level) text. This is the
99 // original string representation of the severity as it is known at the source.
100 func (r *Record) SetSeverityText(text string) {
101 r.severityText = text
102 }
103
104 // Body returns the body of the log record.
105 func (r *Record) Body() Value {
106 return r.body
107 }
108
109 // SetBody sets the body of the log record.
110 func (r *Record) SetBody(v Value) {
111 r.body = v
112 }
113
114 // Err returns the associated error if one has been set.
115 func (r *Record) Err() error {
116 return r.err
117 }
118
119 // SetErr sets the associated error. Passing nil clears the error.
120 func (r *Record) SetErr(err error) {
121 r.err = err
122 }
123
124 // WalkAttributes walks all attributes the log record holds by calling f for
125 // each on each [KeyValue] in the [Record]. Iteration stops if f returns false.
126 func (r *Record) WalkAttributes(f func(KeyValue) bool) {
127 for i := 0; i < r.nFront; i++ {
128 if !f(r.front[i]) {
129 return
130 }
131 }
132 for _, a := range r.back {
133 if !f(a) {
134 return
135 }
136 }
137 }
138
139 // AddAttributes adds attributes to the log record.
140 func (r *Record) AddAttributes(attrs ...KeyValue) {
141 var i int
142 for i = 0; i < len(attrs) && r.nFront < len(r.front); i++ {
143 a := attrs[i]
144 r.front[r.nFront] = a
145 r.nFront++
146 }
147
148 r.back = slices.Grow(r.back, len(attrs[i:]))
149 r.back = append(r.back, attrs[i:]...)
150 }
151
152 // AttributesLen returns the number of attributes in the log record.
153 func (r *Record) AttributesLen() int {
154 return r.nFront + len(r.back)
155 }
156
157 // Clone returns a copy of the record with no shared state.
158 // The original record and the clone can both be modified without interfering with each other.
159 func (r *Record) Clone() Record {
160 res := *r
161 res.back = slices.Clone(r.back)
162 return res
163 }