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
@@ -20,7 +20,7 @@ module SemanticLogger
20
20
  def self.[](klass)
21
21
  return Logger.new(klass) if !@cache_loggers || klass.is_a?(String) || klass.name.nil?
22
22
 
23
- logger_cache.compute_if_absent(klass) { Logger.new(klass) }
23
+ cached_logger(klass)
24
24
  end
25
25
 
26
26
  # Whether `SemanticLogger[Class]` returns a shared, cached Logger instance per
@@ -71,25 +71,171 @@ module SemanticLogger
71
71
  end
72
72
 
73
73
  # Returns the current backtrace level
74
- def self.backtrace_level
75
- @backtrace_level
76
- end
74
+ def self.backtrace_level = @backtrace_level
77
75
 
78
76
  # Returns the current backtrace level index
79
77
  # For internal use only
80
- def self.backtrace_level_index
81
- @backtrace_level_index
78
+ def self.backtrace_level_index = @backtrace_level_index
79
+
80
+ # Sets the level at and above which each log entry records where it was logged: the file, line,
81
+ # and method of the code that made the log call (see Log#call_site). The JSON and text formatters
82
+ # then write the method next to the file name and line number.
83
+ #
84
+ # Unlike backtrace_level, it reads only the frames of the stack up to the code that made the log
85
+ # call, which costs about 1.5 µs per entry however deep the stack is, instead of building
86
+ # the whole backtrace.
87
+ #
88
+ # Parameters
89
+ # level: [Symbol|nil]
90
+ # :trace, :debug, :info, :warn, :error, or :fatal.
91
+ # nil: Do not record where entries were logged.
92
+ # Default: nil
93
+ #
94
+ # Example:
95
+ # SemanticLogger.call_site_level = :info
96
+ def self.call_site_level=(level)
97
+ # For performance reasons pre-calculate the level index
98
+ index = Levels.index(level)
99
+ @call_site_level_index = index.nil? ? 65_535 : index
100
+ @call_site_level = index.nil? ? nil : Levels.level(index)
101
+ end
102
+
103
+ # Returns the level at and above which each log entry records where it was logged, or nil when
104
+ # it is not recorded.
105
+ def self.call_site_level = @call_site_level
106
+
107
+ # Returns the call site level index
108
+ # For internal use only
109
+ def self.call_site_level_index = @call_site_level_index
110
+
111
+ # Sets the paths, or parts of paths, of code that logs on behalf of its caller, such as an
112
+ # application's own logging helper. A frame in a file whose path includes one of them is skipped
113
+ # when recording where an entry was logged, so that the entry shows the code that called the
114
+ # helper. Semantic Logger's own frames are always skipped.
115
+ #
116
+ # Parameters
117
+ # paths: [Array<String>|nil]
118
+ # Each matches any file whose path includes it, such as "app/lib/audit_log.rb", or
119
+ # "/my_logging_gem/" for every file of a gem.
120
+ # nil: Skip only Semantic Logger's own frames.
121
+ # Default: []
122
+ #
123
+ # Example:
124
+ # SemanticLogger.call_site_skip_paths = ["app/lib/audit_log.rb"]
125
+ def self.call_site_skip_paths=(paths)
126
+ paths = [] if paths.nil?
127
+ valid = paths.is_a?(Array) && paths.all? { |path| path.is_a?(String) && !path.empty? }
128
+ raise(ArgumentError, "call_site_skip_paths must be an Array of non-empty Strings: #{paths.inspect}") unless valid
129
+
130
+ # Frozen copies, leaving the Strings supplied as they are, so that code in any Ractor can read them.
131
+ @call_site_skip_paths = Utils.make_shareable(paths.map(&:-@).freeze)
132
+ end
133
+
134
+ # Returns [Array<String>] the paths, or parts of paths, whose frames are skipped when recording
135
+ # where an entry was logged.
136
+ def self.call_site_skip_paths = @call_site_skip_paths
137
+
138
+ # Sets the application's backtrace cleaner, which leaves out or shortens the lines of the
139
+ # backtraces that the text and JSON formatters log, such as `Rails.backtrace_cleaner`.
140
+ #
141
+ # Parameters
142
+ # cleaner: [Object|nil]
143
+ # An object that responds to `#clean`, as ActiveSupport::BacktraceCleaner does, or to `#call`,
144
+ # such as a Proc. It is given each exception's backtrace as an Array of Strings, and returns
145
+ # the lines to log. When it leaves out every line, or raises, the full backtrace is logged,
146
+ # and an error it raises is reported to the internal logger.
147
+ # It is called on the appender threads, so it must be thread safe.
148
+ # nil: Do not clean backtraces.
149
+ # Default: nil
150
+ #
151
+ # The `:default`, `:color`, `:pattern`, `:syslog`, `:json`, and `:fluentd` formatters use it
152
+ # unless given `backtrace_cleaner: false`. Other formatters only use it when given
153
+ # `backtrace_cleaner: true`. Appenders that send the exception itself, such as error services,
154
+ # are not affected.
155
+ #
156
+ # Example:
157
+ # SemanticLogger.backtrace_cleaner = Rails.backtrace_cleaner
158
+ def self.backtrace_cleaner=(cleaner)
159
+ # Compared by identity, since a cleaner, such as a test double, need not define #nil?.
160
+ BacktraceCleaning.validate!(cleaner, expected: "nil or a backtrace cleaner") unless nil.equal?(cleaner)
161
+
162
+ @backtrace_cleaner = cleaner
163
+ end
164
+
165
+ # Returns the application's backtrace cleaner, or nil when there is none.
166
+ def self.backtrace_cleaner
167
+ @backtrace_cleaner
168
+ end
169
+
170
+ # Sets the keys whose values are replaced with "[FILTERED]" in every log entry, such as
171
+ # passwords and access tokens, before any appender writes it.
172
+ #
173
+ # Parameters
174
+ # keys: [Array|Regexp|Object|nil]
175
+ # Array: Symbols and Strings, each matching any key whose name contains it, ignoring case,
176
+ # as in Rails' `config.filter_parameters`, and Regexps.
177
+ # Regexp: Matches the names of the sensitive keys.
178
+ # An object that responds to `#filter_param`, such as ActiveSupport::ParameterFilter, which
179
+ # is asked about each key name: `filter_param(name, nil)` returns nil when the key is not
180
+ # sensitive, and otherwise the value that replaces the key's value.
181
+ # An object that responds to `#call`, such as a Proc, given each key name, which returns
182
+ # whether the key is sensitive.
183
+ # nil: Do not redact.
184
+ # Default: nil
185
+ #
186
+ # The keys of the payload, named tags, context, and metric dimensions of each entry are matched,
187
+ # at any depth, both as written and in snake_case, so that "X-Api-Key" and "apiKey" are also
188
+ # matched as "x_api_key" and "api_key". The message, tags, and exception are not changed.
189
+ #
190
+ # Each entry is redacted once, on the thread that writes it to the appenders, before any of them
191
+ # writes it, so the keys must be thread safe. `on_log` subscribers and logger filters run before,
192
+ # on the thread that logs the entry, and receive it as it was logged. The application's own
193
+ # Hashes are never changed: the entry gets a copy.
194
+ #
195
+ # The keys are read when they are assigned, so changing an Array of them afterwards has no effect:
196
+ # assign them again instead.
197
+ #
198
+ # When an entry cannot be redacted, for example because the keys raise an error, the field is
199
+ # replaced with `{redaction_failed: "ErrorClass"}`, and the error is reported to the internal
200
+ # logger.
201
+ #
202
+ # Example:
203
+ # SemanticLogger.sensitive_keys = [:password, :secret, :token, :authorization]
204
+ #
205
+ # Example, with the parameters that Rails filters, except its Proc filters, which change a value
206
+ # rather than name a key (rails_semantic_logger does this once the application has initialized):
207
+ # filters = Rails.application.config.filter_parameters.reject { |filter| filter.respond_to?(:call) }
208
+ # SemanticLogger.sensitive_keys = ActiveSupport::ParameterFilter.new(filters)
209
+ def self.sensitive_keys=(keys)
210
+ # Compared by identity, since the keys, such as a test double, need not define #nil?.
211
+ @redactor = nil.equal?(keys) ? nil : Redactor.new(keys)
212
+ end
213
+
214
+ # Returns the sensitive keys, as supplied to .sensitive_keys=, or nil when there are none.
215
+ def self.sensitive_keys
216
+ @redactor&.sensitive_keys
217
+ end
218
+
219
+ # Internal: Returns [SemanticLogger::Redactor] the redactor for the sensitive keys, which each
220
+ # entry is asked to redact itself with before it is written (see Appenders#log), or nil when
221
+ # there are no sensitive keys.
222
+ def self.redactor
223
+ @redactor
82
224
  end
83
225
 
84
226
  # Returns [String] name of this host for logging purposes
85
227
  # Note: Not all appenders use `host`
86
228
  def self.host
87
- @host ||= Socket.gethostname.force_encoding("UTF-8")
229
+ @host
88
230
  end
89
231
 
90
- # Override the default host name
232
+ # Override the default host name, which is this machine's host name. Set it to nil to go back to
233
+ # the default.
234
+ #
235
+ # The host, application, and environment are stored as frozen copies, so that code in any Ractor
236
+ # can read them. The value supplied is left as it is.
91
237
  def self.host=(host)
92
- @host = host
238
+ @host = Utils.make_shareable(host || Socket.gethostname.force_encoding("UTF-8"), copy: true)
93
239
  end
94
240
 
95
241
  # Returns [String] name of this application for logging purposes
@@ -100,7 +246,7 @@ module SemanticLogger
100
246
 
101
247
  # Override the default application
102
248
  def self.application=(application)
103
- @application = application
249
+ @application = Utils.make_shareable(application, copy: true)
104
250
  end
105
251
 
106
252
  # Returns [String] name of this environment for logging purposes
@@ -111,11 +257,12 @@ module SemanticLogger
111
257
 
112
258
  # Override the default environment
113
259
  def self.environment=(environment)
114
- @environment = environment
260
+ @environment = Utils.make_shareable(environment, copy: true)
115
261
  end
116
262
 
117
- @application = ENV["SEMANTIC_LOGGER_APP"] || "Semantic Logger"
118
- @environment = ENV["SEMANTIC_LOGGER_ENV"] || ENV["RAILS_ENV"] || ENV.fetch("RACK_ENV", nil)
263
+ self.host = nil
264
+ self.application = ENV["SEMANTIC_LOGGER_APP"] || "Semantic Logger"
265
+ self.environment = ENV["SEMANTIC_LOGGER_ENV"] || ENV["RAILS_ENV"] || ENV.fetch("RACK_ENV", nil)
119
266
 
120
267
  # Add a new logging appender as a new destination for all log messages
121
268
  # emitted from Semantic Logger
@@ -123,8 +270,12 @@ module SemanticLogger
123
270
  # Appenders will be written to in the order that they are added
124
271
  #
125
272
  # If a block is supplied then it will be used to customize the format
126
- # of the messages sent to that appender. See SemanticLogger::Logger.new for
127
- # more information on custom formatters
273
+ # of the messages sent to that appender. See "Formatter as a block or Proc" in
274
+ # docs/config.md for more information on custom formatters
275
+ #
276
+ # Give it one destination: file_name:, io:, logger:, appender:, or metric:. Given more than one, it adds
277
+ # only the first, in that order, and reports a deprecation warning that names the others, which it
278
+ # ignores; v6 raises ArgumentError. A destination given as nil is not one.
128
279
  #
129
280
  # Parameters
130
281
  # file_name: [String]
@@ -139,11 +290,13 @@ module SemanticLogger
139
290
  # appender: [Symbol|SemanticLogger::Subscriber]
140
291
  # A symbol identifying the appender to create.
141
292
  # For example:
142
- # :bugsnag, :elasticsearch, :graylog, :http, :mongodb, :new_relic, :splunk_http, :syslog, :wrapper
293
+ # :bugsnag, :elasticsearch, :graylog, :http, :mongodb, :new_relic, :splunk_http, :syslog
143
294
  # Or,
144
295
  # An instance of an appender derived from SemanticLogger::Subscriber
145
296
  # For example:
146
297
  # SemanticLogger::Appender::Http.new(url: 'http://localhost:8088/path')
298
+ # It is added as it is: set its options, such as level: and formatter:, and its formatter block,
299
+ # on the instance itself. Only async:, batch:, and the other options of the async proxy apply to it.
147
300
  #
148
301
  # Or,
149
302
  # logger: [Logger|Log4r]
@@ -151,7 +304,9 @@ module SemanticLogger
151
304
  #
152
305
  # level: [:trace | :debug | :info | :warn | :error | :fatal]
153
306
  # Override the log level for this appender.
154
- # Default: SemanticLogger.default_level
307
+ # Default: the appender's own. For most that is none (:trace), so it writes every entry that a
308
+ # logger emits; each logger filters by its own level. Those that send errors to a service, such
309
+ # as :bugsnag and :sentry_ruby, default to :error, and :honeybadger_insights to :info.
155
310
  #
156
311
  # formatter: [Symbol|Object|Proc]
157
312
  # Any of the following symbol values: :default, :color, :json, :logfmt, etc...
@@ -199,19 +354,44 @@ module SemanticLogger
199
354
  appender = appenders.add(**args, &)
200
355
  # Start appender thread if it is not already running
201
356
  Logger.processor.start
357
+ # And the thread that receives the entries logged in other Ractors (Ruby 4.0 and later).
358
+ RactorReceiver.start if RactorSupport.enabled?
202
359
  appender
203
360
  end
204
361
 
205
362
  # Remove an existing appender
206
363
  # Currently only supports appender instances
364
+ #
365
+ # Before closing an appender that it removed, waits until the processor has written the log
366
+ # messages already queued to the other appenders, and flushed them, as .flush does, so that none is
367
+ # still being written to it when it is closed, such as a request on its connection that the
368
+ # processor's thread is sending. On the processor's own thread, such as by an appender while it
369
+ # writes, it closes it at once, since nothing else writes to it then. In a forked child, the
370
+ # appender is reopened first, when that has not happened yet, so that closing it closes only what
371
+ # the child built (see Processor#remove).
372
+ #
373
+ # On the thread of an appender added with async: true or in batches, such as by that appender as it
374
+ # writes, removing itself or another appender, it cannot wait for the processor's thread, which may
375
+ # be waiting for it. The processor's thread, once it has written the log messages queued ahead,
376
+ # closes the appender, between writes, then removes it, without this call waiting for it. Until
377
+ # then, .appenders still lists it. An appender that removes itself is closed once its current write
378
+ # has returned.
379
+ #
380
+ # Returns the result of closing the appender, or true on the thread of an appender added with
381
+ # async: true or in batches, before the appender is closed. With sync!, in a signal trap, returns
382
+ # nil when it is not closed within SyncProcessor::TRAP_WAIT_SECONDS, such as when the trap
383
+ # interrupted a log call, which must return first: it is then removed and closed just after (see
384
+ # SyncProcessor#remove).
207
385
  def self.remove_appender(appender)
208
386
  return unless appender
209
387
 
210
- appenders.delete(appender)
211
- appender.close
388
+ Logger.processor.remove(appender)
212
389
  end
213
390
 
214
391
  # Clear out all previously registered appenders
392
+ #
393
+ # Like .close, returns false at once, without closing them, on the thread of an appender added with
394
+ # async: true or in batches.
215
395
  def self.clear_appenders!
216
396
  Logger.processor.close
217
397
  end
@@ -226,11 +406,28 @@ module SemanticLogger
226
406
 
227
407
  # Flush all queued log entries disk, database, etc.
228
408
  # All queued log messages are written and then each appender is flushed in turn.
409
+ #
410
+ # Once a write fails because of the destination of an appender added with async: true or in
411
+ # batches, the rest of the messages queued for that appender ahead of the flush are discarded and
412
+ # counted as failed, rather than each one tried in turn during an outage.
413
+ #
414
+ # On Ruby 4.0 and later, in the main Ractor, the entries already sent from other Ractors are
415
+ # written first. In another Ractor, it waits until the main Ractor has written that Ractor's
416
+ # entries and flushed the appenders.
417
+ #
418
+ # Returns false at once, without flushing, on the thread of an appender added with async: true or
419
+ # in batches, such as by that appender as it writes, since the processor's thread waits for that
420
+ # thread to flush the appender. The first such call is reported to the internal logger.
229
421
  def self.flush
230
- Logger.processor.flush
422
+ return Logger.processor.flush if !RactorSupport.enabled? || RactorSupport.other_ractor?
423
+
424
+ RactorReceiver.flush
231
425
  end
232
426
 
233
427
  # Close all appenders and flush any outstanding messages.
428
+ #
429
+ # Like .flush, returns false at once, without closing them, on the thread of an appender added with
430
+ # async: true or in batches.
234
431
  def self.close
235
432
  Logger.processor.close
236
433
  end
@@ -246,6 +443,14 @@ module SemanticLogger
246
443
  # this guard and reopen unconditionally, for example when re-opening file handles
247
444
  # in the same process after an external log rotation.
248
445
  #
446
+ # Each appender is reopened by the thread that writes its entries, before it writes the next one,
447
+ # so that it is never reopened while it is writing, and so this returns before the appenders have
448
+ # reopened: a flush after it returns once they have. One added with async: true or in batches has
449
+ # a thread of its own; a batching one reopens at its next batch, or flush. That also lets this be
450
+ # called from a signal trap. With sync!, the appenders without a thread of their own are reopened
451
+ # on the calling thread instead, or, in a signal trap, on a thread that the trap starts and waits
452
+ # for, at most SyncProcessor::TRAP_WAIT_SECONDS (see SyncProcessor#flush).
453
+ #
249
454
  # Note:
250
455
  # Not all appender's implement reopen.
251
456
  # Check the code for each appender you are using before relying on this behavior.
@@ -253,15 +458,16 @@ module SemanticLogger
253
458
  return if !force && @reopened_pid == ::Process.pid
254
459
 
255
460
  Logger.processor.reopen
461
+ RactorReceiver.reopen if RactorSupport.enabled?
256
462
  @reopened_pid = ::Process.pid
257
463
  end
258
464
 
259
465
  # Whether appenders are automatically reopened in the child process after a fork.
260
466
  #
261
467
  # Enabled by default. A `Process._fork` hook (Ruby 3.1+) calls SemanticLogger.reopen
262
- # in the child after `fork`, `Process.daemon`, `IO.popen`, `Kernel#system`, and
263
- # backticks, so framework specific `after_fork` hooks (Puma, Unicorn, Resque,
264
- # Spring, etc.) are no longer required.
468
+ # in the child after `fork`, `Process.fork`, `Process.daemon`, and `IO.popen("-")`,
469
+ # so framework specific `after_fork` hooks (Puma, Unicorn, Resque, Spring, etc.)
470
+ # are no longer required.
265
471
  def self.reopen_on_fork?
266
472
  @reopen_on_fork != false
267
473
  end
@@ -275,7 +481,8 @@ module SemanticLogger
275
481
  end
276
482
 
277
483
  # Supply a callback to be called whenever a log entry is created.
278
- # Useful for capturing appender specific context information.
484
+ # Useful for capturing appender specific context information. Keep an object that is for an
485
+ # appender of your own with `log.capture`, and data to be logged with `log.set_context`.
279
486
  #
280
487
  # Parameters
281
488
  # object: [Object | Proc]
@@ -284,13 +491,13 @@ module SemanticLogger
284
491
  #
285
492
  # Example:
286
493
  # SemanticLogger.on_log do |log|
287
- # log.set_context(:honeybadger, Honeybadger.get_context)
494
+ # log.capture(:honeybadger, Honeybadger.get_context)
288
495
  # end
289
496
  #
290
497
  # Example:
291
498
  # module CaptureContext
292
499
  # def call(log)
293
- # log.set_context(:honeybadger, Honeybadger.get_context)
500
+ # log.capture(:honeybadger, Honeybadger.get_context)
294
501
  # end
295
502
  # end
296
503
  # SemanticLogger.on_log(CaptureContext)
@@ -372,19 +579,13 @@ module SemanticLogger
372
579
 
373
580
  # If the tag being supplied is definitely a string then this fast
374
581
  # tag api can be used for short lived tags
375
- def self.fast_tag(tag)
582
+ def self.fast_tag(tag, &)
376
583
  return yield if tag.nil? || tag == ""
377
584
 
378
- t = Thread.current[:semantic_logger_tags] ||= []
379
- begin
380
- t << tag
381
- yield
382
- ensure
383
- t.pop
384
- end
585
+ Context.fast_tag(tag, &)
385
586
  end
386
587
 
387
- # Add the tags or named tags to the list of tags to log for this thread whilst the supplied block is active.
588
+ # Add the tags or named tags to the list of tags to log for this fiber whilst the supplied block is active.
388
589
  #
389
590
  # Returns result of block.
390
591
  #
@@ -413,20 +614,14 @@ module SemanticLogger
413
614
  return tag.is_a?(Hash) ? named_tagged(tag, &) : fast_tag(tag, &)
414
615
  end
415
616
 
416
- begin
417
- push_tags(*tags)
418
- yield
419
- ensure
420
- pop_tags(tags.size)
421
- end
617
+ # The rest Array is this call's own, so Context may keep it.
618
+ Context.tagged(tags, &)
422
619
  end
423
620
 
424
- # Returns a copy of the [Array] of [String] tags currently active for this thread
425
- # Returns nil if no tags are set
621
+ # Returns a copy of the [Array] of [String] tags currently active for this fiber.
622
+ # Returns an empty Array if no tags are set.
426
623
  def self.tags
427
- # Since tags are stored on a per thread basis this list is thread-safe
428
- t = Thread.current[:semantic_logger_tags]
429
- t.nil? ? [] : t.clone
624
+ Context.tags
430
625
  end
431
626
 
432
627
  # Add tags to the current scope
@@ -437,57 +632,71 @@ module SemanticLogger
437
632
  # - To get the flattening behavior use the slower api:
438
633
  # `logger.push_tags`
439
634
  def self.push_tags(*tags)
440
- (Thread.current[:semantic_logger_tags] ||= []).concat(tags)
635
+ Context.push_tags(tags)
441
636
  tags
442
637
  end
443
638
 
444
639
  # Remove specified number of tags from the current tag list
445
640
  def self.pop_tags(quantity = 1)
446
- t = Thread.current[:semantic_logger_tags]
447
- t&.pop(quantity)
641
+ Context.pop_tags(quantity)
642
+ end
643
+
644
+ # Returns [SemanticLogger::Context] a frozen snapshot of the logging context of the current fiber:
645
+ # its tags, named tags, and silence level (see .silence).
646
+ #
647
+ # The context belongs to the current fiber, so a thread or fiber started inside a `tagged` block
648
+ # does not have its tags. Hand the context over with .with_context:
649
+ #
650
+ # context = SemanticLogger.context
651
+ # Thread.new do
652
+ # SemanticLogger.with_context(context) do
653
+ # logger.info("Logged with the same tags")
654
+ # end
655
+ # end
656
+ #
657
+ # The context does not include the levels set by a logger's #with_level, which, like Ruby's
658
+ # Logger#with_level, apply only to the fiber that set them.
659
+ def self.context
660
+ Context.current
661
+ end
662
+
663
+ # Runs the block with the supplied context, from .context, as the logging context of the current
664
+ # fiber. Within the block the fiber has exactly the tags, named tags, and silence level of that
665
+ # context, in place of its own, which are restored when the block exits.
666
+ #
667
+ # Returns the result of the block.
668
+ def self.with_context(context, &)
669
+ Context.use(context, &)
448
670
  end
449
671
 
450
672
  # :nodoc
451
- def self.named_tagged(hash)
673
+ def self.named_tagged(hash, &)
452
674
  return yield if hash.nil? || hash.empty?
453
675
  raise(ArgumentError, "#named_tagged only accepts named parameters (Hash)") unless hash.is_a?(Hash)
454
676
 
455
- begin
456
- push_named_tags(hash)
457
- yield
458
- ensure
459
- pop_named_tags
460
- end
677
+ Context.named_tagged(hash, &)
461
678
  end
462
679
 
463
- # Returns [Hash] a copy of the named tags currently active for this thread.
680
+ # Returns [Hash] a copy of the named tags currently active for this fiber.
464
681
  def self.named_tags
465
- if (list = Thread.current[:semantic_logger_named_tags]) && !list.empty?
466
- if list.size > 1
467
- list.reduce({}) { |sum, h| sum.merge(h) }
468
- else
469
- list.first.clone
470
- end
471
- else
472
- {}
473
- end
682
+ Context.named_tags
474
683
  end
475
684
 
476
685
  def self.push_named_tags(hash)
477
- (Thread.current[:semantic_logger_named_tags] ||= []) << hash
686
+ Context.push_named_tags(hash)
478
687
  hash
479
688
  end
480
689
 
481
690
  def self.pop_named_tags(quantity = 1)
482
- t = Thread.current[:semantic_logger_named_tags]
483
- t&.pop(quantity)
691
+ Context.pop_named_tags(quantity)
484
692
  end
485
693
 
486
694
  # Silence noisy log levels by changing the default_level within the block
487
695
  #
488
- # This setting is thread-safe and only applies to the current thread
696
+ # This setting only applies to the current fiber: every thread, and every fiber of a fiber
697
+ # scheduler such as Async, has its own.
489
698
  #
490
- # Any threads spawned within the block will not be affected by this setting
699
+ # Threads and fibers started within the block are not affected by this setting
491
700
  #
492
701
  # #silence can be used to both raise and lower the log level within
493
702
  # the supplied block.
@@ -519,12 +728,8 @@ module SemanticLogger
519
728
  # Note:
520
729
  # #silence does not affect any loggers which have had their log level set
521
730
  # explicitly. I.e. That do not rely on the global default level
522
- def self.silence(new_level = :error)
523
- current_index = Thread.current[:semantic_logger_silence]
524
- Thread.current[:semantic_logger_silence] = Levels.index(new_level)
525
- yield
526
- ensure
527
- Thread.current[:semantic_logger_silence] = current_index
731
+ def self.silence(new_level = :error, &)
732
+ Context.silence(Levels.index(new_level), &)
528
733
  end
529
734
 
530
735
  # Returns [Integer] the number of log entries waiting to be written to the appenders.
@@ -533,8 +738,11 @@ module SemanticLogger
533
738
  # able to write to the appenders fast enough. Either reduce the amount of
534
739
  # logging, increase the log level, reduce the number of appenders, or
535
740
  # look into speeding up the appenders themselves
741
+ #
742
+ # With sync!, entries are written on the calling thread, so only those logged in a signal trap
743
+ # wait, until another thread writes them (see SyncProcessor#queue_size).
536
744
  def self.queue_size
537
- Logger.processor.queue.size
745
+ Logger.processor.queue_size
538
746
  end
539
747
 
540
748
  # Returns [Hash] operational statistics for the logging pipeline.
@@ -590,7 +798,7 @@ module SemanticLogger
590
798
  end
591
799
 
592
800
  def self.default_level_index
593
- Thread.current[:semantic_logger_silence] || @default_level_index
801
+ Context.silence_index || @default_level_index
594
802
  end
595
803
 
596
804
  # Run Semantic Logger in Synchronous mode.
@@ -611,16 +819,42 @@ module SemanticLogger
611
819
  @default_level_index = Levels.index(@default_level)
612
820
  @backtrace_level = :error
613
821
  @backtrace_level_index = Levels.index(@backtrace_level)
822
+ @backtrace_cleaner = nil
823
+ @redactor = nil
614
824
  @sync = false
615
825
  @cache_loggers = false
616
826
  @logger_cache = nil
617
827
 
828
+ # Do not record where entries were logged, and skip only Semantic Logger's own frames.
829
+ self.call_site_level = nil
830
+ self.call_site_skip_paths = nil
831
+
618
832
  # Lazily initialized thread-safe cache of one Logger per Class/Module.
619
833
  def self.logger_cache
620
834
  @logger_cache ||= Concurrent::Map.new
621
835
  end
622
836
  private_class_method :logger_cache
623
837
 
838
+ # Returns the cached Logger for the Class or Module.
839
+ #
840
+ # A Ractor other than the main one cannot use the main Ractor's cache, or its loggers, so it has a
841
+ # cache of its own (experimental, Ruby 4.0 and later).
842
+ #
843
+ # In a signal trap, a new thread adds the Logger to the cache before the trap returns (see
844
+ # TrapSafe.compute_if_absent), unless the trap interrupted a thread that was adding to the cache.
845
+ # It is added just after the trap then, which leaves a window: until it is, a call on another thread
846
+ # can cache a second Logger for the class, so that the class's `logger`, if the trap asked for it,
847
+ # differs from SemanticLogger[klass]; and a .clear_logger_cache in that window is undone.
848
+ def self.cached_logger(klass)
849
+ if RactorSupport.other_ractor?
850
+ cache = ::Ractor.store_if_absent(:semantic_logger_logger_cache) { {} }
851
+ return cache[klass] ||= Logger.new(klass)
852
+ end
853
+
854
+ TrapSafe.compute_if_absent(logger_cache, klass) { Logger.new(klass) }
855
+ end
856
+ private_class_method :cached_logger
857
+
624
858
  # @formatter:off
625
859
  module Metric
626
860
  autoload :NewRelic, "semantic_logger/metric/new_relic"