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.
Files changed (98) hide show
  1. checksums.yaml +4 -4
  2. data/docs/api.md +160 -9
  3. data/docs/appenders.md +461 -34
  4. data/docs/config.md +543 -36
  5. data/docs/log.md +38 -7
  6. data/docs/metrics.md +139 -28
  7. data/docs/operations.md +293 -24
  8. data/docs/rails.md +319 -5
  9. data/docs/security.md +135 -107
  10. data/docs/testing.md +23 -0
  11. data/docs/upgrading.md +644 -1
  12. data/lib/semantic_logger/appender/async.rb +29 -11
  13. data/lib/semantic_logger/appender/bugsnag.rb +7 -2
  14. data/lib/semantic_logger/appender/cloudwatch_logs.rb +46 -6
  15. data/lib/semantic_logger/appender/elasticsearch_base.rb +197 -29
  16. data/lib/semantic_logger/appender/elasticsearch_http.rb +22 -5
  17. data/lib/semantic_logger/appender/file.rb +29 -14
  18. data/lib/semantic_logger/appender/graylog.rb +81 -7
  19. data/lib/semantic_logger/appender/honeybadger.rb +7 -1
  20. data/lib/semantic_logger/appender/honeybadger_insights.rb +8 -2
  21. data/lib/semantic_logger/appender/http.rb +244 -41
  22. data/lib/semantic_logger/appender/io.rb +11 -6
  23. data/lib/semantic_logger/appender/kafka.rb +192 -46
  24. data/lib/semantic_logger/appender/loki.rb +42 -6
  25. data/lib/semantic_logger/appender/mongodb.rb +94 -9
  26. data/lib/semantic_logger/appender/new_relic.rb +2 -3
  27. data/lib/semantic_logger/appender/new_relic_logs.rb +30 -8
  28. data/lib/semantic_logger/appender/open_telemetry.rb +37 -35
  29. data/lib/semantic_logger/appender/rabbitmq.rb +241 -17
  30. data/lib/semantic_logger/appender/sentry.rb +2 -3
  31. data/lib/semantic_logger/appender/sentry_ruby.rb +82 -15
  32. data/lib/semantic_logger/appender/splunk.rb +4 -4
  33. data/lib/semantic_logger/appender/splunk_http.rb +92 -1
  34. data/lib/semantic_logger/appender/syslog.rb +89 -10
  35. data/lib/semantic_logger/appender/tcp.rb +68 -98
  36. data/lib/semantic_logger/appender/text_output.rb +65 -0
  37. data/lib/semantic_logger/appender/udp.rb +130 -18
  38. data/lib/semantic_logger/appender/wrapper.rb +10 -7
  39. data/lib/semantic_logger/appender.rb +115 -10
  40. data/lib/semantic_logger/appenders.rb +136 -4
  41. data/lib/semantic_logger/backtrace_cleaning.rb +77 -0
  42. data/lib/semantic_logger/base.rb +53 -71
  43. data/lib/semantic_logger/call_site.rb +235 -0
  44. data/lib/semantic_logger/context.rb +222 -0
  45. data/lib/semantic_logger/core_ext/process.rb +20 -5
  46. data/lib/semantic_logger/core_ext/warning.rb +70 -0
  47. data/lib/semantic_logger/deprecation.rb +139 -0
  48. data/lib/semantic_logger/exception_details.rb +4 -3
  49. data/lib/semantic_logger/formatters/base.rb +139 -19
  50. data/lib/semantic_logger/formatters/color.rb +3 -4
  51. data/lib/semantic_logger/formatters/default.rb +35 -7
  52. data/lib/semantic_logger/formatters/ecs.rb +9 -4
  53. data/lib/semantic_logger/formatters/json.rb +9 -0
  54. data/lib/semantic_logger/formatters/logfmt.rb +9 -7
  55. data/lib/semantic_logger/formatters/loki/labels.rb +282 -0
  56. data/lib/semantic_logger/formatters/loki.rb +412 -24
  57. data/lib/semantic_logger/formatters/new_relic_logs.rb +15 -13
  58. data/lib/semantic_logger/formatters/one_line.rb +44 -10
  59. data/lib/semantic_logger/formatters/open_telemetry.rb +186 -29
  60. data/lib/semantic_logger/formatters/pattern.rb +60 -8
  61. data/lib/semantic_logger/formatters/raw.rb +38 -8
  62. data/lib/semantic_logger/formatters/signalfx.rb +55 -15
  63. data/lib/semantic_logger/formatters/syslog.rb +4 -2
  64. data/lib/semantic_logger/formatters/syslog_cee.rb +10 -4
  65. data/lib/semantic_logger/formatters/syslog_header.rb +49 -0
  66. data/lib/semantic_logger/formatters.rb +1 -0
  67. data/lib/semantic_logger/log.rb +236 -80
  68. data/lib/semantic_logger/loggable.rb +55 -95
  69. data/lib/semantic_logger/logger.rb +31 -5
  70. data/lib/semantic_logger/metric/new_relic.rb +32 -17
  71. data/lib/semantic_logger/metric/signalfx.rb +21 -12
  72. data/lib/semantic_logger/metric/statsd.rb +26 -8
  73. data/lib/semantic_logger/processor.rb +194 -5
  74. data/lib/semantic_logger/queue_processor/backoff.rb +140 -0
  75. data/lib/semantic_logger/queue_processor/batch_failure.rb +69 -0
  76. data/lib/semantic_logger/queue_processor/held_write.rb +62 -0
  77. data/lib/semantic_logger/queue_processor/inbox.rb +97 -0
  78. data/lib/semantic_logger/queue_processor/reopener.rb +56 -0
  79. data/lib/semantic_logger/queue_processor/reporter.rb +113 -0
  80. data/lib/semantic_logger/queue_processor/request.rb +48 -10
  81. data/lib/semantic_logger/queue_processor/throttled_counter.rb +60 -17
  82. data/lib/semantic_logger/queue_processor.rb +426 -176
  83. data/lib/semantic_logger/ractor_copy.rb +120 -0
  84. data/lib/semantic_logger/ractor_processor.rb +82 -0
  85. data/lib/semantic_logger/ractor_receiver.rb +282 -0
  86. data/lib/semantic_logger/ractor_support.rb +28 -0
  87. data/lib/semantic_logger/redactor.rb +310 -0
  88. data/lib/semantic_logger/semantic_logger.rb +313 -79
  89. data/lib/semantic_logger/subscriber.rb +169 -15
  90. data/lib/semantic_logger/sync_processor.rb +226 -26
  91. data/lib/semantic_logger/test/capture_log_events.rb +20 -2
  92. data/lib/semantic_logger/test/minitest.rb +2 -1
  93. data/lib/semantic_logger/test/rspec.rb +1 -1
  94. data/lib/semantic_logger/trap_safe.rb +113 -0
  95. data/lib/semantic_logger/utils.rb +266 -79
  96. data/lib/semantic_logger/version.rb +1 -1
  97. data/lib/semantic_logger.rb +35 -2
  98. 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
@@ -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
- # nil if this logger instance should use the global default level
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 global default level for this logger
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 the global default level.
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
- overrides[self] = index
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
- # # Enable trace level logging
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
- log = Log.new(name, level)
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
- # Allow the global default level to determine this loggers log level
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
- Thread.current[:semantic_logger_with_level]&.[](self)
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) ? (@filter =~ log.name).nil? : @filter.call(log) != true
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
- # current thread context.
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
- message = message.nil? ? payload : "#{message} -- #{payload}"
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 : "#{log.message} -- #{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