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,222 @@
1
+ module SemanticLogger
2
+ # The logging context of a fiber: its tags, named tags, and silence level.
3
+ #
4
+ # An instance is a frozen snapshot of a fiber's context, returned by SemanticLogger.context, for
5
+ # SemanticLogger.with_context to apply in another thread or fiber. It has `tags` (an Array),
6
+ # `named_tags` (a Hash), and `silence` (the level Symbol set by SemanticLogger.silence, or nil).
7
+ #
8
+ # The class methods are internal. They manage the context of the current fiber, together with the
9
+ # `with_level` overrides of its loggers, which are not part of a snapshot: like Ruby's
10
+ # Logger#with_level they apply only to the fiber that set them. Only this class knows where that
11
+ # state is kept: in fiber-local variables (`Thread.current[]`), so that every fiber, including the
12
+ # fibers of a fiber scheduler such as Async, has its own.
13
+ #
14
+ # The stored lists are never changed in place. Each change stores a new frozen list, and the block
15
+ # forms restore the previous list when the block exits. Code that copies fiber-local variables into
16
+ # another thread, such as Rails' ActionController::Live, therefore hands over lists that Semantic
17
+ # Logger never changes for the other thread. The tags in them are the caller's own objects.
18
+ Context = Data.define(:tags, :named_tags, :silence)
19
+
20
+ class Context
21
+ TAGS_KEY = :semantic_logger_tags
22
+ NAMED_TAGS_KEY = :semantic_logger_named_tags
23
+ SILENCE_KEY = :semantic_logger_silence
24
+ WITH_LEVEL_KEY = :semantic_logger_with_level
25
+ EMPTY = [].freeze
26
+ EMPTY_HASH = {}.freeze
27
+ private_constant :TAGS_KEY, :NAMED_TAGS_KEY, :SILENCE_KEY, :WITH_LEVEL_KEY, :EMPTY, :EMPTY_HASH
28
+
29
+ # Parameters
30
+ # tags: [Array]
31
+ # Positional tags.
32
+ # named_tags: [Hash]
33
+ # Named tags.
34
+ # silence: [Symbol|String|Integer]
35
+ # A level accepted by SemanticLogger.silence, or nil for none.
36
+ def initialize(tags: EMPTY, named_tags: EMPTY_HASH, silence: nil)
37
+ raise(ArgumentError, "tags must be an Array") unless tags.is_a?(Array)
38
+ raise(ArgumentError, "named_tags must be a Hash") unless named_tags.is_a?(Hash)
39
+
40
+ super(
41
+ tags: tags.frozen? ? tags : tags.dup.freeze,
42
+ named_tags: named_tags.frozen? ? named_tags : named_tags.dup.freeze,
43
+ silence: silence.nil? ? nil : Levels.level(Levels.index(silence))
44
+ )
45
+ end
46
+
47
+ # Returns [Context] a copy with the supplied members changed, checked and frozen as by .new,
48
+ # which Data#with does not call on Ruby 3.2.
49
+ def with(**changes)
50
+ changes.empty? ? self : self.class.new(**to_h, **changes)
51
+ end
52
+
53
+ # A context with no tags, named tags, or silence level.
54
+ NONE = new
55
+ private_constant :NONE
56
+
57
+ class << self
58
+ # Returns [Context] a frozen snapshot of the current fiber's context.
59
+ def current
60
+ tags = Thread.current[TAGS_KEY]
61
+ named = Thread.current[NAMED_TAGS_KEY]
62
+ index = Thread.current[SILENCE_KEY]
63
+ return NONE if (tags.nil? || tags.empty?) && (named.nil? || named.empty?) && index.nil?
64
+
65
+ new(tags: tags || EMPTY, named_tags: merge(named).freeze, silence: index && Levels.level(index))
66
+ end
67
+
68
+ # Runs the block with the supplied context as the current fiber's context, in place of the
69
+ # fiber's own tags, named tags, and silence level, which are restored when the block exits.
70
+ def use(context)
71
+ raise(ArgumentError, "Expected a SemanticLogger::Context, got #{context.class}") unless context.is_a?(Context)
72
+
73
+ previous = [Thread.current[TAGS_KEY], Thread.current[NAMED_TAGS_KEY], Thread.current[SILENCE_KEY]]
74
+ begin
75
+ Thread.current[TAGS_KEY] = context.tags.empty? ? nil : context.tags
76
+ Thread.current[NAMED_TAGS_KEY] = context.named_tags.empty? ? nil : [context.named_tags].freeze
77
+ Thread.current[SILENCE_KEY] = context.silence && Levels.index(context.silence)
78
+ yield
79
+ ensure
80
+ Thread.current[TAGS_KEY], Thread.current[NAMED_TAGS_KEY], Thread.current[SILENCE_KEY] = previous
81
+ end
82
+ end
83
+
84
+ # Returns [Array] a new Array of the tags of the thread's current fiber.
85
+ def tags(thread = Thread.current)
86
+ tags = thread[TAGS_KEY]
87
+ tags ? tags.dup : []
88
+ end
89
+
90
+ # Returns [Hash] a new Hash of the named tags of the thread's current fiber.
91
+ #
92
+ # Each named tags block pushes its Hash onto a list; a later Hash wins on a key that is in both.
93
+ def named_tags(thread = Thread.current)
94
+ merge(thread[NAMED_TAGS_KEY])
95
+ end
96
+
97
+ # Runs the block with the tag added to the current fiber's tags.
98
+ #
99
+ # Like every block form below, it restores the previous value when the block exits, whatever
100
+ # the block did to it. Each is written out in full, since this is on the hot path. Each reads
101
+ # the previous value before its `begin`, so that an exception raised into the thread, such as
102
+ # by Timeout, can never restore a value that was not read yet.
103
+ def fast_tag(tag)
104
+ previous = Thread.current[TAGS_KEY]
105
+ begin
106
+ Thread.current[TAGS_KEY] = (previous ? previous.dup << tag : [tag]).freeze
107
+ yield
108
+ ensure
109
+ Thread.current[TAGS_KEY] = previous
110
+ end
111
+ end
112
+
113
+ # Runs the block with the Array of tags added to the current fiber's tags. Takes ownership of
114
+ # the Array, which it may freeze, so the caller must not keep it.
115
+ def tagged(tags)
116
+ previous = Thread.current[TAGS_KEY]
117
+ begin
118
+ Thread.current[TAGS_KEY] = (previous ? previous + tags : tags).freeze
119
+ yield
120
+ ensure
121
+ Thread.current[TAGS_KEY] = previous
122
+ end
123
+ end
124
+
125
+ # Adds the Array of tags to the current fiber's tags, until they are popped.
126
+ def push_tags(tags)
127
+ Thread.current[TAGS_KEY] = (current_tags + tags).freeze
128
+ end
129
+
130
+ # Removes the last `quantity` tags from the current fiber's tags.
131
+ # Returns [Array] the tags removed, or nil when the fiber has no tags.
132
+ def pop_tags(quantity)
133
+ pop(TAGS_KEY, quantity)
134
+ end
135
+
136
+ # Runs the block with the Hash of named tags added to the current fiber's named tags.
137
+ def named_tagged(hash)
138
+ previous = Thread.current[NAMED_TAGS_KEY]
139
+ begin
140
+ Thread.current[NAMED_TAGS_KEY] = (previous ? previous.dup << hash : [hash]).freeze
141
+ yield
142
+ ensure
143
+ Thread.current[NAMED_TAGS_KEY] = previous
144
+ end
145
+ end
146
+
147
+ # Adds the Hash of named tags to the current fiber's named tags, until it is popped.
148
+ def push_named_tags(hash)
149
+ Thread.current[NAMED_TAGS_KEY] = (current_named_tags.dup << hash).freeze
150
+ end
151
+
152
+ # Removes the last `quantity` Hashes of named tags pushed onto the current fiber.
153
+ # Returns [Array] the Hashes removed, or nil when the fiber has no named tags.
154
+ def pop_named_tags(quantity)
155
+ pop(NAMED_TAGS_KEY, quantity)
156
+ end
157
+
158
+ # Returns [Integer|nil] the level index set by an enclosing `silence` block on the current
159
+ # fiber, or nil when there is none.
160
+ def silence_index
161
+ Thread.current[SILENCE_KEY]
162
+ end
163
+
164
+ # Runs the block with the supplied level index as the current fiber's silence level.
165
+ def silence(index)
166
+ previous = Thread.current[SILENCE_KEY]
167
+ begin
168
+ Thread.current[SILENCE_KEY] = index
169
+ yield
170
+ ensure
171
+ Thread.current[SILENCE_KEY] = previous
172
+ end
173
+ end
174
+
175
+ # Returns [Integer|nil] the level index set for the logger by an enclosing `with_level` block
176
+ # on the current fiber, or nil when there is none.
177
+ def with_level_index(logger)
178
+ Thread.current[WITH_LEVEL_KEY]&.[](logger)
179
+ end
180
+
181
+ # Runs the block with the supplied level index for the logger on the current fiber.
182
+ def with_level(logger, index)
183
+ previous = Thread.current[WITH_LEVEL_KEY]
184
+ begin
185
+ overrides = previous ? previous.dup : {}.compare_by_identity
186
+ overrides[logger] = index
187
+ Thread.current[WITH_LEVEL_KEY] = overrides.freeze
188
+ yield
189
+ ensure
190
+ Thread.current[WITH_LEVEL_KEY] = previous
191
+ end
192
+ end
193
+
194
+ private
195
+
196
+ # Returns [Hash] a new Hash of the list of named tags Hashes merged, a later one winning.
197
+ def merge(list)
198
+ return {} if list.nil? || list.empty?
199
+
200
+ list.size == 1 ? list.first.dup : list.reduce({}) { |sum, hash| sum.merge(hash) }
201
+ end
202
+
203
+ def current_tags
204
+ Thread.current[TAGS_KEY] || EMPTY
205
+ end
206
+
207
+ def current_named_tags
208
+ Thread.current[NAMED_TAGS_KEY] || EMPTY
209
+ end
210
+
211
+ # Pops from a copy of the list under the key, as Array#pop does, and stores the copy.
212
+ def pop(key, quantity)
213
+ list = Thread.current[key]&.dup
214
+ return if list.nil?
215
+
216
+ popped = list.pop(quantity)
217
+ Thread.current[key] = list.freeze
218
+ popped
219
+ end
220
+ end
221
+ end
222
+ end
@@ -5,21 +5,36 @@ module SemanticLogger
5
5
  # Prepended onto `Process.singleton_class` when Semantic Logger is loaded.
6
6
  # Enabled by default; opt out with `SemanticLogger.reopen_on_fork = false`.
7
7
  #
8
- # `Process._fork` (Ruby 3.1+) is the single method that every fork path routes
9
- # through (`Kernel#fork`, `Process.fork`, `IO.popen`, `Kernel#system`, and
10
- # backticks), so overriding it covers them all with one hook.
8
+ # `Process._fork` (Ruby 3.1+) is the method that every fork of the Ruby process
9
+ # routes through (`Kernel#fork`, `Process.fork`, and `IO.popen("-")`), so
10
+ # overriding it covers them all with one hook. `Kernel#system`, backticks,
11
+ # `spawn`, and `IO.popen` with a command do not call it: they run another
12
+ # program, which does not inherit Semantic Logger.
13
+ #
14
+ # It can also run in a signal trap, such as one that forks, where Ruby does
15
+ # not allow a Mutex to be locked: pausing the thread that receives the entries
16
+ # of other Ractors locks none, and neither does reopening in the child. In
17
+ # synchronous mode, a thread that the trap starts reopens the appenders that
18
+ # have no thread of their own (see SyncProcessor#reopen).
11
19
  #
12
20
  # Note: both `_fork` and `daemon` must be overridden to reliably restart the
13
21
  # appender thread, since `Process.daemon` does not route through `_fork`
14
22
  # (https://bugs.ruby-lang.org/issues/18911). Do not collapse this down to only
15
23
  # `_fork`.
16
24
  module Process
25
+ # Runs the block, which forks, with Semantic Logger ready for the fork: on Ruby 4.0 and later,
26
+ # while the thread that receives log entries from other Ractors is paused (see
27
+ # RactorReceiver.pause).
28
+ def self.pause_for_fork(&)
29
+ SemanticLogger::RactorSupport.enabled? ? SemanticLogger::RactorReceiver.pause(&) : yield
30
+ end
31
+
17
32
  # `_fork` runs in both the parent and the child. It returns 0 in the child
18
33
  # and the child's pid in the parent, so only reopen in the child. Reopening
19
34
  # in the parent would needlessly recreate its queue and worker thread,
20
35
  # risking the loss of messages still on the queue.
21
36
  def _fork
22
- child_pid = super
37
+ child_pid = Process.pause_for_fork { super }
23
38
  SemanticLogger.reopen if child_pid.zero? && SemanticLogger.reopen_on_fork?
24
39
  child_pid
25
40
  end
@@ -27,7 +42,7 @@ module SemanticLogger
27
42
  # `Process.daemon` does not route through `_fork`, so reopen explicitly. Once
28
43
  # it returns, the caller is running as the daemon (child) process.
29
44
  def daemon(...)
30
- super.tap { SemanticLogger.reopen if SemanticLogger.reopen_on_fork? }
45
+ Process.pause_for_fork { super }.tap { SemanticLogger.reopen if SemanticLogger.reopen_on_fork? }
31
46
  end
32
47
  end
33
48
  end
@@ -0,0 +1,70 @@
1
+ require "json"
2
+
3
+ module SemanticLogger
4
+ module CoreExt
5
+ # Drops the json gem's warning about a binary String when Semantic Logger serializes log data.
6
+ #
7
+ # json 2.8.0 through 3.0.x write a binary String that holds valid UTF-8 outside ASCII as
8
+ # UTF-8, but warn "JSON.generate: UTF-8 string passed as BINARY, this will raise an encoding
9
+ # error in json 3.0" for each one, every time, at the default verbosity. Log data often holds
10
+ # such Strings: response bodies, Base64-decoded text, socket reads. The JSON is right: json 3.1
11
+ # raises instead, and Utils.to_json then writes the same String as the same UTF-8 (see
12
+ # Utils.json_safe). So for log data the warning only reports what Semantic Logger handles.
13
+ #
14
+ # Finding the binary Strings before serializing would mean walking every log entry, which
15
+ # takes longer than serializing it, and marking each serialization would slow every entry
16
+ # too. Instead, when the warning is raised, Utils is asked whether it comes from serializing
17
+ # log data (see Utils.serializing_log_data?). Only a warning pays for that.
18
+ #
19
+ # Prepended to `Warning` when Semantic Logger is loaded on CRuby with json 2.8.0 through 3.0.x
20
+ # (see NEEDED), so that it sees the warning before a `Warning.warn` that the application
21
+ # defines on `Warning`, extends into it, or prepends to it before loading Semantic Logger. A
22
+ # module prepended afterwards, such as a test helper that raises on warnings, sees it first.
23
+ # Any other warning, and this one from anywhere else, such as the application's own JSON, is
24
+ # passed on unchanged.
25
+ module Warning
26
+ # Part of the warning, which json 2.8.0 through 3.0.x prefix with "JSON.generate: ".
27
+ BINARY_STRING = "UTF-8 string passed as BINARY".freeze
28
+
29
+ # Whether this json gem warns about a binary String: the C extension of json 2.8.0 through
30
+ # 3.0.x. JRuby's json, and json 3.1 and later, raise instead.
31
+ NEEDED = RUBY_ENGINE == "ruby" &&
32
+ JSON::VERSION.split(".").first(2).map(&:to_i).then do |version|
33
+ (version <=> [2, 8]) >= 0 && (version <=> [3, 1]).negative?
34
+ end
35
+
36
+ # Key of the fiber-local state of .unless_binary_string_warned: :watching while it runs, and
37
+ # :warned once the warning was dropped meanwhile.
38
+ STATE = :semantic_logger_json_warning
39
+
40
+ # Returns the block's result, or nil when the json gem warned about a binary String while
41
+ # it ran, for a caller that hands the data on to be serialized elsewhere and so has to repair
42
+ # it (see Utils.json_ready).
43
+ def self.unless_binary_string_warned
44
+ return yield unless NEEDED
45
+
46
+ previous = Thread.current[STATE]
47
+ Thread.current[STATE] = :watching
48
+ result = yield
49
+ result unless Thread.current[STATE] == :warned
50
+ ensure
51
+ Thread.current[STATE] = previous if NEEDED
52
+ end
53
+
54
+ # Called by Ruby for each warning. Drops the json gem's binary String warning when it comes
55
+ # from Semantic Logger serializing log data, noting it for .unless_binary_string_warned;
56
+ # passes on every other warning.
57
+ #
58
+ # The category is passed on only to a #warn that accepts it, as Ruby itself does, so that a
59
+ # `Warning.warn(message)` of the application's own keeps working.
60
+ def warn(message, *, **)
61
+ if message.is_a?(String) && message.include?(BINARY_STRING) && Utils.serializing_log_data?
62
+ Thread.current[STATE] = :warned if Thread.current[STATE]
63
+ return
64
+ end
65
+
66
+ Warning.instance_method(:warn).bind(self).super_method.arity == 1 ? super(message) : super
67
+ end
68
+ end
69
+ end
70
+ end
@@ -0,0 +1,139 @@
1
+ require "rbconfig"
2
+
3
+ module SemanticLogger
4
+ # Reports the use of a deprecated method or option as a Ruby deprecation warning, see `Kernel#warn`, so that Ruby
5
+ # decides whether and where it is reported, as it does for its own deprecations, rather than a setting of Semantic
6
+ # Logger:
7
+ # - Only while deprecation warnings are on, see `Warning[:deprecated]`. They are off by default, so production stays
8
+ # quiet, and on in tests run by Minitest or test-unit, or with `ruby -W:deprecated` or `RUBYOPT=-W:deprecated`.
9
+ # - Written to `$stderr`, unless the application routes them elsewhere, such as to its log, or raises them in its
10
+ # tests, by overriding `Warning.warn`.
11
+ #
12
+ # Each warning names the line of the application that used what is deprecated, rather than a line of Semantic
13
+ # Logger, of Ruby itself, or of a gem that Semantic Logger called with a block, see .application_location.
14
+ #
15
+ # Copied from IOStreams::Deprecation, so that both libraries report deprecations the same way.
16
+ module Deprecation
17
+ # The directory of the files of this library, whose lines are skipped when finding the line that used it.
18
+ LIB_DIR = "#{__dir__}/".freeze
19
+ private_constant :LIB_DIR
20
+
21
+ # The file that loads this library, whose lines are skipped too. Only the files of this library are skipped, rather
22
+ # than every file of the directory that holds them, which can hold other libraries, such as `site_ruby`, or the
23
+ # `lib` directory of an application that it is copied into.
24
+ LIB_FILE = File.expand_path("../semantic_logger.rb", __dir__).freeze
25
+ private_constant :LIB_FILE
26
+
27
+ # The text that each warning starts with, after the location of the line that used what is deprecated.
28
+ PREFIX = "SemanticLogger: ".freeze
29
+ private_constant :PREFIX
30
+
31
+ # A warning reported by .warn, as `Kernel#warn` passes it to `Warning.warn`, see .warning?.
32
+ WARNING = /\A(?:.+:\d+: warning: )?#{Regexp.escape(PREFIX)}/
33
+ private_constant :WARNING
34
+
35
+ # The start of the paths of the code of Ruby itself, rather than of a file of it: the core methods that CRuby
36
+ # writes in Ruby, such as `Kernel#tap`, and the files of JRuby itself, when it is loaded from its jar. Only those
37
+ # of JRuby's own home and its own Ruby code in the jar, such as the block that `java_import` calls, since an
38
+ # application packaged in a jar, such as with Warbler, is loaded from it too. Shareable, so that a Ractor other
39
+ # than the main one can report a deprecation.
40
+ RUBY_PATHS = Utils.make_shareable(
41
+ ["<internal:", "uri:classloader:/META-INF/jruby.home/", "uri:classloader:/jruby/"]
42
+ )
43
+ private_constant :RUBY_PATHS
44
+
45
+ # The directory of the standard library of Ruby.
46
+ RUBY_LIB_DIRS = Utils.make_shareable([RbConfig::CONFIG["rubylibdir"]].compact.map { |dir| "#{dir}/" })
47
+ private_constant :RUBY_LIB_DIRS
48
+
49
+ # Reports that the application used something deprecated, unless deprecation warnings are off, with the message,
50
+ # which says what is deprecated and what to use instead, after "SemanticLogger: ", at the line of the application
51
+ # that used it, see .application_location, in the same form as `Kernel#warn` names the line of its caller, such as
52
+ # `config/initializers/logging.rb:12: warning: SemanticLogger: old is deprecated, use new instead`, or without a
53
+ # line when the call stack has none outside this library.
54
+ #
55
+ # Returns nil.
56
+ def self.warn(message)
57
+ return unless Warning[:deprecated]
58
+
59
+ location = application_location
60
+ text = "#{PREFIX}#{message}"
61
+ text = "#{location.path}:#{location.lineno}: warning: #{text}" if location
62
+ Kernel.warn(text, category: :deprecated)
63
+ nil
64
+ end
65
+
66
+ # Returns [true|false] whether the message, as `Kernel#warn` passes it to `Warning.warn`, is a warning reported by
67
+ # .warn, so that an application, or its tests, can tell the deprecation warnings of Semantic Logger from the others.
68
+ def self.warning?(message)
69
+ WARNING.match?(message)
70
+ end
71
+
72
+ # Returns [Thread::Backtrace::Location|nil] the line of the application that used this library, or nil when the
73
+ # call stack has none outside this library. It is the first line of the call stack outside this library, other
74
+ # than:
75
+ # - A line of Ruby itself, see .ruby?, which runs on behalf of its caller, such as `Kernel#tap`, as Ruby names the
76
+ # caller of its own core methods.
77
+ # - A line of a gem that this library called with a block, which has a line of this library further out in the
78
+ # call stack. A line of a gem that called this library, such as one of Rails Semantic Logger, is the one
79
+ # returned, since it is the gem that used it.
80
+ #
81
+ # The call stack is walked outward from the caller, until the line of the application is found, rather than
82
+ # creating all of it.
83
+ def self.application_location
84
+ gem_dirs = installed_gem_dirs
85
+ candidate = nil
86
+ Thread.each_caller_location do |location|
87
+ if library?(location)
88
+ candidate = nil
89
+ elsif gem?(location, gem_dirs)
90
+ candidate ||= location
91
+ elsif !ruby?(location)
92
+ return candidate || location
93
+ end
94
+ end
95
+ candidate
96
+ end
97
+ private_class_method :application_location
98
+
99
+ # Returns [true|false] whether the line of the call stack is in a file of this library. Code run with `eval` has
100
+ # only the file name that it was given.
101
+ def self.library?(location)
102
+ file = location.absolute_path || location.path
103
+ file.start_with?(LIB_DIR) || file == LIB_FILE
104
+ end
105
+ private_class_method :library?
106
+
107
+ # Returns [true|false] whether the line of the call stack is in the code of Ruby itself: a core method, see
108
+ # RUBY_PATHS, including one of JRuby, written in Java, or a file of the standard library of Ruby.
109
+ def self.ruby?(location)
110
+ path = location.path
111
+ path.start_with?(*RUBY_PATHS) || path.end_with?(".java") || in_dirs?(location, RUBY_LIB_DIRS)
112
+ end
113
+ private_class_method :ruby?
114
+
115
+ # Returns [true|false] whether the line of the call stack is in a file of a gem, in one of the directories of the
116
+ # installed gems.
117
+ def self.gem?(location, gem_dirs)
118
+ in_dirs?(location, gem_dirs)
119
+ end
120
+ private_class_method :gem?
121
+
122
+ # Returns [true|false] whether the file of the line of the call stack is in one of the directories, by the path
123
+ # that it was loaded from, or its absolute path, which differs when the path holds a link.
124
+ def self.in_dirs?(location, dirs)
125
+ location.path.start_with?(*dirs) || location.absolute_path&.start_with?(*dirs) || false
126
+ end
127
+ private_class_method :in_dirs?
128
+
129
+ # Returns [Array<String>] the directories of the installed gems, which Bundler can change once it is loaded. None
130
+ # in a Ractor other than the main one, see RactorSupport.other_ractor?, which cannot read the paths of RubyGems, so
131
+ # that a line of a gem is taken there as the line of the application.
132
+ def self.installed_gem_dirs
133
+ return [] if !defined?(::Gem) || RactorSupport.other_ractor?
134
+
135
+ ::Gem.path.map { |dir| dir.end_with?("/") ? dir : "#{dir}/" }
136
+ end
137
+ private_class_method :installed_gem_dirs
138
+ end
139
+ end
@@ -5,14 +5,15 @@ module SemanticLogger
5
5
  # Internal: Log caches the result for each of its exceptions; see Log#exception_details.
6
6
  module ExceptionDetails
7
7
  # Ruby's own Exception#detailed_message: the message, decorated with the class name.
8
- DETAILED_MESSAGE = Exception.instance_method(:detailed_message)
8
+ DETAILED_MESSAGE = Utils.make_shareable(Exception.instance_method(:detailed_message))
9
9
  private_constant :DETAILED_MESSAGE
10
10
 
11
11
  # Returns [String] the detail that #detailed_message adds to the exception's message, without
12
12
  # the class name that Ruby also adds, or nil when there is none or it cannot be separated.
13
13
  #
14
14
  # Never raises, so that an exception's own #detailed_message cannot stop a log entry being
15
- # written.
15
+ # written, nor its #message, which Ruby's #detailed_message calls: as Utils.exception_message,
16
+ # that includes a ScriptError, such as the NotImplementedError of an abstract #message.
16
17
  def self.extract(exception, source: false)
17
18
  detailed = full_detailed_message(exception, source)
18
19
  return unless detailed
@@ -23,7 +24,7 @@ module SemanticLogger
23
24
 
24
25
  details = detailed.delete_prefix(base).sub(/\A\n+/, "").rstrip
25
26
  details unless details.empty?
26
- rescue StandardError
27
+ rescue StandardError, ScriptError
27
28
  nil
28
29
  end
29
30