| 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 |
} |