semantic_logger 5.2.0 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/docs/api.md +160 -9
- data/docs/appenders.md +461 -34
- data/docs/config.md +543 -36
- data/docs/log.md +38 -7
- data/docs/metrics.md +139 -28
- data/docs/operations.md +293 -24
- data/docs/rails.md +319 -5
- data/docs/security.md +135 -107
- data/docs/testing.md +23 -0
- data/docs/upgrading.md +644 -1
- data/lib/semantic_logger/appender/async.rb +29 -11
- data/lib/semantic_logger/appender/bugsnag.rb +7 -2
- data/lib/semantic_logger/appender/cloudwatch_logs.rb +46 -6
- data/lib/semantic_logger/appender/elasticsearch_base.rb +197 -29
- data/lib/semantic_logger/appender/elasticsearch_http.rb +22 -5
- data/lib/semantic_logger/appender/file.rb +29 -14
- data/lib/semantic_logger/appender/graylog.rb +81 -7
- data/lib/semantic_logger/appender/honeybadger.rb +7 -1
- data/lib/semantic_logger/appender/honeybadger_insights.rb +8 -2
- data/lib/semantic_logger/appender/http.rb +244 -41
- data/lib/semantic_logger/appender/io.rb +11 -6
- data/lib/semantic_logger/appender/kafka.rb +192 -46
- data/lib/semantic_logger/appender/loki.rb +42 -6
- data/lib/semantic_logger/appender/mongodb.rb +94 -9
- data/lib/semantic_logger/appender/new_relic.rb +2 -3
- data/lib/semantic_logger/appender/new_relic_logs.rb +30 -8
- data/lib/semantic_logger/appender/open_telemetry.rb +37 -35
- data/lib/semantic_logger/appender/rabbitmq.rb +241 -17
- data/lib/semantic_logger/appender/sentry.rb +2 -3
- data/lib/semantic_logger/appender/sentry_ruby.rb +82 -15
- data/lib/semantic_logger/appender/splunk.rb +4 -4
- data/lib/semantic_logger/appender/splunk_http.rb +92 -1
- data/lib/semantic_logger/appender/syslog.rb +89 -10
- data/lib/semantic_logger/appender/tcp.rb +68 -98
- data/lib/semantic_logger/appender/text_output.rb +65 -0
- data/lib/semantic_logger/appender/udp.rb +130 -18
- data/lib/semantic_logger/appender/wrapper.rb +10 -7
- data/lib/semantic_logger/appender.rb +115 -10
- data/lib/semantic_logger/appenders.rb +136 -4
- data/lib/semantic_logger/backtrace_cleaning.rb +77 -0
- data/lib/semantic_logger/base.rb +53 -71
- data/lib/semantic_logger/call_site.rb +235 -0
- data/lib/semantic_logger/context.rb +222 -0
- data/lib/semantic_logger/core_ext/process.rb +20 -5
- data/lib/semantic_logger/core_ext/warning.rb +70 -0
- data/lib/semantic_logger/deprecation.rb +139 -0
- data/lib/semantic_logger/exception_details.rb +4 -3
- data/lib/semantic_logger/formatters/base.rb +139 -19
- data/lib/semantic_logger/formatters/color.rb +3 -4
- data/lib/semantic_logger/formatters/default.rb +35 -7
- data/lib/semantic_logger/formatters/ecs.rb +9 -4
- data/lib/semantic_logger/formatters/json.rb +9 -0
- data/lib/semantic_logger/formatters/logfmt.rb +9 -7
- data/lib/semantic_logger/formatters/loki/labels.rb +282 -0
- data/lib/semantic_logger/formatters/loki.rb +412 -24
- data/lib/semantic_logger/formatters/new_relic_logs.rb +15 -13
- data/lib/semantic_logger/formatters/one_line.rb +44 -10
- data/lib/semantic_logger/formatters/open_telemetry.rb +186 -29
- data/lib/semantic_logger/formatters/pattern.rb +60 -8
- data/lib/semantic_logger/formatters/raw.rb +38 -8
- data/lib/semantic_logger/formatters/signalfx.rb +55 -15
- data/lib/semantic_logger/formatters/syslog.rb +4 -2
- data/lib/semantic_logger/formatters/syslog_cee.rb +10 -4
- data/lib/semantic_logger/formatters/syslog_header.rb +49 -0
- data/lib/semantic_logger/formatters.rb +1 -0
- data/lib/semantic_logger/log.rb +236 -80
- data/lib/semantic_logger/loggable.rb +55 -95
- data/lib/semantic_logger/logger.rb +31 -5
- data/lib/semantic_logger/metric/new_relic.rb +32 -17
- data/lib/semantic_logger/metric/signalfx.rb +21 -12
- data/lib/semantic_logger/metric/statsd.rb +26 -8
- data/lib/semantic_logger/processor.rb +194 -5
- data/lib/semantic_logger/queue_processor/backoff.rb +140 -0
- data/lib/semantic_logger/queue_processor/batch_failure.rb +69 -0
- data/lib/semantic_logger/queue_processor/held_write.rb +62 -0
- data/lib/semantic_logger/queue_processor/inbox.rb +97 -0
- data/lib/semantic_logger/queue_processor/reopener.rb +56 -0
- data/lib/semantic_logger/queue_processor/reporter.rb +113 -0
- data/lib/semantic_logger/queue_processor/request.rb +48 -10
- data/lib/semantic_logger/queue_processor/throttled_counter.rb +60 -17
- data/lib/semantic_logger/queue_processor.rb +426 -176
- data/lib/semantic_logger/ractor_copy.rb +120 -0
- data/lib/semantic_logger/ractor_processor.rb +82 -0
- data/lib/semantic_logger/ractor_receiver.rb +282 -0
- data/lib/semantic_logger/ractor_support.rb +28 -0
- data/lib/semantic_logger/redactor.rb +310 -0
- data/lib/semantic_logger/semantic_logger.rb +313 -79
- data/lib/semantic_logger/subscriber.rb +169 -15
- data/lib/semantic_logger/sync_processor.rb +226 -26
- data/lib/semantic_logger/test/capture_log_events.rb +20 -2
- data/lib/semantic_logger/test/minitest.rb +2 -1
- data/lib/semantic_logger/test/rspec.rb +1 -1
- data/lib/semantic_logger/trap_safe.rb +113 -0
- data/lib/semantic_logger/utils.rb +266 -79
- data/lib/semantic_logger/version.rb +1 -1
- data/lib/semantic_logger.rb +35 -2
- metadata +22 -2
data/lib/semantic_logger/log.rb
CHANGED
|
@@ -41,65 +41,80 @@ module SemanticLogger
|
|
|
41
41
|
# backtrace [Array<String>]
|
|
42
42
|
# The backtrace captured at source when the log level >= SemanticLogger.backtrace_level
|
|
43
43
|
#
|
|
44
|
+
# call_site [CallSite]
|
|
45
|
+
# Where the entry was logged: the path, line, and label (usually the method) of the code that
|
|
46
|
+
# made the log call, when the log level >= SemanticLogger.call_site_level. The one the log call
|
|
47
|
+
# supplies as `call_site:`, or nil for `call_site: false`, or else the first line of a backtrace
|
|
48
|
+
# it supplies. nil below that level.
|
|
49
|
+
#
|
|
44
50
|
# metric_amount [Numeric]
|
|
45
51
|
# Used for numeric or counter metrics.
|
|
46
52
|
# For example, the number of inquiries or, the amount purchased etc.
|
|
47
53
|
#
|
|
48
54
|
# context [Hash]
|
|
49
55
|
# Named contexts that were captured when the log entry was created.
|
|
56
|
+
#
|
|
57
|
+
# captures [Hash]
|
|
58
|
+
# Objects that an appender captured on the logging thread for its own use when the log entry
|
|
59
|
+
# was created, such as the OpenTelemetry context. Only a formatter built for that appender writes
|
|
60
|
+
# them, as the NewRelicLogs formatter writes the linking metadata its appender captures.
|
|
61
|
+
#
|
|
62
|
+
# The payload, named tags, context, and dimensions have the values of sensitive keys replaced
|
|
63
|
+
# before the entry is written to any appender, when SemanticLogger.sensitive_keys is set (see
|
|
64
|
+
# #redact).
|
|
50
65
|
class Log
|
|
51
66
|
# Keys passed in without a payload that will be extracted and the remainder passed into the payload.
|
|
52
|
-
NON_PAYLOAD_KEYS = %i[message exception backtrace
|
|
53
|
-
|
|
54
|
-
log_exception on_exception_level
|
|
55
|
-
metric metric_amount dimensions].freeze
|
|
67
|
+
NON_PAYLOAD_KEYS = %i[message exception backtrace call_site duration min_duration
|
|
68
|
+
log_exception on_exception_level metric metric_amount dimensions].freeze
|
|
56
69
|
|
|
57
70
|
# Values accepted for the :log_exception argument.
|
|
58
71
|
LOG_EXCEPTION_OPTIONS = %i[full partial none].freeze
|
|
59
72
|
private_constant :LOG_EXCEPTION_OPTIONS
|
|
60
73
|
|
|
61
74
|
# A finite real number, which #assign can compare with another one.
|
|
62
|
-
REAL_NUMBER = ->(value) { value.is_a?(Numeric) && value.real? && value.finite? }
|
|
75
|
+
REAL_NUMBER = Utils.make_shareable(->(value) { value.is_a?(Numeric) && value.real? && value.finite? })
|
|
63
76
|
private_constant :REAL_NUMBER
|
|
64
77
|
|
|
65
78
|
# Checks that a value is valid for its argument, for the arguments that do not accept any value.
|
|
66
79
|
# Any other value would make #assign, or the formatters, raise.
|
|
67
|
-
ARGUMENT_VALIDATORS =
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
80
|
+
ARGUMENT_VALIDATORS = Utils.make_shareable(
|
|
81
|
+
{
|
|
82
|
+
backtrace: ->(value) { value.is_a?(Array) && value.all?(String) },
|
|
83
|
+
call_site: ->(value) { CallSite.supplied?(value) },
|
|
84
|
+
duration: REAL_NUMBER,
|
|
85
|
+
min_duration: REAL_NUMBER,
|
|
86
|
+
metric_amount: REAL_NUMBER,
|
|
87
|
+
dimensions: ->(value) { value.is_a?(Hash) },
|
|
88
|
+
log_exception: ->(value) { LOG_EXCEPTION_OPTIONS.include?(value) },
|
|
89
|
+
on_exception_level: ->(value) { Levels.valid?(value) }
|
|
90
|
+
}.freeze
|
|
91
|
+
)
|
|
76
92
|
private_constant :ARGUMENT_VALIDATORS
|
|
77
93
|
|
|
78
94
|
# Hash#key?, which unlike HashWithIndifferentAccess#key? only matches the exact Symbol key.
|
|
79
|
-
HASH_KEY = Hash.instance_method(:key?)
|
|
95
|
+
HASH_KEY = Utils.make_shareable(Hash.instance_method(:key?))
|
|
80
96
|
private_constant :HASH_KEY
|
|
81
97
|
|
|
82
|
-
# Whether the value is accepted for the :log_exception argument of #assign.
|
|
83
|
-
def self.log_exception_option?(value)
|
|
84
|
-
value.nil? || LOG_EXCEPTION_OPTIONS.include?(value)
|
|
85
|
-
end
|
|
86
|
-
|
|
87
98
|
# Returns [String] the name that identifies the thread in a log entry: the thread's own name,
|
|
88
99
|
# or its object id when it has none, which Ruby never reuses within a process.
|
|
89
100
|
def self.thread_name_for(thread) = thread.name || thread.object_id.to_s
|
|
90
101
|
|
|
91
102
|
attr_accessor :level, :level_index, :name, :message, :time, :duration,
|
|
92
|
-
:payload, :exception, :thread_name, :backtrace,
|
|
93
|
-
:tags, :named_tags, :context,
|
|
103
|
+
:payload, :exception, :thread_name, :backtrace, :call_site,
|
|
104
|
+
:tags, :named_tags, :context, :captures,
|
|
94
105
|
:metric, :metric_amount, :dimensions
|
|
95
106
|
|
|
96
|
-
|
|
107
|
+
# Parameters
|
|
108
|
+
# thread: [Thread]
|
|
109
|
+
# The thread whose name, tags, and named tags the entry has.
|
|
110
|
+
# Default: Thread.current
|
|
111
|
+
def initialize(name, level, index = nil, thread = Thread.current)
|
|
97
112
|
@level = level
|
|
98
|
-
@thread_name = Log.thread_name_for(
|
|
113
|
+
@thread_name = Log.thread_name_for(thread)
|
|
99
114
|
@name = name
|
|
100
115
|
@time = Time.now
|
|
101
|
-
@tags =
|
|
102
|
-
@named_tags =
|
|
116
|
+
@tags = Context.tags(thread)
|
|
117
|
+
@named_tags = Context.named_tags(thread)
|
|
103
118
|
@level_index = index.nil? ? Levels.index(level) : index
|
|
104
119
|
end
|
|
105
120
|
|
|
@@ -117,6 +132,7 @@ module SemanticLogger
|
|
|
117
132
|
metric_amount: nil,
|
|
118
133
|
duration: nil,
|
|
119
134
|
backtrace: nil,
|
|
135
|
+
call_site: nil,
|
|
120
136
|
log_exception: :full,
|
|
121
137
|
on_exception_level: nil,
|
|
122
138
|
dimensions: nil)
|
|
@@ -126,6 +142,7 @@ module SemanticLogger
|
|
|
126
142
|
self.metric = metric
|
|
127
143
|
self.metric_amount = metric_amount
|
|
128
144
|
self.dimensions = dimensions
|
|
145
|
+
Log.negative_metric_amount_deprecated if counted_negative_amount?
|
|
129
146
|
|
|
130
147
|
if exception
|
|
131
148
|
unless exception.is_a?(Exception)
|
|
@@ -137,7 +154,10 @@ module SemanticLogger
|
|
|
137
154
|
when :full
|
|
138
155
|
self.exception = exception
|
|
139
156
|
when :partial
|
|
140
|
-
|
|
157
|
+
# The class and message of the exception, then of each exception that caused it: the same
|
|
158
|
+
# exceptions that :full writes (see #backtrace_to_s).
|
|
159
|
+
self.message = with_class(" -- Exception: ", exception, ": ", message_of(exception))
|
|
160
|
+
each_exception(exception) { |ex, depth| self.message = with_cause(ex) unless depth.zero? }
|
|
141
161
|
when nil, :none
|
|
142
162
|
# Log the message without the exception that was raised
|
|
143
163
|
nil
|
|
@@ -158,11 +178,17 @@ module SemanticLogger
|
|
|
158
178
|
return false if duration && (duration < min_duration) && exception.nil?
|
|
159
179
|
|
|
160
180
|
if backtrace
|
|
161
|
-
self.backtrace = Utils.extract_backtrace(backtrace)
|
|
181
|
+
backtrace = self.backtrace = Utils.extract_backtrace(backtrace)
|
|
162
182
|
elsif level_index >= SemanticLogger.backtrace_level_index
|
|
163
183
|
self.backtrace = Utils.extract_backtrace(caller)
|
|
164
184
|
end
|
|
165
185
|
|
|
186
|
+
# A call site or backtrace supplied by the log call says where the entry is about, such as the
|
|
187
|
+
# application code that ran a query, or the thread whose backtrace is logged.
|
|
188
|
+
if level_index >= SemanticLogger.call_site_level_index
|
|
189
|
+
self.call_site = CallSite.locate(call_site: call_site, backtrace: backtrace)
|
|
190
|
+
end
|
|
191
|
+
|
|
166
192
|
true
|
|
167
193
|
end
|
|
168
194
|
|
|
@@ -182,12 +208,36 @@ module SemanticLogger
|
|
|
182
208
|
added = args.delete(:payload)
|
|
183
209
|
assigned, kept = args.partition { |key, value| block_attribute?(key, value) }
|
|
184
210
|
assigned.each { |key, value| public_send(:"#{key}=", value) }
|
|
211
|
+
# Once per process, so that #assign having reported it already does no harm.
|
|
212
|
+
Log.negative_metric_amount_deprecated if counted_negative_amount?
|
|
185
213
|
# An argument this entry already has wins over the block's :payload, like the block's other keys.
|
|
186
214
|
added = merge_payload(kept.to_h, added) unless kept.empty?
|
|
187
215
|
self.payload = merge_payload(payload, added)
|
|
188
216
|
self
|
|
189
217
|
end
|
|
190
218
|
|
|
219
|
+
# Reports, once per process, that a log call gave a negative metric amount, which is deprecated:
|
|
220
|
+
# a metric counts upward, and v6 drops a negative amount. The entry is still logged with it.
|
|
221
|
+
#
|
|
222
|
+
# Only once, so that a negative amount in a loop does not report a warning for each log call, and
|
|
223
|
+
# only once deprecation warnings are on, so that turning them on later still reports it. Not from
|
|
224
|
+
# a Ractor other than the main one, which cannot record that it was reported. Two threads that
|
|
225
|
+
# report at the same moment can each report it, which costs a second warning at worst. Remove in
|
|
226
|
+
# v6, where the metrics API drops a negative amount instead.
|
|
227
|
+
#
|
|
228
|
+
# Internal: called by #assign and #assign_hash only (@api private).
|
|
229
|
+
def self.negative_metric_amount_deprecated
|
|
230
|
+
return if !Warning[:deprecated] || RactorSupport.other_ractor? || @negative_metric_amount_reported
|
|
231
|
+
|
|
232
|
+
@negative_metric_amount_reported = true
|
|
233
|
+
Deprecation.warn(
|
|
234
|
+
"A negative metric_amount is deprecated: a metric counts upward, and v6 drops a negative amount. " \
|
|
235
|
+
"Count what goes down as a metric of its own, such as \"cart/items_removed\". " \
|
|
236
|
+
"This is reported for the first negative amount only. See " \
|
|
237
|
+
"https://logger.reidmorrison.com/upgrading.html#negative-metric-amounts"
|
|
238
|
+
)
|
|
239
|
+
end
|
|
240
|
+
|
|
191
241
|
# Returns [true|false] whether the value can be used as the log argument named by the key.
|
|
192
242
|
#
|
|
193
243
|
# Never raises, so it can check values from untrusted data before they are passed to #assign.
|
|
@@ -240,17 +290,24 @@ module SemanticLogger
|
|
|
240
290
|
|
|
241
291
|
MAX_EXCEPTIONS_TO_UNWRAP = 5
|
|
242
292
|
# Call the block for exception and any nested exception
|
|
243
|
-
|
|
293
|
+
#
|
|
294
|
+
# Parameters
|
|
295
|
+
# first: [Exception|nil]
|
|
296
|
+
# The exception to start from, for one that this entry does not keep, such as the one that
|
|
297
|
+
# log_exception: :partial writes into the message.
|
|
298
|
+
# Default: this entry's exception
|
|
299
|
+
#
|
|
300
|
+
# Yields each exception with its depth: 0 for the first one, 1 for the exception that caused it,
|
|
301
|
+
# and so on.
|
|
302
|
+
def each_exception(first = exception)
|
|
244
303
|
# With thanks to https://github.com/bugsnag/bugsnag-ruby/blob/6348306e44323eee347896843d16c690cd7c4362/lib/bugsnag/notification.rb#L81
|
|
245
|
-
depth = 0
|
|
246
304
|
exceptions = []
|
|
247
|
-
ex =
|
|
305
|
+
ex = first
|
|
248
306
|
while !ex.nil? && !exceptions.include?(ex) && exceptions.length < MAX_EXCEPTIONS_TO_UNWRAP
|
|
249
307
|
exceptions << ex
|
|
250
|
-
yield(ex,
|
|
308
|
+
yield(ex, exceptions.length - 1)
|
|
251
309
|
|
|
252
|
-
|
|
253
|
-
ex =
|
|
310
|
+
ex =
|
|
254
311
|
if ex.respond_to?(:cause) && ex.cause
|
|
255
312
|
ex.cause
|
|
256
313
|
elsif ex.respond_to?(:continued_exception) && ex.continued_exception
|
|
@@ -279,37 +336,65 @@ module SemanticLogger
|
|
|
279
336
|
#
|
|
280
337
|
# The result is cached on this entry, since every appender's formatter may ask for it.
|
|
281
338
|
def exception_details(exception, source: false)
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
339
|
+
cached([:exception_details, exception.__id__, source]) { ExceptionDetails.extract(exception, source: source) }
|
|
340
|
+
end
|
|
341
|
+
|
|
342
|
+
# Returns [Array<String>] the backtrace of the supplied exception, or nil when it has none.
|
|
343
|
+
#
|
|
344
|
+
# Parameters
|
|
345
|
+
# exception: [Exception]
|
|
346
|
+
# This entry's exception, or one of its causes (see #each_exception).
|
|
347
|
+
# cleaner: [Object|nil]
|
|
348
|
+
# A backtrace cleaner, such as `Rails.backtrace_cleaner`, that responds to `#clean` or
|
|
349
|
+
# `#call`. The backtrace is returned as it cleans it (see BacktraceCleaning.clean), and the
|
|
350
|
+
# exception's own backtrace is left unchanged. Any other value, such as the `true` of the
|
|
351
|
+
# formatter option, is reported to the internal logger as a broken cleaner, and the full
|
|
352
|
+
# backtrace is returned.
|
|
353
|
+
# Default: nil (the exception's own backtrace)
|
|
354
|
+
#
|
|
355
|
+
# A cleaned backtrace is frozen, as are its lines, and cached on this entry, since every
|
|
356
|
+
# appender's formatter may ask for it. Nothing is cached while the exception has no backtrace:
|
|
357
|
+
# one that was never raised can be given one later, as the Bugsnag appender does.
|
|
358
|
+
def backtrace_of(exception, cleaner: nil)
|
|
359
|
+
return exception.backtrace unless cleaner && exception.backtrace
|
|
360
|
+
|
|
361
|
+
cached([:backtrace, exception.__id__, cleaner.__id__]) { BacktraceCleaning.clean(exception.backtrace, cleaner) }
|
|
290
362
|
end
|
|
291
363
|
|
|
292
364
|
# Returns [String] the exception backtrace including all of the child / caused by exceptions
|
|
293
365
|
#
|
|
366
|
+
# When a cleaner is supplied, each backtrace is cleaned by it first (see #backtrace_of).
|
|
367
|
+
#
|
|
294
368
|
# When a block is supplied, each cause's message and each backtrace line is passed
|
|
295
|
-
# to it, and the value it returns is written in its
|
|
296
|
-
# example a formatter, transform that text while this
|
|
369
|
+
# to it, in the order they are written, and the value it returns is written in its
|
|
370
|
+
# place. This lets a caller, for example a formatter, transform that text while this
|
|
371
|
+
# method keeps the layout.
|
|
372
|
+
#
|
|
373
|
+
# Lines are separated by a line break, with none added before the first or after the
|
|
374
|
+
# last, even when an exception in the chain has no backtrace, so that a caller can put
|
|
375
|
+
# the text on the line after its own.
|
|
376
|
+
#
|
|
377
|
+
# Never raises because of what it writes: each cause is named as Utils.exception_name names it,
|
|
378
|
+
# as Ruby names its class, without asking the class, such as `#<Class:0x000...>` for an anonymous
|
|
379
|
+
# class, which has no name; its message is read as Utils.exception_message reads it, so
|
|
380
|
+
# that a #message that raises, or does not return a String, cannot make it raise, nor pass the
|
|
381
|
+
# block anything but a String; and the lines are joined as Utils.join_lines joins them, whatever
|
|
382
|
+
# their encodings.
|
|
297
383
|
#
|
|
298
384
|
# Example:
|
|
299
385
|
# log.backtrace_to_s { |text| text.gsub("\n", "\\n") }
|
|
300
|
-
|
|
301
|
-
|
|
386
|
+
# log.backtrace_to_s(cleaner: Rails.backtrace_cleaner)
|
|
387
|
+
def backtrace_to_s(cleaner: nil, &block)
|
|
388
|
+
lines = []
|
|
302
389
|
each_exception do |exception, i|
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
trace = lines.join("\n")
|
|
307
|
-
else
|
|
308
|
-
message = block ? yield(exception.message) : exception.message
|
|
309
|
-
trace << "\nCause: #{exception.class.name}: #{message}\n#{lines.join("\n")}"
|
|
390
|
+
unless i.zero?
|
|
391
|
+
message = block ? yield(message_of(exception)) : message_of(exception)
|
|
392
|
+
lines << Utils.join_texts("Cause: ", Utils.exception_name(exception), ": ", message)
|
|
310
393
|
end
|
|
394
|
+
backtrace = backtrace_of(exception, cleaner: cleaner) || []
|
|
395
|
+
lines.concat(block ? backtrace.map(&block) : backtrace)
|
|
311
396
|
end
|
|
312
|
-
|
|
397
|
+
Utils.join_lines(lines)
|
|
313
398
|
end
|
|
314
399
|
|
|
315
400
|
# Returns [String] duration of the log entry as a string
|
|
@@ -346,9 +431,7 @@ module SemanticLogger
|
|
|
346
431
|
end
|
|
347
432
|
|
|
348
433
|
# Returns [String] single character upper case log level
|
|
349
|
-
def level_to_s
|
|
350
|
-
level.to_s[0..0].upcase
|
|
351
|
-
end
|
|
434
|
+
def level_to_s = level.to_s[0..0].upcase
|
|
352
435
|
|
|
353
436
|
# DEPRECATED
|
|
354
437
|
def process_info(thread_name_length = 30)
|
|
@@ -358,23 +441,17 @@ module SemanticLogger
|
|
|
358
441
|
"#{$$}:#{format("%.#{thread_name_length}s", thread_name)}#{file_name}"
|
|
359
442
|
end
|
|
360
443
|
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
# Extract the filename and line number from the last entry in the supplied backtrace
|
|
444
|
+
# Extract the file name and line number from the first line of the supplied backtrace.
|
|
364
445
|
def extract_file_and_line(stack, short_name = false)
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
match = CALLER_REGEXP.match(stack.first)
|
|
368
|
-
return unless match
|
|
369
|
-
|
|
370
|
-
[short_name ? File.basename(match[1]) : match[1], match[2].to_i]
|
|
446
|
+
CallSite.parse(stack&.first)&.file_name_and_line(short_name: short_name)
|
|
371
447
|
end
|
|
372
448
|
|
|
373
|
-
# Returns [String,
|
|
374
|
-
#
|
|
449
|
+
# Returns [String, Integer] the file name and line number where the entry was logged: from the call
|
|
450
|
+
# site, or else the first line of the backtrace, or of the exception's backtrace.
|
|
451
|
+
# nil when there are none.
|
|
375
452
|
def file_name_and_line(short_name = false)
|
|
376
|
-
|
|
377
|
-
|
|
453
|
+
call_site&.file_name_and_line(short_name: short_name) ||
|
|
454
|
+
extract_file_and_line(backtrace || exception&.backtrace, short_name)
|
|
378
455
|
end
|
|
379
456
|
|
|
380
457
|
# Strip the standard Rails colorizing from the logged message.
|
|
@@ -401,14 +478,13 @@ module SemanticLogger
|
|
|
401
478
|
# Rendered with #inspect, or with the block when given (for example Amazing Print). A payload
|
|
402
479
|
# nested too deeply for either is first cut off at Utils::MAX_JSON_SAFE_DEPTH, rather than
|
|
403
480
|
# raising SystemStackError (see Utils.safe_inspect).
|
|
404
|
-
def payload_to_s(&)
|
|
405
|
-
Utils.safe_inspect(payload, &) if payload?
|
|
406
|
-
end
|
|
481
|
+
def payload_to_s(&) = (Utils.safe_inspect(payload, &) if payload?)
|
|
407
482
|
|
|
408
483
|
# Returns [true|false] whether the log entry has a payload
|
|
409
|
-
def payload?
|
|
410
|
-
|
|
411
|
-
|
|
484
|
+
def payload? = !(payload.nil? || (payload.respond_to?(:empty?) && payload.empty?))
|
|
485
|
+
|
|
486
|
+
# Returns [true|false] whether the log entry has a metric with dimensions: a Hash that is not empty.
|
|
487
|
+
def dimensions? = metric ? dimensions.is_a?(Hash) && !dimensions.empty? : false
|
|
412
488
|
|
|
413
489
|
def to_h(host = SemanticLogger.host, application = SemanticLogger.application,
|
|
414
490
|
environment = SemanticLogger.environment)
|
|
@@ -417,17 +493,54 @@ module SemanticLogger
|
|
|
417
493
|
end
|
|
418
494
|
|
|
419
495
|
# Lazy initializes the context hash and assigns a key value pair.
|
|
420
|
-
def set_context(key, value)
|
|
421
|
-
|
|
496
|
+
def set_context(key, value) = (self.context ||= {}).store(key, value)
|
|
497
|
+
|
|
498
|
+
# Keeps the value, captured on the logging thread, for the appender that uses it. Unlike the
|
|
499
|
+
# context, formatters do not write it, unless one is built for that appender and reads its key.
|
|
500
|
+
def capture(key, value) = (self.captures ||= {}).store(key, value)
|
|
501
|
+
|
|
502
|
+
# Returns the value captured with the key, or nil when there is none.
|
|
503
|
+
def captured(key) = captures&.[](key)
|
|
504
|
+
|
|
505
|
+
# Replaces this entry's payload, named tags, context, and metric dimensions, the fields that
|
|
506
|
+
# hold keyed data, with copies in which the value of every sensitive key is replaced (see
|
|
507
|
+
# Redactor#redact). Returns self.
|
|
508
|
+
#
|
|
509
|
+
# The values replaced are left as they are, since they can be the application's own, or be
|
|
510
|
+
# shared with other entries, as named tags are. A field with no sensitive key is kept as it is.
|
|
511
|
+
#
|
|
512
|
+
# Called once, before the entry is written to any appender (see SemanticLogger.sensitive_keys=).
|
|
513
|
+
def redact(redactor)
|
|
514
|
+
self.payload = redactor.redact(payload)
|
|
515
|
+
self.named_tags = redactor.redact(named_tags)
|
|
516
|
+
self.context = redactor.redact(context)
|
|
517
|
+
self.dimensions = redactor.redact(dimensions)
|
|
518
|
+
self
|
|
422
519
|
end
|
|
423
520
|
|
|
424
521
|
# A metric only event has a metric but no message or exception.
|
|
425
|
-
def metric_only?
|
|
426
|
-
|
|
522
|
+
def metric_only? = metric && message.nil? && exception.nil?
|
|
523
|
+
|
|
524
|
+
# Replaces the values of this entry that cannot be copied to another Ractor, such as a Proc in its
|
|
525
|
+
# payload (see RactorCopy). Returns self. Experimental, Ruby 4.0 and later only.
|
|
526
|
+
def make_copyable
|
|
527
|
+
%i[message payload tags named_tags context captures metric dimensions].each do |field|
|
|
528
|
+
public_send(:"#{field}=", RactorCopy.copyable(public_send(field)))
|
|
529
|
+
end
|
|
530
|
+
self.exception = RactorCopy.copyable_exception(exception) if exception
|
|
531
|
+
@cache = nil
|
|
532
|
+
self
|
|
427
533
|
end
|
|
428
534
|
|
|
429
535
|
private
|
|
430
536
|
|
|
537
|
+
# Returns [true|false] whether this entry gives a metric a negative amount, which is deprecated (see
|
|
538
|
+
# .negative_metric_amount_deprecated): whether it has a metric and a metric amount that is a real
|
|
539
|
+
# number below zero. Also for a measure_* entry, since SignalFx adds its amount to a counter too.
|
|
540
|
+
# Without a metric no metric subscriber receives the amount. Costs a nil check when there is no
|
|
541
|
+
# metric. Never raises, since Base#backtrace passes its metric_amount to #assign without checking it.
|
|
542
|
+
def counted_negative_amount? = metric && REAL_NUMBER.call(metric_amount) && metric_amount.negative?
|
|
543
|
+
|
|
431
544
|
# Returns the kept payload with the keys of the added one that it does not have, so that a kept
|
|
432
545
|
# value is never replaced. A String and a Symbol key of the same name, such as "account_id" from
|
|
433
546
|
# JSON.parse and :account_id, count as the same key, since the formatters write both under that
|
|
@@ -451,6 +564,49 @@ module SemanticLogger
|
|
|
451
564
|
merged
|
|
452
565
|
end
|
|
453
566
|
|
|
567
|
+
# Returns the value cached on this entry for the key, after caching the value the block returns
|
|
568
|
+
# when there is none yet. Used for values derived from the entry that every appender's formatter
|
|
569
|
+
# may ask for.
|
|
570
|
+
#
|
|
571
|
+
# Keys hold objects by their #__id__, so that no exception's or cleaner's own #eql? or #hash is
|
|
572
|
+
# called: an exception class can define them by value, which would cache two of its exceptions
|
|
573
|
+
# together, and a cleaner, such as a test double, need not define them.
|
|
574
|
+
#
|
|
575
|
+
# The cache is replaced rather than changed, since appenders on other threads may be reading it.
|
|
576
|
+
# Appenders that ask at the same moment can each compute the value, so the block must not rely
|
|
577
|
+
# on being called only once.
|
|
578
|
+
# Once the entry is handed to the appenders the cache only grows, so the entry found by #key? is
|
|
579
|
+
# still there when it is read.
|
|
580
|
+
def cached(key)
|
|
581
|
+
return @cache[key] if @cache&.key?(key)
|
|
582
|
+
|
|
583
|
+
# Merged into the cache as it is now: another appender may have added to it meanwhile.
|
|
584
|
+
yield.tap { |value| @cache = (@cache || {}).merge(key => value).freeze }
|
|
585
|
+
end
|
|
586
|
+
|
|
587
|
+
# Returns [String] the value as text in valid UTF-8 (see Utils.encode_utf8_string).
|
|
588
|
+
def utf8(value) = Utils.encode_utf8_string(value.to_s)
|
|
589
|
+
|
|
590
|
+
# Returns [String] the exception's message, without raising, so that log_exception: :partial
|
|
591
|
+
# never replaces the exception being logged with one that its #message raises (see
|
|
592
|
+
# Utils.exception_message).
|
|
593
|
+
def message_of(exception) = Utils.exception_message(exception)
|
|
594
|
+
|
|
595
|
+
# Returns [String] this entry's message, as log_exception: :partial writes it, followed by the
|
|
596
|
+
# label, the class of the exception, named as Utils.exception_name names it, and any more texts,
|
|
597
|
+
# joined once.
|
|
598
|
+
def with_class(label, exception, *more) = Utils.join_texts(message, label, Utils.exception_name(exception), *more)
|
|
599
|
+
|
|
600
|
+
# Returns [String] this entry's message, as log_exception: :partial writes it, followed by the
|
|
601
|
+
# class of an exception that caused the logged one, then its message (see #with_cause_message).
|
|
602
|
+
def with_cause(cause) = with_cause_message(with_class(" -- Cause: ", cause), message_of(cause))
|
|
603
|
+
|
|
604
|
+
# Returns [String] the text followed by the message of an exception that caused the logged one,
|
|
605
|
+
# or the text alone when it already holds that message: as when the message is empty, is the
|
|
606
|
+
# class name that the text ends with (when the exception was raised without a message), or was
|
|
607
|
+
# copied by the exception that wraps it into its own. Compared as UTF-8, so that it never raises.
|
|
608
|
+
def with_cause_message(text, added) = utf8(text).include?(utf8(added)) ? text : Utils.join_texts(text, ": ", added)
|
|
609
|
+
|
|
454
610
|
# Whether a log argument from the Hash returned by a logging block, already checked by
|
|
455
611
|
# .argument?, is assigned to its attribute: only when this entry does not have it yet. As in
|
|
456
612
|
# #extract_arguments, an empty message counts as none.
|
|
@@ -23,15 +23,9 @@
|
|
|
23
23
|
# end
|
|
24
24
|
# end
|
|
25
25
|
# end
|
|
26
|
-
#
|
|
27
|
-
# Notes:
|
|
28
|
-
# * To forcibly replace Rails or any other existing logging methods
|
|
29
|
-
# use `prepend` instead of `include`. For example:
|
|
30
|
-
# ExternalSupplier.prepend SemanticLogger::Loggable
|
|
31
26
|
module SemanticLogger
|
|
32
27
|
module Loggable
|
|
33
28
|
def self.included(base)
|
|
34
|
-
base.extend ClassMethods
|
|
35
29
|
base.singleton_class.class_eval do
|
|
36
30
|
undef_method :logger if method_defined?(:logger)
|
|
37
31
|
undef_method :logger= if method_defined?(:logger=)
|
|
@@ -42,114 +36,80 @@ module SemanticLogger
|
|
|
42
36
|
|
|
43
37
|
# Returns [SemanticLogger::Logger] class level logger
|
|
44
38
|
def self.logger
|
|
39
|
+
return Loggable.ractor_loggers[self] ||= SemanticLogger[self] if RactorSupport.other_ractor?
|
|
40
|
+
|
|
45
41
|
@semantic_logger ||= SemanticLogger[self]
|
|
46
42
|
end
|
|
47
43
|
|
|
48
44
|
# Replace instance class level logger
|
|
49
45
|
def self.logger=(logger)
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
@semantic_logger ||= self.class.logger
|
|
56
|
-
end
|
|
57
|
-
|
|
58
|
-
# Replace instance level logger
|
|
59
|
-
def logger=(logger)
|
|
60
|
-
@semantic_logger = logger
|
|
46
|
+
if RactorSupport.other_ractor?
|
|
47
|
+
Loggable.ractor_loggers[self] = logger
|
|
48
|
+
else
|
|
49
|
+
@semantic_logger = logger
|
|
50
|
+
end
|
|
61
51
|
end
|
|
62
52
|
end
|
|
63
|
-
end
|
|
64
|
-
|
|
65
|
-
module ClassMethods
|
|
66
|
-
# Measure and log the performance of an instance method.
|
|
67
|
-
#
|
|
68
|
-
# Parameters:
|
|
69
|
-
# method_name: [Symbol]
|
|
70
|
-
# The name of the method that should be measured.
|
|
71
|
-
#
|
|
72
|
-
# options: [Hash]
|
|
73
|
-
# Any valid options that can be passed to measure.
|
|
74
|
-
#
|
|
75
|
-
# Approximate overhead when logging a method call with a metric:
|
|
76
|
-
# 0.044 ms per method call.
|
|
77
|
-
# 0.009 ms per method call. If `min_duration` is not met
|
|
78
|
-
# 0.0005 ms per method call. If `level` is not met
|
|
79
|
-
def logger_measure_method(method_name,
|
|
80
|
-
min_duration: 0.0,
|
|
81
|
-
metric: "#{name}/#{method_name}",
|
|
82
|
-
log_exception: :partial,
|
|
83
|
-
on_exception_level: nil,
|
|
84
|
-
message: "##{method_name}",
|
|
85
|
-
level: :info)
|
|
86
|
-
# unless visibility = Utils.method_visibility(self, method_name)
|
|
87
|
-
# logger.warn("Unable to measure method: #{name}##{method_name} since it does not exist")
|
|
88
|
-
# return false
|
|
89
|
-
# end
|
|
90
53
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
source_name = method_name.to_s.to_sym.inspect.delete_prefix(":")
|
|
98
|
-
if source_name.start_with?('"', "@", "$")
|
|
99
|
-
raise(ArgumentError, "Invalid method name to measure: #{method_name.inspect}")
|
|
100
|
-
end
|
|
101
|
-
unless Log.log_exception_option?(log_exception)
|
|
102
|
-
raise(ArgumentError, "Invalid value:#{log_exception.inspect} for argument :log_exception")
|
|
103
|
-
end
|
|
54
|
+
if base.is_a?(Class)
|
|
55
|
+
base.class_eval do
|
|
56
|
+
# Returns [SemanticLogger::Logger] instance level logger
|
|
57
|
+
def logger
|
|
58
|
+
@semantic_logger ||= self.class.logger
|
|
59
|
+
end
|
|
104
60
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
61
|
+
# Replace instance level logger
|
|
62
|
+
def logger=(logger)
|
|
63
|
+
@semantic_logger = logger
|
|
64
|
+
end
|
|
108
65
|
end
|
|
66
|
+
else
|
|
67
|
+
base.class_eval do
|
|
68
|
+
# Returns [SemanticLogger::Logger] instance level logger
|
|
69
|
+
#
|
|
70
|
+
# The module was included into, or extended, a class that need not include Loggable itself.
|
|
71
|
+
def logger
|
|
72
|
+
return Loggable.ractor_loggers[self] ||= Loggable.logger_for(self) if Loggable.ractor_owned?(self)
|
|
109
73
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
on_exception_level = Levels.level(Levels.index(on_exception_level)) if on_exception_level
|
|
113
|
-
message = message&.to_s
|
|
114
|
-
metric = metric&.to_s
|
|
74
|
+
@semantic_logger ||= Loggable.logger_for(self)
|
|
75
|
+
end
|
|
115
76
|
|
|
116
|
-
|
|
117
|
-
def
|
|
118
|
-
if
|
|
119
|
-
logger
|
|
120
|
-
:measure_method,
|
|
121
|
-
index: #{index},
|
|
122
|
-
level: #{level.inspect},
|
|
123
|
-
message: #{message.inspect},
|
|
124
|
-
min_duration: #{duration},
|
|
125
|
-
metric: #{metric.inspect},
|
|
126
|
-
log_exception: #{log_exception.inspect},
|
|
127
|
-
on_exception_level: #{on_exception_level.inspect}
|
|
128
|
-
) do
|
|
129
|
-
super(*args, &block)
|
|
130
|
-
end
|
|
77
|
+
# Replace instance level logger
|
|
78
|
+
def logger=(logger)
|
|
79
|
+
if Loggable.ractor_owned?(self)
|
|
80
|
+
Loggable.ractor_loggers[self] = logger
|
|
131
81
|
else
|
|
132
|
-
|
|
82
|
+
@semantic_logger = logger
|
|
133
83
|
end
|
|
134
84
|
end
|
|
135
|
-
|
|
136
|
-
# {"#{visibility} :#{method_name}" unless visibility == :public}
|
|
137
|
-
true
|
|
85
|
+
end
|
|
138
86
|
end
|
|
87
|
+
end
|
|
139
88
|
|
|
140
|
-
|
|
89
|
+
# Returns [SemanticLogger::Logger] the logger for an object that uses a module that includes Loggable.
|
|
90
|
+
#
|
|
91
|
+
# A class or module that extended the module has a logger named after itself. An instance uses its
|
|
92
|
+
# class's class level logger when it has one, otherwise one named after its class.
|
|
93
|
+
def self.logger_for(object)
|
|
94
|
+
return SemanticLogger[object] if object.is_a?(Module)
|
|
141
95
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
const_get(:SemanticLoggerMeasure)
|
|
146
|
-
else
|
|
147
|
-
mod = const_set(:SemanticLoggerMeasure, Module.new)
|
|
148
|
-
prepend mod
|
|
96
|
+
klass = object.class
|
|
97
|
+
klass.respond_to?(:logger) ? klass.logger : SemanticLogger[klass]
|
|
98
|
+
end
|
|
149
99
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
100
|
+
# Returns [true|false] whether the logger of the supplied object is held in the current Ractor
|
|
101
|
+
# rather than by the object: a class or module, which a Ractor other than the main one cannot change.
|
|
102
|
+
def self.ractor_owned?(object)
|
|
103
|
+
object.is_a?(Module) && RactorSupport.other_ractor?
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
# Returns [Hash] the class level loggers of the current Ractor, when it is not the main one.
|
|
107
|
+
#
|
|
108
|
+
# A Ractor other than the main one cannot set, or use, the class level logger of the main Ractor,
|
|
109
|
+
# which the class holds, so it has a logger of its own for each class (experimental, Ruby 4.0 and
|
|
110
|
+
# later).
|
|
111
|
+
def self.ractor_loggers
|
|
112
|
+
::Ractor.store_if_absent(:semantic_logger_loggable) { {} }
|
|
153
113
|
end
|
|
154
114
|
end
|
|
155
115
|
end
|