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
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
module SemanticLogger
|
|
2
|
+
# Asks an application's backtrace cleaner, such as `Rails.backtrace_cleaner`, to clean a backtrace.
|
|
3
|
+
#
|
|
4
|
+
# A backtrace cleaner is any object that responds to `#clean`, as ActiveSupport::BacktraceCleaner
|
|
5
|
+
# does, or to `#call`, such as a Proc. It is given the backtrace as an Array of Strings, and
|
|
6
|
+
# returns the lines to log in its place: it can leave lines out, and shorten or rewrite them.
|
|
7
|
+
#
|
|
8
|
+
# Internal: Log caches the result for each of its exceptions; see Log#backtrace_of.
|
|
9
|
+
module BacktraceCleaning
|
|
10
|
+
# Returns [true|false] whether the object can clean a backtrace.
|
|
11
|
+
def self.cleaner?(object)
|
|
12
|
+
object.respond_to?(:clean) || object.respond_to?(:call)
|
|
13
|
+
end
|
|
14
|
+
|
|
15
|
+
# Returns the cleaner, for a setting that holds one.
|
|
16
|
+
# Raises ArgumentError when it cannot clean a backtrace (see .cleaner?), naming what the
|
|
17
|
+
# setting expects, since it can accept other values too.
|
|
18
|
+
def self.validate!(cleaner, expected: "a backtrace cleaner")
|
|
19
|
+
return cleaner if cleaner?(cleaner)
|
|
20
|
+
|
|
21
|
+
raise(ArgumentError, "Expected #{expected} that responds to #clean or #call, not #{cleaner.inspect}")
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
# Returns [Array<String>] the backtrace as the cleaner cleans it, or nil when there is none.
|
|
25
|
+
# The Array and its lines are frozen copies, so that every appender can share them.
|
|
26
|
+
#
|
|
27
|
+
# Returns a copy of the supplied backtrace instead when the cleaner leaves out every line, so
|
|
28
|
+
# that the only clue to where an exception came from is never lost, for example an exception
|
|
29
|
+
# raised entirely within gems that a cleaner silences. Also when the cleaner does not return an
|
|
30
|
+
# Array of lines, or raises a StandardError, such as for an object that is not a cleaner, so
|
|
31
|
+
# that a cleaner cannot stop a log entry being written. The error is reported to the internal
|
|
32
|
+
# logger, since nothing else would show that the cleaner is broken.
|
|
33
|
+
#
|
|
34
|
+
# The cleaner is given a copy of the backtrace, which it may change, since the supplied one
|
|
35
|
+
# belongs to the exception, and other appenders, such as error services, also read it.
|
|
36
|
+
def self.clean(backtrace, cleaner)
|
|
37
|
+
return if backtrace.nil?
|
|
38
|
+
|
|
39
|
+
cleaned_lines(backtrace, cleaner) || frozen_copy(backtrace)
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
# Returns [Array<String>] a frozen copy of the lines the cleaner keeps, or nil when it keeps
|
|
43
|
+
# none, does not return an Array of lines, or raises.
|
|
44
|
+
def self.cleaned_lines(backtrace, cleaner)
|
|
45
|
+
return if backtrace.empty?
|
|
46
|
+
|
|
47
|
+
lines = backtrace.dup
|
|
48
|
+
cleaned = cleaner.respond_to?(:clean) ? cleaner.clean(lines) : cleaner.call(lines)
|
|
49
|
+
frozen_copy(cleaned) if cleaned.is_a?(Array) && !cleaned.empty?
|
|
50
|
+
rescue StandardError => e
|
|
51
|
+
report(e)
|
|
52
|
+
nil
|
|
53
|
+
end
|
|
54
|
+
private_class_method :cleaned_lines
|
|
55
|
+
|
|
56
|
+
# Returns [Array<String>] a frozen copy of the lines, each a frozen copy too, which leaves the
|
|
57
|
+
# supplied lines, such as the exception's own, unchanged. A cleaner can return
|
|
58
|
+
# Thread::Backtrace::Location objects, or Strings of its own.
|
|
59
|
+
def self.frozen_copy(lines)
|
|
60
|
+
lines.map { |line| String.new(line.to_s).freeze }.freeze
|
|
61
|
+
end
|
|
62
|
+
private_class_method :frozen_copy
|
|
63
|
+
|
|
64
|
+
# Reports an error raised by a cleaner to the internal logger, as text: given the exception
|
|
65
|
+
# itself, the internal logger's formatter would ask the same cleaner to clean its backtrace.
|
|
66
|
+
def self.report(exception)
|
|
67
|
+
where = exception.backtrace&.first
|
|
68
|
+
Logger.processor.logger.warn(
|
|
69
|
+
"Backtrace cleaner raised #{Utils.exception_name(exception)}: #{Utils.exception_message(exception)}" \
|
|
70
|
+
"#{" (#{where})" if where}, so the full backtrace is logged"
|
|
71
|
+
)
|
|
72
|
+
rescue StandardError
|
|
73
|
+
nil
|
|
74
|
+
end
|
|
75
|
+
private_class_method :report
|
|
76
|
+
end
|
|
77
|
+
end
|
data/lib/semantic_logger/base.rb
CHANGED
|
@@ -15,11 +15,11 @@ module SemanticLogger
|
|
|
15
15
|
# the log level in any logging instance or the default log level
|
|
16
16
|
# SemanticLogger.default_level
|
|
17
17
|
#
|
|
18
|
-
# Must be one of the values in SemanticLogger::LEVELS, or
|
|
19
|
-
#
|
|
18
|
+
# Must be one of the values in SemanticLogger::LEVELS, or nil to use this instance's fallback
|
|
19
|
+
# level (see #fallback_level).
|
|
20
20
|
def level=(level)
|
|
21
21
|
if level.nil?
|
|
22
|
-
# Use the
|
|
22
|
+
# Use the fallback level for this instance (see #fallback_level)
|
|
23
23
|
@level_index = nil
|
|
24
24
|
@level = nil
|
|
25
25
|
else
|
|
@@ -29,7 +29,7 @@ module SemanticLogger
|
|
|
29
29
|
end
|
|
30
30
|
|
|
31
31
|
# Returns the level set by an enclosing `#with_level` block on the current fiber,
|
|
32
|
-
# otherwise the level set for this instance, otherwise
|
|
32
|
+
# otherwise the level set for this instance, otherwise its fallback level (see #fallback_level).
|
|
33
33
|
def level
|
|
34
34
|
index = @with_level_used && with_level_index
|
|
35
35
|
return Levels.level(index) if index
|
|
@@ -45,21 +45,10 @@ module SemanticLogger
|
|
|
45
45
|
#
|
|
46
46
|
# Matches Ruby's `Logger#with_level`, which Sidekiq calls to apply a job's `log_level`.
|
|
47
47
|
# Accepts the same levels as `#level=`. Returns the result of the block.
|
|
48
|
-
def with_level(level)
|
|
48
|
+
def with_level(level, &)
|
|
49
49
|
index = Levels.index(level)
|
|
50
|
-
overrides = (Thread.current[:semantic_logger_with_level] ||= {}.compare_by_identity)
|
|
51
|
-
previous = overrides[self]
|
|
52
50
|
@with_level_used = true
|
|
53
|
-
|
|
54
|
-
begin
|
|
55
|
-
yield
|
|
56
|
-
ensure
|
|
57
|
-
if previous
|
|
58
|
-
overrides[self] = previous
|
|
59
|
-
else
|
|
60
|
-
overrides.delete(self)
|
|
61
|
-
end
|
|
62
|
-
end
|
|
51
|
+
Context.with_level(self, index, &)
|
|
63
52
|
end
|
|
64
53
|
|
|
65
54
|
# Implement the log level calls
|
|
@@ -87,7 +76,7 @@ module SemanticLogger
|
|
|
87
76
|
# Examples:
|
|
88
77
|
# require 'semantic_logger'
|
|
89
78
|
#
|
|
90
|
-
# #
|
|
79
|
+
# # Log :info and above
|
|
91
80
|
# SemanticLogger.default_level = :info
|
|
92
81
|
#
|
|
93
82
|
# # Log to screen
|
|
@@ -158,18 +147,11 @@ module SemanticLogger
|
|
|
158
147
|
payload: nil,
|
|
159
148
|
metric: nil,
|
|
160
149
|
metric_amount: nil)
|
|
161
|
-
|
|
150
|
+
# The entry has the name, tags, and named tags of the thread whose backtrace it logs.
|
|
151
|
+
log = new_log(level, nil, thread)
|
|
162
152
|
return false unless meets_log_level?(log)
|
|
163
153
|
|
|
164
|
-
backtrace =
|
|
165
|
-
if thread == Thread.current
|
|
166
|
-
Utils.extract_backtrace(caller)
|
|
167
|
-
else
|
|
168
|
-
log.thread_name = Log.thread_name_for(thread)
|
|
169
|
-
log.tags = (thread[:semantic_logger_tags] || []).clone
|
|
170
|
-
log.named_tags = (thread[:semantic_logger_named_tags] || {}).clone
|
|
171
|
-
thread.backtrace
|
|
172
|
-
end
|
|
154
|
+
backtrace = thread == Thread.current ? Utils.extract_backtrace(caller) : thread.backtrace
|
|
173
155
|
if backtrace
|
|
174
156
|
message += "\n"
|
|
175
157
|
message << backtrace.join("\n")
|
|
@@ -339,7 +321,7 @@ module SemanticLogger
|
|
|
339
321
|
# that sets an override needs to see the flag, and that fiber set it itself.
|
|
340
322
|
@with_level_used = false
|
|
341
323
|
if level.nil?
|
|
342
|
-
#
|
|
324
|
+
# Use the fallback level for this instance (see #fallback_level)
|
|
343
325
|
@level_index = nil
|
|
344
326
|
@level = nil
|
|
345
327
|
else
|
|
@@ -365,14 +347,41 @@ module SemanticLogger
|
|
|
365
347
|
|
|
366
348
|
# Level index set for this instance by an enclosing `#with_level` block on the current fiber.
|
|
367
349
|
def with_level_index
|
|
368
|
-
|
|
350
|
+
Context.with_level_index(self)
|
|
369
351
|
end
|
|
370
352
|
|
|
371
353
|
# Whether to log the supplied message based on the current filter if any
|
|
372
354
|
def filtered?(log)
|
|
373
355
|
return false if @filter.nil?
|
|
374
356
|
|
|
375
|
-
@filter.is_a?(Regexp) ? (
|
|
357
|
+
@filter.is_a?(Regexp) ? !name_matches_filter?(log.name) : @filter.call(log) != true
|
|
358
|
+
end
|
|
359
|
+
|
|
360
|
+
# Whether the name matches the Regexp filter. A name that is not valid in its encoding, or is
|
|
361
|
+
# not ASCII-compatible, which matching raises for, is matched converted to valid UTF-8 (see
|
|
362
|
+
# Utils.encode_utf8_string), since a log call must not raise.
|
|
363
|
+
def name_matches_filter?(name)
|
|
364
|
+
@filter.match?(name)
|
|
365
|
+
rescue ArgumentError, EncodingError
|
|
366
|
+
utf8_name_matches_filter?(Utils.encode_utf8_string(name.to_s))
|
|
367
|
+
end
|
|
368
|
+
|
|
369
|
+
# Whether the Regexp filter matches the name, which is valid UTF-8. A Regexp fixed to another
|
|
370
|
+
# encoding, such as one that holds characters outside ASCII written in a source file in
|
|
371
|
+
# ISO-8859-1, cannot match UTF-8 text, so it matches the name in its own encoding: as bytes for
|
|
372
|
+
# a binary Regexp, otherwise converted, with "?" for a character the encoding does not have. A
|
|
373
|
+
# name that it still cannot match, such as for an encoding with no converter from UTF-8, does
|
|
374
|
+
# not match.
|
|
375
|
+
def utf8_name_matches_filter?(name)
|
|
376
|
+
@filter.match?(name)
|
|
377
|
+
rescue ArgumentError, EncodingError
|
|
378
|
+
encoding = @filter.encoding
|
|
379
|
+
begin
|
|
380
|
+
text = encoding == Encoding::BINARY ? name.b : name.encode(encoding, invalid: :replace, undef: :replace)
|
|
381
|
+
@filter.match?(text)
|
|
382
|
+
rescue ArgumentError, EncodingError
|
|
383
|
+
false
|
|
384
|
+
end
|
|
376
385
|
end
|
|
377
386
|
|
|
378
387
|
# Ensure minimum log level is met
|
|
@@ -381,9 +390,9 @@ module SemanticLogger
|
|
|
381
390
|
end
|
|
382
391
|
|
|
383
392
|
# Build a new Log entry, layering this logger's instance tags on top of the
|
|
384
|
-
#
|
|
385
|
-
def new_log(level, index = nil)
|
|
386
|
-
apply_instance_tags(Log.new(name, level, index))
|
|
393
|
+
# context of the thread, by default the current one.
|
|
394
|
+
def new_log(level, index = nil, thread = Thread.current)
|
|
395
|
+
apply_instance_tags(Log.new(name, level, index, thread))
|
|
387
396
|
end
|
|
388
397
|
|
|
389
398
|
# Merge this logger's instance tags into the supplied Log entry.
|
|
@@ -436,7 +445,9 @@ module SemanticLogger
|
|
|
436
445
|
exception = payload
|
|
437
446
|
payload = nil
|
|
438
447
|
elsif payload && !payload.is_a?(Hash)
|
|
439
|
-
|
|
448
|
+
# Joined so that texts in incompatible encodings, such as a UTF-8 message and a binary
|
|
449
|
+
# response body, cannot make the log call raise (see Utils.join_texts).
|
|
450
|
+
message = message.nil? ? payload : Utils.join_texts(message, " -- ", payload)
|
|
440
451
|
payload = nil
|
|
441
452
|
end
|
|
442
453
|
|
|
@@ -466,11 +477,14 @@ module SemanticLogger
|
|
|
466
477
|
# arguments. Lambdas enforce their arity, so yielding the log to a zero-arity lambda would
|
|
467
478
|
# raise ArgumentError. Blocks that accept an argument still receive the log so they can read
|
|
468
479
|
# or mutate it.
|
|
480
|
+
#
|
|
481
|
+
# A String result is joined to the message with Utils.join_texts, so that texts in incompatible
|
|
482
|
+
# encodings, such as a UTF-8 message and a binary block result, cannot make the log call raise.
|
|
469
483
|
def apply_block_result(log, &block)
|
|
470
484
|
result = block.arity.zero? ? block.call : block.call(log)
|
|
471
485
|
case result
|
|
472
486
|
when String
|
|
473
|
-
log.message = log.message.nil? ? result :
|
|
487
|
+
log.message = log.message.nil? ? result : Utils.join_texts(log.message, " -- ", result)
|
|
474
488
|
when Hash
|
|
475
489
|
log.assign_hash(result)
|
|
476
490
|
end
|
|
@@ -523,9 +537,11 @@ module SemanticLogger
|
|
|
523
537
|
exception: exception,
|
|
524
538
|
metric: measure_option(params, :metric),
|
|
525
539
|
metric_amount: measure_option(params, :metric_amount),
|
|
540
|
+
dimensions: measure_option(params, :dimensions),
|
|
526
541
|
duration: duration,
|
|
527
542
|
log_exception: measure_option(params, :log_exception) || :partial,
|
|
528
|
-
on_exception_level: measure_option(params, :on_exception_level)
|
|
543
|
+
on_exception_level: measure_option(params, :on_exception_level),
|
|
544
|
+
call_site: measure_option(params, :call_site)
|
|
529
545
|
)
|
|
530
546
|
|
|
531
547
|
# Log level may change during assign due to :on_exception_level
|
|
@@ -549,39 +565,5 @@ module SemanticLogger
|
|
|
549
565
|
silence_level = :error if silence_level == true
|
|
550
566
|
silence_level if Levels.valid?(silence_level)
|
|
551
567
|
end
|
|
552
|
-
|
|
553
|
-
# For measuring methods and logging their duration.
|
|
554
|
-
def measure_method(index:,
|
|
555
|
-
level:,
|
|
556
|
-
message:,
|
|
557
|
-
min_duration:,
|
|
558
|
-
metric:,
|
|
559
|
-
log_exception:,
|
|
560
|
-
on_exception_level:)
|
|
561
|
-
# Ignores filter, silence, payload
|
|
562
|
-
exception = nil
|
|
563
|
-
start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
|
|
564
|
-
begin
|
|
565
|
-
yield
|
|
566
|
-
rescue Exception => e
|
|
567
|
-
exception = e
|
|
568
|
-
ensure
|
|
569
|
-
log = new_log(level, index)
|
|
570
|
-
# May return false due to elastic logging
|
|
571
|
-
should_log = log.assign(
|
|
572
|
-
message: message,
|
|
573
|
-
min_duration: min_duration,
|
|
574
|
-
exception: exception,
|
|
575
|
-
metric: metric,
|
|
576
|
-
duration: 1_000.0 * (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start),
|
|
577
|
-
log_exception: log_exception,
|
|
578
|
-
on_exception_level: on_exception_level
|
|
579
|
-
)
|
|
580
|
-
|
|
581
|
-
# Log level may change during assign due to :on_exception_level
|
|
582
|
-
log(log) if should_log && should_log?(log)
|
|
583
|
-
raise exception if exception
|
|
584
|
-
end
|
|
585
|
-
end
|
|
586
568
|
end
|
|
587
569
|
end
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
module SemanticLogger
|
|
2
|
+
# Where a log entry was logged: the path and line of the code that made the log call, and the
|
|
3
|
+
# label of its frame, usually the method, such as "Order#submit".
|
|
4
|
+
#
|
|
5
|
+
# Log#assign sets it when the entry's level is at or above SemanticLogger.call_site_level. When the
|
|
6
|
+
# log call supplies a backtrace, the call site is its first line. Otherwise it is the first frame of
|
|
7
|
+
# the calling thread's stack outside Semantic Logger and SemanticLogger.call_site_skip_paths, which
|
|
8
|
+
# costs far less than capturing a backtrace, since only the frames up to it are read.
|
|
9
|
+
#
|
|
10
|
+
# A call site is frozen and holds only frozen Strings and an Integer, so that a log entry logged in
|
|
11
|
+
# another Ractor can be sent to the main one.
|
|
12
|
+
#
|
|
13
|
+
# Attributes:
|
|
14
|
+
# path: [String]
|
|
15
|
+
# The file, as in a backtrace, such as "/app/models/order.rb".
|
|
16
|
+
# line: [Integer]
|
|
17
|
+
# The line number in the file.
|
|
18
|
+
# label: [String|nil]
|
|
19
|
+
# The label of the frame, as in a backtrace. On Ruby 3.4 and later it includes the class, such
|
|
20
|
+
# as "Order#submit" or "Order.find_open", on Ruby 3.2 and 3.3 only the method, such as "submit".
|
|
21
|
+
# A block's label starts with "block in", and code outside a method has a label such as
|
|
22
|
+
# "<main>" or "<class:Order>".
|
|
23
|
+
CallSite = Data.define(:path, :line, :label)
|
|
24
|
+
|
|
25
|
+
class CallSite
|
|
26
|
+
# The number of frames read from the stack at a time. Semantic Logger's own frames, which are
|
|
27
|
+
# skipped, are usually fewer than this.
|
|
28
|
+
WINDOW = 8
|
|
29
|
+
private_constant :WINDOW
|
|
30
|
+
|
|
31
|
+
# Paths of the frames of Ruby's own methods written in Ruby, such as "<internal:kernel>", which are
|
|
32
|
+
# never the code that logged the entry. Which methods these are depends on the version of Ruby.
|
|
33
|
+
INTERNAL_PATH = "<internal:".freeze
|
|
34
|
+
private_constant :INTERNAL_PATH
|
|
35
|
+
|
|
36
|
+
# Labels of Ruby's methods that call a method for their caller, such as
|
|
37
|
+
# `logger.public_send(level, message)`, and add a frame of their own with the caller's path and
|
|
38
|
+
# line.
|
|
39
|
+
#
|
|
40
|
+
# CRuby 3.4 and later include the class in the label, which tells these methods apart from an
|
|
41
|
+
# application's own methods of the same name. JRuby, and CRuby before 3.4, do not, so there an
|
|
42
|
+
# application's own `call` method is also skipped when it was called from the same line of the
|
|
43
|
+
# same file, such as by recursion or a one-line definition. The path and line stay the same; only
|
|
44
|
+
# the label becomes the caller's. JRuby labels the frame "block in public_send" when it is called
|
|
45
|
+
# in a block. "block in call" is left out, since it is also the label of a block in an
|
|
46
|
+
# application's own `call` method.
|
|
47
|
+
DISPATCH_LABELS = Utils.make_shareable(
|
|
48
|
+
if RUBY_ENGINE == "ruby" && RUBY_VERSION >= "3.4"
|
|
49
|
+
%w[Kernel#public_send Method#call UnboundMethod#bind_call].freeze
|
|
50
|
+
else
|
|
51
|
+
["public_send", "call", "bind_call", "block in public_send", "block in bind_call"].freeze
|
|
52
|
+
end
|
|
53
|
+
)
|
|
54
|
+
private_constant :DISPATCH_LABELS
|
|
55
|
+
|
|
56
|
+
# The line number and the start of the label in a backtrace line, such as ":12:in 'Order#submit'",
|
|
57
|
+
# or as Ruby 3.3 and earlier write it, ":12:in `submit'". Without a leading `.*`, so that matching an
|
|
58
|
+
# untrusted line takes linear time on every Ruby, including JRuby, which has no backtracking limits.
|
|
59
|
+
# A line number has at most 10 digits, since a longer one, which only a forged line has, would be
|
|
60
|
+
# slow to convert to an Integer and back.
|
|
61
|
+
LINE_AND_LABEL = /:(\d{1,10}):in [`']/
|
|
62
|
+
private_constant :LINE_AND_LABEL
|
|
63
|
+
|
|
64
|
+
# A backtrace line without a label, such as "app.rb:12".
|
|
65
|
+
UNLABELED_LINE = /\A(.+):(\d{1,10})(?!\d)/
|
|
66
|
+
private_constant :UNLABELED_LINE
|
|
67
|
+
|
|
68
|
+
# A line break, which only a forged backtrace line holds.
|
|
69
|
+
LINE_BREAK = "\n".freeze
|
|
70
|
+
private_constant :LINE_BREAK
|
|
71
|
+
|
|
72
|
+
# A label's closing quote.
|
|
73
|
+
QUOTE = "'".freeze
|
|
74
|
+
private_constant :QUOTE
|
|
75
|
+
|
|
76
|
+
# Returns [CallSite|nil] where a log entry was logged, from what the log call supplied:
|
|
77
|
+
# call_site: [CallSite|Thread::Backtrace::Location|false|nil]
|
|
78
|
+
# The call site, or the frame it is made from. false: the entry has no call site.
|
|
79
|
+
# backtrace: [Array<String>|nil]
|
|
80
|
+
# Without a call site, its first line is the call site.
|
|
81
|
+
# Without either (or with an empty backtrace), the first frame of the calling thread's stack
|
|
82
|
+
# outside Semantic Logger (see .capture).
|
|
83
|
+
def self.locate(call_site: nil, backtrace: nil)
|
|
84
|
+
return if false.equal?(call_site)
|
|
85
|
+
return from(call_site) if call_site
|
|
86
|
+
|
|
87
|
+
backtrace.nil? || backtrace.empty? ? capture : parse(backtrace.first)
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
# Returns [CallSite] the call site, or the call site of a Thread::Backtrace::Location. A call site
|
|
91
|
+
# whose Strings are frozen is returned as it is; otherwise its Strings are copied, frozen and
|
|
92
|
+
# deduplicated, since the same few paths and labels are logged again and again.
|
|
93
|
+
def self.from(call_site)
|
|
94
|
+
is_call_site = CallSite === call_site # rubocop:disable Style/CaseEquality
|
|
95
|
+
return call_site if is_call_site && call_site.path.frozen? && (call_site.label.nil? || call_site.label.frozen?)
|
|
96
|
+
|
|
97
|
+
label = call_site.label
|
|
98
|
+
new(frozen_copy(call_site.path), is_call_site ? call_site.line : call_site.lineno, label && frozen_copy(label))
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
# Returns [String] a frozen, deduplicated copy of the String, or the String when it is already one.
|
|
102
|
+
# A subclass of String is copied to a String first, since JRuby freezes it in place instead.
|
|
103
|
+
def self.frozen_copy(string)
|
|
104
|
+
string.instance_of?(String) ? -string : -String.new(string)
|
|
105
|
+
end
|
|
106
|
+
private_class_method :frozen_copy
|
|
107
|
+
|
|
108
|
+
# Whether the value can be supplied as a log entry's call site (see .locate). A value that parsed
|
|
109
|
+
# data, such as JSON, can hold is not, other than false, so that untrusted data cannot set the
|
|
110
|
+
# location of an entry. Never calls a method of the value, which can be any object in a payload.
|
|
111
|
+
def self.supplied?(value)
|
|
112
|
+
return true if false.equal?(value) || ::Thread::Backtrace::Location === value # rubocop:disable Style/CaseEquality
|
|
113
|
+
|
|
114
|
+
CallSite === value && value.well_formed? # rubocop:disable Style/CaseEquality
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
# Returns [CallSite|nil] the first frame of the calling thread's stack outside Semantic Logger, Ruby's
|
|
118
|
+
# own methods, and SemanticLogger.call_site_skip_paths, and other than the frame of a method such
|
|
119
|
+
# as public_send that called the logger for it. nil when every frame is skipped.
|
|
120
|
+
def self.capture
|
|
121
|
+
skip_paths = SemanticLogger.call_site_skip_paths
|
|
122
|
+
# A Ractor other than the main one cannot use the main Ractor's cache.
|
|
123
|
+
cache = RactorSupport.other_ractor? ? nil : skip_cache(skip_paths)
|
|
124
|
+
start = 1
|
|
125
|
+
# One frame more than the window, which is only read as the caller of the frame before it.
|
|
126
|
+
# caller_locations returns nil, or on JRuby an empty Array, once start is past the end of the stack.
|
|
127
|
+
while (locations = caller_locations(start, WINDOW + 1)) && !locations.empty?
|
|
128
|
+
locations.each_with_index do |location, index|
|
|
129
|
+
break if index == WINDOW
|
|
130
|
+
|
|
131
|
+
path = location.path
|
|
132
|
+
next if skip?(path, skip_paths, cache)
|
|
133
|
+
|
|
134
|
+
label = location.label
|
|
135
|
+
next if dispatch?(location, label, locations[index + 1])
|
|
136
|
+
|
|
137
|
+
return new(-path, location.lineno, label && -label)
|
|
138
|
+
end
|
|
139
|
+
start += WINDOW
|
|
140
|
+
end
|
|
141
|
+
end
|
|
142
|
+
|
|
143
|
+
# Returns [CallSite|nil] the call site in a line of a backtrace, such as
|
|
144
|
+
# "app.rb:12:in 'Order#submit'". nil when the line is not a String with a path and line number,
|
|
145
|
+
# or is not text that Ruby can match, such as invalid UTF-8.
|
|
146
|
+
def self.parse(line)
|
|
147
|
+
return unless line.is_a?(String) && line.encoding.ascii_compatible? && line.valid_encoding?
|
|
148
|
+
return if line.include?(LINE_BREAK)
|
|
149
|
+
|
|
150
|
+
# The first ":12:in '" is the end of the path, since a label can hold anything. The label's
|
|
151
|
+
# closing quote must follow its opening one.
|
|
152
|
+
match = LINE_AND_LABEL.match(line) if line.end_with?(QUOTE)
|
|
153
|
+
if match&.begin(0)&.positive? && match.end(0) < line.size
|
|
154
|
+
return new(-match.pre_match, match[1].to_i, -line[match.end(0)...-1])
|
|
155
|
+
end
|
|
156
|
+
|
|
157
|
+
match = UNLABELED_LINE.match(line)
|
|
158
|
+
new(-match[1], match[2].to_i, nil) if match
|
|
159
|
+
end
|
|
160
|
+
|
|
161
|
+
# Whether a frame in the file at this path is skipped when capturing a call site.
|
|
162
|
+
#
|
|
163
|
+
# The frames of log calls come from a few files, Semantic Logger's own and the application's, so
|
|
164
|
+
# the answer is remembered in the cache for each path, which is faster than matching the path
|
|
165
|
+
# again. Without a cache, the path is matched each time.
|
|
166
|
+
#
|
|
167
|
+
# In a signal trap, the answer for a path not yet in the cache is not remembered, since writing to
|
|
168
|
+
# the cache locks a Mutex on CRuby, which Ruby does not allow there.
|
|
169
|
+
def self.skip?(path, skip_paths, cache)
|
|
170
|
+
return skip_path?(path, skip_paths) unless cache
|
|
171
|
+
|
|
172
|
+
skipped = cache[path]
|
|
173
|
+
return skipped unless skipped.nil?
|
|
174
|
+
|
|
175
|
+
skipped = skip_path?(path, skip_paths)
|
|
176
|
+
return skipped if TrapSafe.in_trap?
|
|
177
|
+
|
|
178
|
+
# Bounded, since code evaluated at runtime can have a path of its own each time.
|
|
179
|
+
cache.clear if cache.size >= MAX_CACHED_PATHS
|
|
180
|
+
cache[path] = skipped
|
|
181
|
+
end
|
|
182
|
+
private_class_method :skip?
|
|
183
|
+
|
|
184
|
+
# The most paths whose answer .skip? remembers.
|
|
185
|
+
MAX_CACHED_PATHS = 1_000
|
|
186
|
+
private_constant :MAX_CACHED_PATHS
|
|
187
|
+
|
|
188
|
+
# Returns [Concurrent::Map] whether each path is skipped, for these skip paths. A new one when the
|
|
189
|
+
# skip paths have changed.
|
|
190
|
+
def self.skip_cache(skip_paths)
|
|
191
|
+
cache = @skip_cache
|
|
192
|
+
return cache.last if cache&.first.equal?(skip_paths)
|
|
193
|
+
|
|
194
|
+
(@skip_cache = [skip_paths, Concurrent::Map.new]).last
|
|
195
|
+
end
|
|
196
|
+
private_class_method :skip_cache
|
|
197
|
+
|
|
198
|
+
# Whether the frame is that of a method such as public_send, called by the frame after it, which
|
|
199
|
+
# has the same path and line. Then the frame after it made the log call.
|
|
200
|
+
def self.dispatch?(location, label, caller_location)
|
|
201
|
+
DISPATCH_LABELS.include?(label) && !caller_location.nil? &&
|
|
202
|
+
caller_location.lineno == location.lineno && caller_location.path == location.path
|
|
203
|
+
end
|
|
204
|
+
private_class_method :dispatch?
|
|
205
|
+
|
|
206
|
+
def self.skip_path?(path, skip_paths)
|
|
207
|
+
return true if path.start_with?(INTERNAL_PATH) || Utils.extract_path?(path)
|
|
208
|
+
|
|
209
|
+
skip_paths.any? { |skip_path| path.include?(skip_path) }
|
|
210
|
+
end
|
|
211
|
+
private_class_method :skip_path?
|
|
212
|
+
|
|
213
|
+
# Whether the path is a String, the line an Integer, and the label a String or nil, as the
|
|
214
|
+
# formatters need. A call site that Semantic Logger makes always is; one that a log call supplies
|
|
215
|
+
# is checked, and otherwise logged as part of the payload, like any other value that is not valid
|
|
216
|
+
# for its argument.
|
|
217
|
+
#
|
|
218
|
+
# Like .supplied?, calls no method of the values, which can be any objects.
|
|
219
|
+
def well_formed?
|
|
220
|
+
String === path && Integer === line && (nil.equal?(label) || String === label) # rubocop:disable Style/CaseEquality
|
|
221
|
+
end
|
|
222
|
+
|
|
223
|
+
# Returns [Array<String, Integer>] the file name and line number of the call site. With short_name
|
|
224
|
+
# the file name has no directory, such as "order.rb".
|
|
225
|
+
def file_name_and_line(short_name: false)
|
|
226
|
+
[short_name ? File.basename(path) : path, line]
|
|
227
|
+
end
|
|
228
|
+
|
|
229
|
+
# Returns [String] the call site as Ruby 3.4 and later write it in a backtrace, such as
|
|
230
|
+
# "/app/models/order.rb:42:in 'Order#submit'".
|
|
231
|
+
def to_s
|
|
232
|
+
label ? "#{path}:#{line}:in '#{label}'" : "#{path}:#{line}"
|
|
233
|
+
end
|
|
234
|
+
end
|
|
235
|
+
end
|