Debian Codegraph @

log/logger.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 "context"
8 "slices"
9
10 "go.opentelemetry.io/otel/attribute"
11 "go.opentelemetry.io/otel/log/embedded"
12 )
13
14 // Logger emits log records.
15 //
16 // Warning: Methods may be added to this interface in minor releases. See
17 // package documentation on API implementation for information on how to set
18 // default behavior for unimplemented methods.
19 type Logger interface {
20 // Users of the interface can ignore this. This embedded type is only used
21 // by implementations of this interface. See the "API Implementations"
22 // section of the package documentation for more information.
23 embedded.Logger
24
25 // Emit emits a log record.
26 //
27 // The record may be held by the implementation. Callers should not mutate
28 // the record after passed.
29 //
30 // Implementations of this method need to be safe for a user to call
31 // concurrently.
32 Emit(ctx context.Context, record Record)
33
34 // Enabled reports whether the Logger emits for the given context and
35 // param.
36 //
37 // This is useful for users that want to know if a [Record]
38 // will be processed or dropped before they perform complex operations to
39 // construct the [Record].
40 //
41 // The passed param is likely to be a partial record information being
42 // provided (e.g a param with only the Severity set).
43 // If a Logger needs more information than is provided, it
44 // is said to be in an indeterminate state (see below).
45 //
46 // The returned value will be true when the Logger will emit for the
47 // provided context and param, and will be false if the Logger will not
48 // emit. The returned value may be true or false in an indeterminate state.
49 // An implementation should default to returning true for an indeterminate
50 // state, but may return false if valid reasons in particular circumstances
51 // exist (e.g. performance, correctness).
52 //
53 // The param should not be held by the implementation. A copy should be
54 // made if the param needs to be held after the call returns.
55 //
56 // Implementations of this method need to be safe for a user to call
57 // concurrently.
58 Enabled(ctx context.Context, param EnabledParameters) bool
59 }
60
61 // LoggerOption applies configuration options to a [Logger].
62 type LoggerOption interface {
63 // applyLogger is used to set a LoggerOption value of a LoggerConfig.
64 applyLogger(LoggerConfig) LoggerConfig
65 }
66
67 // LoggerConfig contains options for a [Logger].
68 type LoggerConfig struct {
69 // Ensure forward compatibility by explicitly making this not comparable.
70 noCmp [0]func() //nolint: unused // This is indeed used.
71
72 version string
73 schemaURL string
74 attrs attribute.Set
75 }
76
77 // NewLoggerConfig returns a new [LoggerConfig] with all the options applied.
78 func NewLoggerConfig(options ...LoggerOption) LoggerConfig {
79 var c LoggerConfig
80 for _, opt := range options {
81 c = opt.applyLogger(c)
82 }
83 return c
84 }
85
86 // InstrumentationVersion returns the version of the library providing
87 // instrumentation.
88 func (cfg LoggerConfig) InstrumentationVersion() string {
89 return cfg.version
90 }
91
92 // InstrumentationAttributes returns the attributes associated with the library
93 // providing instrumentation.
94 func (cfg LoggerConfig) InstrumentationAttributes() attribute.Set {
95 return cfg.attrs
96 }
97
98 // SchemaURL returns the schema URL of the library providing instrumentation.
99 func (cfg LoggerConfig) SchemaURL() string {
100 return cfg.schemaURL
101 }
102
103 type loggerOptionFunc func(LoggerConfig) LoggerConfig
104
105 func (fn loggerOptionFunc) applyLogger(cfg LoggerConfig) LoggerConfig {
106 return fn(cfg)
107 }
108
109 // WithInstrumentationVersion returns a [LoggerOption] that sets the
110 // instrumentation version of a [Logger].
111 func WithInstrumentationVersion(version string) LoggerOption {
112 return loggerOptionFunc(func(config LoggerConfig) LoggerConfig {
113 config.version = version
114 return config
115 })
116 }
117
118 // mergeSets returns the union of keys between a and b. Any duplicate keys will
119 // use the value associated with b.
120 func mergeSets(a, b attribute.Set) attribute.Set {
121 // NewMergeIterator uses the first value for any duplicates.
122 iter := attribute.NewMergeIterator(&b, &a)
123 merged := make([]attribute.KeyValue, 0, a.Len()+b.Len())
124 for iter.Next() {
125 merged = append(merged, iter.Attribute())
126 }
127 return attribute.NewSet(merged...)
128 }
129
130 // WithInstrumentationAttributes returns a [LoggerOption] that sets the
131 // instrumentation attributes of a [Logger].
132 //
133 // This is equivalent to calling WithInstrumentationAttributeSet with an
134 // [attribute.Set] created from a clone of the passed attributes.
135 // [WithInstrumentationAttributeSet] is recommended for more control.
136 //
137 // If multiple [WithInstrumentationAttributes] or [WithInstrumentationAttributeSet]
138 // options are passed, the attributes will be merged together in the order
139 // they are passed. Attributes with duplicate keys will use the last value passed.
140 func WithInstrumentationAttributes(attr ...attribute.KeyValue) LoggerOption {
141 set := attribute.NewSet(slices.Clone(attr)...)
142 return WithInstrumentationAttributeSet(set)
143 }
144
145 // WithInstrumentationAttributeSet returns a [LoggerOption] that adds the
146 // instrumentation attributes of a [Logger].
147 //
148 // If multiple [WithInstrumentationAttributes] or [WithInstrumentationAttributeSet]
149 // options are passed, the attributes will be merged together in the order
150 // they are passed. Attributes with duplicate keys will use the last value passed.
151 func WithInstrumentationAttributeSet(set attribute.Set) LoggerOption {
152 if set.Len() == 0 {
153 return loggerOptionFunc(func(config LoggerConfig) LoggerConfig {
154 return config
155 })
156 }
157
158 return loggerOptionFunc(func(config LoggerConfig) LoggerConfig {
159 if config.attrs.Len() == 0 {
160 config.attrs = set
161 } else {
162 config.attrs = mergeSets(config.attrs, set)
163 }
164 return config
165 })
166 }
167
168 // WithSchemaURL returns a [LoggerOption] that sets the schema URL for a
169 // [Logger].
170 func WithSchemaURL(schemaURL string) LoggerOption {
171 return loggerOptionFunc(func(config LoggerConfig) LoggerConfig {
172 config.schemaURL = schemaURL
173 return config
174 })
175 }
176
177 // EnabledParameters represents payload for [Logger]'s Enabled method.
178 type EnabledParameters struct {
179 Severity Severity
180 EventName string
181 }