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
@@ -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 exception
53
- duration min_duration
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
- backtrace: ->(value) { value.is_a?(Array) && value.all?(String) },
69
- duration: REAL_NUMBER,
70
- min_duration: REAL_NUMBER,
71
- metric_amount: REAL_NUMBER,
72
- dimensions: ->(value) { value.is_a?(Hash) },
73
- log_exception: ->(value) { LOG_EXCEPTION_OPTIONS.include?(value) },
74
- on_exception_level: ->(value) { Levels.valid?(value) }
75
- }.freeze
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
- def initialize(name, level, index = nil)
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(Thread.current)
113
+ @thread_name = Log.thread_name_for(thread)
99
114
  @name = name
100
115
  @time = Time.now
101
- @tags = SemanticLogger.tags
102
- @named_tags = SemanticLogger.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
- self.message = "#{message} -- Exception: #{exception.class}: #{exception.message}"
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
- def each_exception
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 = exception
305
+ ex = first
248
306
  while !ex.nil? && !exceptions.include?(ex) && exceptions.length < MAX_EXCEPTIONS_TO_UNWRAP
249
307
  exceptions << ex
250
- yield(ex, depth)
308
+ yield(ex, exceptions.length - 1)
251
309
 
252
- depth += 1
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
- key = [exception, source]
283
- cache = @exception_details
284
- return cache[key] if cache&.key?(key)
285
-
286
- details = ExceptionDetails.extract(exception, source: source)
287
- # Replace the cache rather than change it, since appenders on other threads may be reading it.
288
- @exception_details = (cache || {}).merge(key => details).freeze
289
- details
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 place. This lets a caller, for
296
- # example a formatter, transform that text while this method keeps the layout.
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
- def backtrace_to_s(&block)
301
- trace = ""
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
- lines = exception.backtrace || []
304
- lines = lines.map(&block) if block
305
- if i.zero?
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
- trace
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
- CALLER_REGEXP = /^(.*):(\d+).*/
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
- return unless stack&.size&.positive?
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, String] the file_name and line_number from the backtrace supplied
374
- # in either the backtrace or exception
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
- stack = backtrace || exception&.backtrace
377
- extract_file_and_line(stack, short_name)
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
- !(payload.nil? || (payload.respond_to?(:empty?) && payload.empty?))
411
- end
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
- (self.context ||= {})[key] = value
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
- metric && message.nil? && exception.nil?
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
- @semantic_logger = logger
51
- end
52
-
53
- # Returns [SemanticLogger::Logger] instance level logger
54
- def logger
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
- # These values are written into the source of the generated method, so only accept values
92
- # that are certain to produce valid literals, rather than code.
93
- #
94
- # Ruby writes a Symbol that is a valid method name, including operators such as `[]=` and
95
- # non-ASCII identifiers, without quotes. Any other Symbol is quoted, as in `:"a; b"`.
96
- # Instance, class, and global variable names are unquoted, but are not method names.
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
- duration = Float(min_duration, exception: false)
106
- unless duration&.finite?
107
- raise(ArgumentError, "Invalid value:#{min_duration.inspect} for argument :min_duration")
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
- index = Levels.index(level)
111
- level = Levels.level(index)
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
- logger_measure_module.module_eval(<<~MEASURE_METHOD, __FILE__, __LINE__ + 1)
117
- def #{source_name}(*args, &block)
118
- if logger.send(:level_index) <= #{index}
119
- logger.send(
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
- super(*args, &block)
82
+ @semantic_logger = logger
133
83
  end
134
84
  end
135
- MEASURE_METHOD
136
- # {"#{visibility} :#{method_name}" unless visibility == :public}
137
- true
85
+ end
138
86
  end
87
+ end
139
88
 
140
- private
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
- # Dynamic Module to intercept method calls for measuring purposes.
143
- def logger_measure_module
144
- if const_defined?(:SemanticLoggerMeasure, _search_ancestors = false)
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
- mod
151
- end
152
- end
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