semantic_logger 5.2.0 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/docs/api.md +160 -9
- data/docs/appenders.md +461 -34
- data/docs/config.md +543 -36
- data/docs/log.md +38 -7
- data/docs/metrics.md +139 -28
- data/docs/operations.md +293 -24
- data/docs/rails.md +319 -5
- data/docs/security.md +135 -107
- data/docs/testing.md +23 -0
- data/docs/upgrading.md +644 -1
- data/lib/semantic_logger/appender/async.rb +29 -11
- data/lib/semantic_logger/appender/bugsnag.rb +7 -2
- data/lib/semantic_logger/appender/cloudwatch_logs.rb +46 -6
- data/lib/semantic_logger/appender/elasticsearch_base.rb +197 -29
- data/lib/semantic_logger/appender/elasticsearch_http.rb +22 -5
- data/lib/semantic_logger/appender/file.rb +29 -14
- data/lib/semantic_logger/appender/graylog.rb +81 -7
- data/lib/semantic_logger/appender/honeybadger.rb +7 -1
- data/lib/semantic_logger/appender/honeybadger_insights.rb +8 -2
- data/lib/semantic_logger/appender/http.rb +244 -41
- data/lib/semantic_logger/appender/io.rb +11 -6
- data/lib/semantic_logger/appender/kafka.rb +192 -46
- data/lib/semantic_logger/appender/loki.rb +42 -6
- data/lib/semantic_logger/appender/mongodb.rb +94 -9
- data/lib/semantic_logger/appender/new_relic.rb +2 -3
- data/lib/semantic_logger/appender/new_relic_logs.rb +30 -8
- data/lib/semantic_logger/appender/open_telemetry.rb +37 -35
- data/lib/semantic_logger/appender/rabbitmq.rb +241 -17
- data/lib/semantic_logger/appender/sentry.rb +2 -3
- data/lib/semantic_logger/appender/sentry_ruby.rb +82 -15
- data/lib/semantic_logger/appender/splunk.rb +4 -4
- data/lib/semantic_logger/appender/splunk_http.rb +92 -1
- data/lib/semantic_logger/appender/syslog.rb +89 -10
- data/lib/semantic_logger/appender/tcp.rb +68 -98
- data/lib/semantic_logger/appender/text_output.rb +65 -0
- data/lib/semantic_logger/appender/udp.rb +130 -18
- data/lib/semantic_logger/appender/wrapper.rb +10 -7
- data/lib/semantic_logger/appender.rb +115 -10
- data/lib/semantic_logger/appenders.rb +136 -4
- data/lib/semantic_logger/backtrace_cleaning.rb +77 -0
- data/lib/semantic_logger/base.rb +53 -71
- data/lib/semantic_logger/call_site.rb +235 -0
- data/lib/semantic_logger/context.rb +222 -0
- data/lib/semantic_logger/core_ext/process.rb +20 -5
- data/lib/semantic_logger/core_ext/warning.rb +70 -0
- data/lib/semantic_logger/deprecation.rb +139 -0
- data/lib/semantic_logger/exception_details.rb +4 -3
- data/lib/semantic_logger/formatters/base.rb +139 -19
- data/lib/semantic_logger/formatters/color.rb +3 -4
- data/lib/semantic_logger/formatters/default.rb +35 -7
- data/lib/semantic_logger/formatters/ecs.rb +9 -4
- data/lib/semantic_logger/formatters/json.rb +9 -0
- data/lib/semantic_logger/formatters/logfmt.rb +9 -7
- data/lib/semantic_logger/formatters/loki/labels.rb +282 -0
- data/lib/semantic_logger/formatters/loki.rb +412 -24
- data/lib/semantic_logger/formatters/new_relic_logs.rb +15 -13
- data/lib/semantic_logger/formatters/one_line.rb +44 -10
- data/lib/semantic_logger/formatters/open_telemetry.rb +186 -29
- data/lib/semantic_logger/formatters/pattern.rb +60 -8
- data/lib/semantic_logger/formatters/raw.rb +38 -8
- data/lib/semantic_logger/formatters/signalfx.rb +55 -15
- data/lib/semantic_logger/formatters/syslog.rb +4 -2
- data/lib/semantic_logger/formatters/syslog_cee.rb +10 -4
- data/lib/semantic_logger/formatters/syslog_header.rb +49 -0
- data/lib/semantic_logger/formatters.rb +1 -0
- data/lib/semantic_logger/log.rb +236 -80
- data/lib/semantic_logger/loggable.rb +55 -95
- data/lib/semantic_logger/logger.rb +31 -5
- data/lib/semantic_logger/metric/new_relic.rb +32 -17
- data/lib/semantic_logger/metric/signalfx.rb +21 -12
- data/lib/semantic_logger/metric/statsd.rb +26 -8
- data/lib/semantic_logger/processor.rb +194 -5
- data/lib/semantic_logger/queue_processor/backoff.rb +140 -0
- data/lib/semantic_logger/queue_processor/batch_failure.rb +69 -0
- data/lib/semantic_logger/queue_processor/held_write.rb +62 -0
- data/lib/semantic_logger/queue_processor/inbox.rb +97 -0
- data/lib/semantic_logger/queue_processor/reopener.rb +56 -0
- data/lib/semantic_logger/queue_processor/reporter.rb +113 -0
- data/lib/semantic_logger/queue_processor/request.rb +48 -10
- data/lib/semantic_logger/queue_processor/throttled_counter.rb +60 -17
- data/lib/semantic_logger/queue_processor.rb +426 -176
- data/lib/semantic_logger/ractor_copy.rb +120 -0
- data/lib/semantic_logger/ractor_processor.rb +82 -0
- data/lib/semantic_logger/ractor_receiver.rb +282 -0
- data/lib/semantic_logger/ractor_support.rb +28 -0
- data/lib/semantic_logger/redactor.rb +310 -0
- data/lib/semantic_logger/semantic_logger.rb +313 -79
- data/lib/semantic_logger/subscriber.rb +169 -15
- data/lib/semantic_logger/sync_processor.rb +226 -26
- data/lib/semantic_logger/test/capture_log_events.rb +20 -2
- data/lib/semantic_logger/test/minitest.rb +2 -1
- data/lib/semantic_logger/test/rspec.rb +1 -1
- data/lib/semantic_logger/trap_safe.rb +113 -0
- data/lib/semantic_logger/utils.rb +266 -79
- data/lib/semantic_logger/version.rb +1 -1
- data/lib/semantic_logger.rb +35 -2
- metadata +22 -2
|
@@ -0,0 +1,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
|
|
9
|
-
# through (`Kernel#fork`, `Process.fork`, `IO.popen
|
|
10
|
-
#
|
|
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
|
|