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
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
118
|
-
|
|
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
|
|
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
|
|
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:
|
|
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
|
-
|
|
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`,
|
|
263
|
-
#
|
|
264
|
-
#
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
417
|
-
|
|
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
|
|
425
|
-
# Returns
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
447
|
-
|
|
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
|
-
|
|
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
|
|
680
|
+
# Returns [Hash] a copy of the named tags currently active for this fiber.
|
|
464
681
|
def self.named_tags
|
|
465
|
-
|
|
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
|
-
(
|
|
686
|
+
Context.push_named_tags(hash)
|
|
478
687
|
hash
|
|
479
688
|
end
|
|
480
689
|
|
|
481
690
|
def self.pop_named_tags(quantity = 1)
|
|
482
|
-
|
|
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
|
|
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
|
-
#
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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"
|