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
|
@@ -16,7 +16,8 @@ module SemanticLogger
|
|
|
16
16
|
# Methods forwarded directly to the wrapped appender (run on the caller's thread).
|
|
17
17
|
def_delegators :@appender,
|
|
18
18
|
:name, :should_log?, :filter, :host, :application, :environment,
|
|
19
|
-
:level, :level=, :logger, :logger=, :console_stream,
|
|
19
|
+
:level, :level=, :formatter, :formatter=, :logger, :logger=, :console_stream,
|
|
20
|
+
:console_output?
|
|
20
21
|
|
|
21
22
|
# Methods forwarded to the queue processor that owns the thread and queue.
|
|
22
23
|
# Tuning options (max_queue_size, batch_size, non_blocking, ...) are set once at
|
|
@@ -24,8 +25,9 @@ module SemanticLogger
|
|
|
24
25
|
# read back are re-exposed here. lag_* and non_blocking= back the public
|
|
25
26
|
# SemanticLogger.lag_* and SemanticLogger.non_blocking= API on the main Processor.
|
|
26
27
|
def_delegators :@processor,
|
|
27
|
-
:log, :flush, :close, :
|
|
28
|
-
:
|
|
28
|
+
:log, :flush, :close, :renew_after_fork, :process_exiting=, :thread, :active?,
|
|
29
|
+
:worker_thread?, :holding_up?,
|
|
30
|
+
:queue, :max_queue_size, :capped?, :non_blocking?, :non_blocking=, :batch?,
|
|
29
31
|
:lag_check_interval, :lag_check_interval=,
|
|
30
32
|
:lag_threshold_s, :lag_threshold_s=,
|
|
31
33
|
:processed_count, :dropped_count, :failed_count
|
|
@@ -73,20 +75,27 @@ module SemanticLogger
|
|
|
73
75
|
# Default: false
|
|
74
76
|
#
|
|
75
77
|
# dropped_message_report_seconds: [Integer]
|
|
76
|
-
#
|
|
77
|
-
#
|
|
78
|
-
#
|
|
78
|
+
# Log the count of messages dropped because the queue was full, with non_blocking or once
|
|
79
|
+
# the worker thread has stopped (see async_max_retries), to the internal logger at most
|
|
80
|
+
# once every this number of seconds. Also limits how often messages discarded because
|
|
81
|
+
# they could not be written are reported, after the first.
|
|
79
82
|
# Default: 30
|
|
80
83
|
#
|
|
81
84
|
# async_max_retries: [Integer]
|
|
82
85
|
# Maximum number of consecutive times to restart the worker thread (with a back-off)
|
|
83
86
|
# after it raises an exception while processing messages, before giving up and stopping
|
|
84
87
|
# the thread. The counter resets after any message is processed successfully.
|
|
88
|
+
# Once stopped, messages are dropped when the queue is full, rather than block.
|
|
85
89
|
# -1: Retry indefinitely and never stop the thread (the pre-v5 behaviour).
|
|
86
90
|
# Default: 100
|
|
91
|
+
#
|
|
92
|
+
# The proxy also answers #wrapped_logger, the logger that the appender writes to, when the
|
|
93
|
+
# appender has one, such as one added with `logger:`, so that it is found the same way with or
|
|
94
|
+
# without async: true. The proxy of any other appender does not respond to it.
|
|
87
95
|
def initialize(appender:, **args)
|
|
88
96
|
@appender = appender
|
|
89
97
|
@processor = QueueProcessor.start(appender: appender, **args)
|
|
98
|
+
define_singleton_method(:wrapped_logger) { @appender.wrapped_logger } if appender.respond_to?(:wrapped_logger)
|
|
90
99
|
end
|
|
91
100
|
|
|
92
101
|
# Returns [String] the class and object address of this proxy, whether it batches, and the
|
|
@@ -97,9 +106,16 @@ module SemanticLogger
|
|
|
97
106
|
"#{address} batch=#{batch?} appender=#{appender.inspect}>"
|
|
98
107
|
end
|
|
99
108
|
|
|
100
|
-
# Re-open appender after a fork
|
|
109
|
+
# Re-open the wrapped appender and the queue processor, after a fork, or within the same
|
|
110
|
+
# process, such as after a log rotation (see QueueProcessor#reopen).
|
|
111
|
+
#
|
|
112
|
+
# The wrapped appender is reopened by the worker thread, before it writes again, so that it
|
|
113
|
+
# is never reopened while it is writing, and not in a signal trap, from which this is often
|
|
114
|
+
# called. So this returns before it has reopened, and a reopen that fails, such as for a server
|
|
115
|
+
# name that no longer resolves, is reported by the worker thread, which carries on. After a
|
|
116
|
+
# fork, the child then always has a worker thread, which reopens the appender before it
|
|
117
|
+
# writes anything.
|
|
101
118
|
def reopen
|
|
102
|
-
appender.reopen if appender.respond_to?(:reopen)
|
|
103
119
|
processor.reopen
|
|
104
120
|
end
|
|
105
121
|
|
|
@@ -113,9 +129,11 @@ module SemanticLogger
|
|
|
113
129
|
# max_queue_size: [Integer] Maximum queue size, or nil when uncapped.
|
|
114
130
|
# processed: [Integer] Cumulative number of log messages written since startup.
|
|
115
131
|
# dropped: [Integer] Cumulative number of log messages dropped because the queue
|
|
116
|
-
# was full
|
|
117
|
-
#
|
|
118
|
-
#
|
|
132
|
+
# was full: with non_blocking enabled, or once the worker
|
|
133
|
+
# thread has stopped (see async_max_retries).
|
|
134
|
+
# failed: [Integer] Cumulative number of log messages discarded because they
|
|
135
|
+
# could not be written, whether their content or the
|
|
136
|
+
# destination was at fault (see Subscriber#message_error?).
|
|
119
137
|
def stats
|
|
120
138
|
{
|
|
121
139
|
name: name,
|
|
@@ -56,7 +56,12 @@ module SemanticLogger
|
|
|
56
56
|
|
|
57
57
|
# Send error messages as Runtime exceptions
|
|
58
58
|
exception = extract_exception(log)
|
|
59
|
-
|
|
59
|
+
# Bugsnag replaces each byte of text that is not valid UTF-8 with U+FFFD, including binary
|
|
60
|
+
# text that holds UTF-8, such as a response body, so the data is sent as a copy with its
|
|
61
|
+
# text converted to valid UTF-8, as the JSON formatters write it, and a Hash or Array nested
|
|
62
|
+
# too deeply, or that holds itself, cut off there as they cut it off (see
|
|
63
|
+
# Utils.encode_utf8). Any other object is sent as it is, for Bugsnag to clean.
|
|
64
|
+
hash = format_log(log) { |data| Utils.encode_utf8(data) }
|
|
60
65
|
bugsnag_notify(exception, hash, log_level(log.level))
|
|
61
66
|
true
|
|
62
67
|
end
|
|
@@ -82,7 +87,7 @@ module SemanticLogger
|
|
|
82
87
|
return log.exception
|
|
83
88
|
end
|
|
84
89
|
|
|
85
|
-
error = RuntimeError.new(log.message)
|
|
90
|
+
error = RuntimeError.new(log.message && Utils.encode_utf8_string(log.message.to_s))
|
|
86
91
|
error.set_backtrace(log.backtrace) if log.backtrace
|
|
87
92
|
error
|
|
88
93
|
end
|
|
@@ -102,19 +102,40 @@ module SemanticLogger
|
|
|
102
102
|
put_log_events while buffered_logs.size.positive?
|
|
103
103
|
end
|
|
104
104
|
|
|
105
|
+
# Shuts down the timer, and sends the buffered log events, such as when the appender is removed,
|
|
106
|
+
# which does not flush it first. It has no timer when building the client failed as it was reopened
|
|
107
|
+
# after a fork.
|
|
108
|
+
#
|
|
109
|
+
# In a forked child that has not reopened, such as one that removes the appender before its reopen
|
|
110
|
+
# has run, it first forgets the timer and the buffered log events it inherited, which the parent
|
|
111
|
+
# sends (see #reopen), so that it sends only its own.
|
|
105
112
|
def close
|
|
106
|
-
|
|
113
|
+
forget_inherited
|
|
114
|
+
task&.shutdown
|
|
115
|
+
flush
|
|
107
116
|
end
|
|
108
117
|
|
|
118
|
+
# Builds a new client, starts a new timer that sends the buffered log events every
|
|
119
|
+
# force_flush_interval_seconds, and then shuts down the timer it replaces, such as after a log
|
|
120
|
+
# rotation. The buffered log events are kept, for the new timer to send. When building the client
|
|
121
|
+
# fails, it raises, and keeps the client and timer it has. An error shutting down the replaced
|
|
122
|
+
# timer is reported to the internal logger, rather than raised.
|
|
123
|
+
#
|
|
124
|
+
# After a fork, the child starts with no buffered log events, since the parent sends those it
|
|
125
|
+
# had, and forgets the timer it inherited, without shutting it down: concurrent-ruby drops the
|
|
126
|
+
# parent's scheduled runs in the child, so that timer never runs there. When building the client
|
|
127
|
+
# fails in the child, the appender has no timer, and sends the buffered log events only once
|
|
128
|
+
# max_buffered_events are buffered, or it is flushed, until a reopen succeeds.
|
|
109
129
|
def reopen
|
|
110
|
-
|
|
111
|
-
@client
|
|
112
|
-
|
|
113
|
-
@task
|
|
114
|
-
|
|
130
|
+
forget_inherited
|
|
131
|
+
@client = Aws::CloudWatchLogs::Client.new(client_kwargs)
|
|
132
|
+
replaced = @task
|
|
133
|
+
@task = Concurrent::TimerTask.new(execution_interval: force_flush_interval_seconds,
|
|
134
|
+
interval_type: :fixed_rate) do
|
|
115
135
|
put_log_events
|
|
116
136
|
end
|
|
117
137
|
@task.execute
|
|
138
|
+
shut_down_replaced(replaced)
|
|
118
139
|
end
|
|
119
140
|
|
|
120
141
|
# Use JSON Formatter by default
|
|
@@ -130,6 +151,25 @@ module SemanticLogger
|
|
|
130
151
|
|
|
131
152
|
private
|
|
132
153
|
|
|
154
|
+
# Starts with no buffered log events, and no timer, in a process other than the one that buffered the
|
|
155
|
+
# log events and started the timer: when the appender is created, and in a child process after a fork,
|
|
156
|
+
# where it forgets those of the parent. Records the process. See #reopen.
|
|
157
|
+
def forget_inherited
|
|
158
|
+
return if @pid == ::Process.pid
|
|
159
|
+
|
|
160
|
+
@task = nil
|
|
161
|
+
@buffered_logs = Concurrent::Array.new
|
|
162
|
+
@pid = ::Process.pid
|
|
163
|
+
end
|
|
164
|
+
|
|
165
|
+
# Shuts down the timer that a reopen replaced, if any. Reports an error to the internal logger as a
|
|
166
|
+
# warning, rather than raising it, since the new timer already sends the buffered log events.
|
|
167
|
+
def shut_down_replaced(task)
|
|
168
|
+
task&.shutdown
|
|
169
|
+
rescue StandardError => e
|
|
170
|
+
logger.warn("Could not shut down the timer that a reopen replaced", e)
|
|
171
|
+
end
|
|
172
|
+
|
|
133
173
|
# Returns [Hash] the PutLogEvents log event for the log message.
|
|
134
174
|
def log_event(log)
|
|
135
175
|
{timestamp: (log.time.to_f * 1000).floor, message: event_message(format_log(log))}
|
|
@@ -12,6 +12,18 @@ module SemanticLogger
|
|
|
12
12
|
# `SemanticLogger.add_appender(appender: :elasticsearch, ...)` or
|
|
13
13
|
# `appender: :opensearch`, never by referencing this class directly.
|
|
14
14
|
class ElasticsearchBase < SemanticLogger::Subscriber
|
|
15
|
+
# The most groups of failures that one report of a bulk request lists (see #report_failures).
|
|
16
|
+
MAX_REPORTED_FAILURES = 10
|
|
17
|
+
# The most characters of each reason that the report writes: a reason can repeat a whole value,
|
|
18
|
+
# as the "For input string" of a number that could not be parsed does.
|
|
19
|
+
MAX_REPORTED_REASON = 500
|
|
20
|
+
# The seconds to wait before each time that the entries the server rejected with status 429 are
|
|
21
|
+
# sent again (see #bulk_write): three times, after 0.2, 0.4, then 0.8 seconds, so waits of at
|
|
22
|
+
# most 1.4 seconds for a request, plus up to 3 more bulk requests. Kept short, since waiting
|
|
23
|
+
# holds up the thread that writes the entries.
|
|
24
|
+
RESEND_DELAYS = [0.2, 0.4, 0.8].freeze
|
|
25
|
+
private_constant :MAX_REPORTED_FAILURES, :MAX_REPORTED_REASON, :RESEND_DELAYS
|
|
26
|
+
|
|
15
27
|
attr_accessor :url, :index, :date_pattern, :client, :flush_interval, :timeout_interval, :batch_size,
|
|
16
28
|
:client_args
|
|
17
29
|
|
|
@@ -29,6 +41,12 @@ module SemanticLogger
|
|
|
29
41
|
# if you want monthly indexes ('%Y.%m') or weekly ('%Y.%W').
|
|
30
42
|
# Default: '%Y.%m.%d'
|
|
31
43
|
#
|
|
44
|
+
# data_stream: [true|false]
|
|
45
|
+
# Write to the data stream named by `index:`, with `create` actions,
|
|
46
|
+
# rather than to a daily index: `date_pattern:` is not used, and the
|
|
47
|
+
# default formatter writes the time under `@timestamp`.
|
|
48
|
+
# Default: false
|
|
49
|
+
#
|
|
32
50
|
# type: [String]
|
|
33
51
|
# Deprecated and ignored. Document `_type` has been unused since
|
|
34
52
|
# Elasticsearch 7 and is ignored by OpenSearch. Passing it logs a
|
|
@@ -36,12 +54,15 @@ module SemanticLogger
|
|
|
36
54
|
#
|
|
37
55
|
# level: [:trace | :debug | :info | :warn | :error | :fatal]
|
|
38
56
|
# Override the log level for this appender.
|
|
39
|
-
# Default:
|
|
57
|
+
# Default: none (:trace), so it writes every entry that a logger emits; each logger
|
|
58
|
+
# filters by its own level.
|
|
40
59
|
#
|
|
41
60
|
# formatter: [Object|Proc|Symbol|Hash]
|
|
42
61
|
# An instance of a class that implements #call, or a Proc to be used to format
|
|
43
|
-
# the output from this appender
|
|
44
|
-
#
|
|
62
|
+
# the output from this appender. It returns the document, as a Hash, or as a
|
|
63
|
+
# String of JSON.
|
|
64
|
+
# Default: :raw, with an ISO 8601 time under `timestamp`, or `@timestamp` with
|
|
65
|
+
# `data_stream: true`.
|
|
45
66
|
#
|
|
46
67
|
# filter: [Regexp|Proc]
|
|
47
68
|
# RegExp: Only include log messages where the class name matches the supplied.
|
|
@@ -57,6 +78,10 @@ module SemanticLogger
|
|
|
57
78
|
# Name of this application to appear in log messages.
|
|
58
79
|
# Default: SemanticLogger.application
|
|
59
80
|
#
|
|
81
|
+
# metrics: [true|false]
|
|
82
|
+
# Whether to also index metric-only entries: a metric without a message or an exception.
|
|
83
|
+
# Default: false
|
|
84
|
+
#
|
|
60
85
|
# Client Parameters (passed through to the backing client):
|
|
61
86
|
# url: [String]
|
|
62
87
|
# Fully qualified address to the service.
|
|
@@ -64,9 +89,13 @@ module SemanticLogger
|
|
|
64
89
|
#
|
|
65
90
|
# hosts: [String|Hash|Array]
|
|
66
91
|
# Single host passed as a String or Hash, or multiple hosts
|
|
67
|
-
# passed as an Array
|
|
92
|
+
# passed as an Array. A Hash takes the keys `host`, `port`,
|
|
93
|
+
# `scheme`, `user`, `password`, and `path`.
|
|
68
94
|
# Note:
|
|
69
95
|
# :url above is ignored when supplying this option.
|
|
96
|
+
# A `host:` passed to the appender itself, outside the Hash, is
|
|
97
|
+
# not a server: it is the host name written in each log entry,
|
|
98
|
+
# see `host:` above.
|
|
70
99
|
#
|
|
71
100
|
# resurrect_after [Float]
|
|
72
101
|
# After how many seconds a dead connection should be tried again.
|
|
@@ -131,13 +160,13 @@ module SemanticLogger
|
|
|
131
160
|
environment: nil,
|
|
132
161
|
host: nil,
|
|
133
162
|
data_stream: false,
|
|
163
|
+
metrics: false,
|
|
134
164
|
**client_args,
|
|
135
165
|
&)
|
|
136
166
|
if type
|
|
137
|
-
|
|
167
|
+
Deprecation.warn(
|
|
138
168
|
"The Elasticsearch/OpenSearch appender `type:` parameter is deprecated and will be removed in v6. " \
|
|
139
|
-
"Document `_type` has been unused since Elasticsearch 7 and is ignored by OpenSearch."
|
|
140
|
-
category: :deprecated
|
|
169
|
+
"Document `_type` has been unused since Elasticsearch 7 and is ignored by OpenSearch."
|
|
141
170
|
)
|
|
142
171
|
end
|
|
143
172
|
|
|
@@ -150,7 +179,7 @@ module SemanticLogger
|
|
|
150
179
|
@data_stream = data_stream
|
|
151
180
|
|
|
152
181
|
super(level: level, formatter: formatter, filter: filter, application: application,
|
|
153
|
-
environment: environment, host: host, metrics:
|
|
182
|
+
environment: environment, host: host, metrics: metrics, &)
|
|
154
183
|
reopen
|
|
155
184
|
end
|
|
156
185
|
|
|
@@ -160,19 +189,14 @@ module SemanticLogger
|
|
|
160
189
|
@client = Utils.without_url_in_errors(option: ":url or :hosts") { client_class.new(@client_args) }
|
|
161
190
|
end
|
|
162
191
|
|
|
163
|
-
# Log to the index for today
|
|
192
|
+
# Log to the index for today, or to the data stream.
|
|
164
193
|
def log(log)
|
|
165
|
-
bulk_write([
|
|
194
|
+
bulk_write([bulk_entry(log)])
|
|
166
195
|
true
|
|
167
196
|
end
|
|
168
197
|
|
|
169
198
|
def batch(logs)
|
|
170
|
-
|
|
171
|
-
logs.each do |log|
|
|
172
|
-
messages << bulk_index(log) << bulk_line(log)
|
|
173
|
-
end
|
|
174
|
-
|
|
175
|
-
bulk_write(messages)
|
|
199
|
+
bulk_write(logs.map { |log| bulk_entry(log) })
|
|
176
200
|
true
|
|
177
201
|
end
|
|
178
202
|
|
|
@@ -194,6 +218,12 @@ module SemanticLogger
|
|
|
194
218
|
raise NotImplementedError, "#{self.class} must implement #client_class"
|
|
195
219
|
end
|
|
196
220
|
|
|
221
|
+
# Returns [Array] the entry of a bulk request for the log message: its action, and its document
|
|
222
|
+
# (see #bulk_line).
|
|
223
|
+
def bulk_entry(log)
|
|
224
|
+
[bulk_index(log), bulk_line(log)]
|
|
225
|
+
end
|
|
226
|
+
|
|
197
227
|
# Returns [String] the log message formatted as a bulk line, serialized by Utils.to_json
|
|
198
228
|
# and handed to the client as a String. The client gem's serializer writes Infinity and NaN
|
|
199
229
|
# as bare words, which is not JSON, and does not repair invalid UTF-8, a structure nested too
|
|
@@ -205,27 +235,165 @@ module SemanticLogger
|
|
|
205
235
|
format_log(log) { |document| document.is_a?(String) ? document : Utils.to_json(document) }
|
|
206
236
|
end
|
|
207
237
|
|
|
208
|
-
#
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
238
|
+
# Sends the entries in one bulk request, then sends again those that the server rejected with
|
|
239
|
+
# status 429 (see #resend_rejected). The entries still not indexed after that, for this or any
|
|
240
|
+
# other reason, are reported and discarded (see #report_failures).
|
|
241
|
+
#
|
|
242
|
+
# The other entries were indexed, so an error raised while sending the rejected ones again,
|
|
243
|
+
# such as a timeout, is reported with the failures, rather than raised, which would count every
|
|
244
|
+
# entry as discarded.
|
|
245
|
+
def bulk_write(entries)
|
|
246
|
+
failed = bulk_failures(entries)
|
|
247
|
+
return if failed.empty?
|
|
248
|
+
|
|
249
|
+
begin
|
|
250
|
+
resend_rejected(entries, failed)
|
|
251
|
+
rescue StandardError => e
|
|
252
|
+
error = e
|
|
253
|
+
end
|
|
254
|
+
report_failures(failed.values, entries.size, error) unless failed.empty?
|
|
255
|
+
end
|
|
256
|
+
|
|
257
|
+
# Sends again the entries that the server rejected with status 429, since its write queue was
|
|
258
|
+
# full, so that they are likely to be indexed a little later. Only those entries are sent again,
|
|
259
|
+
# so that none is indexed twice. They are sent up to RESEND_DELAYS.size more times, after a
|
|
260
|
+
# growing wait, which holds up the thread writing the entries: the appender's own thread when it
|
|
261
|
+
# writes in batches, as it does by default, or with `async: true`. Otherwise it is the thread
|
|
262
|
+
# that writes to every appender, or with SemanticLogger.sync!, the thread that logged, and every
|
|
263
|
+
# other thread that logs waits for it.
|
|
264
|
+
#
|
|
265
|
+
# `failed` holds the result of each entry not indexed, by its position in `entries` (see
|
|
266
|
+
# #bulk_failures). The result of an entry sent again replaces it, and an entry then indexed is
|
|
267
|
+
# removed.
|
|
268
|
+
def resend_rejected(entries, failed)
|
|
269
|
+
RESEND_DELAYS.each do |delay|
|
|
270
|
+
resend = failed.keys.select { |position| failed[position]["status"].to_i == 429 }
|
|
271
|
+
break if resend.empty?
|
|
272
|
+
|
|
273
|
+
sleep(delay)
|
|
274
|
+
again = bulk_failures(resend.map { |position| entries[position] })
|
|
275
|
+
resend.each_with_index do |position, resent|
|
|
276
|
+
if again.key?(resent)
|
|
277
|
+
failed[position] = again[resent]
|
|
278
|
+
else
|
|
279
|
+
failed.delete(position)
|
|
280
|
+
end
|
|
216
281
|
end
|
|
282
|
+
end
|
|
283
|
+
end
|
|
284
|
+
|
|
285
|
+
# Sends the entries in one bulk request, serializing their actions; their documents already
|
|
286
|
+
# are (see #bulk_line).
|
|
287
|
+
#
|
|
288
|
+
# Returns [Hash{Integer => Hash}] the result of each entry that was not indexed, by its
|
|
289
|
+
# position in `entries`. The response has an item for each entry, in order, under the name of
|
|
290
|
+
# its action, such as
|
|
291
|
+
# `{"index" => {"_index" => ..., "status" => 400, "error" => {"type" => ..., "reason" => ...}}}`,
|
|
292
|
+
# without the document. An entry failed when its result has an error, or a status of 300 or
|
|
293
|
+
# above: an `index` action succeeds with 201 (created) or 200 (updated), and a `create` action
|
|
294
|
+
# with 201.
|
|
295
|
+
def bulk_failures(entries)
|
|
296
|
+
body = entries.flat_map { |action, document| [action.to_json, document] }
|
|
297
|
+
bulk_result = @data_stream ? @client.bulk(index: index, body: body) : @client.bulk(body: body)
|
|
298
|
+
return {} unless bulk_result["errors"]
|
|
299
|
+
|
|
300
|
+
failures = {}
|
|
301
|
+
bulk_result["items"].each_with_index do |item, position|
|
|
302
|
+
result = item.values.first
|
|
303
|
+
failures[position] = result if result.key?("error") || result["status"].to_i >= 300
|
|
304
|
+
end
|
|
305
|
+
failures
|
|
306
|
+
end
|
|
307
|
+
|
|
308
|
+
# Reports to the internal logger the results of the entries of a bulk request that were not
|
|
309
|
+
# indexed, of `total` entries, which are discarded (see #bulk_write), with the error that
|
|
310
|
+
# stopped sending them again, if any. The failures are grouped by their kind (see
|
|
311
|
+
# #bulk_failure_kind), since the reasons for one kind differ by each entry's id and value, so
|
|
312
|
+
# that a batch whose entries all fail the same way is reported in a short line. Only the first
|
|
313
|
+
# MAX_REPORTED_FAILURES groups are listed.
|
|
314
|
+
def report_failures(failed, total, error = nil)
|
|
315
|
+
groups = failed.group_by { |result| bulk_failure_kind(result) }
|
|
316
|
+
listed = groups.first(MAX_REPORTED_FAILURES).map do |kind, results|
|
|
317
|
+
bulk_failure(kind, results.first["error"], results.size)
|
|
318
|
+
end
|
|
319
|
+
others = groups.values.drop(MAX_REPORTED_FAILURES)
|
|
320
|
+
unless others.empty?
|
|
321
|
+
listed << "and #{others.size} other failure#{'s' unless others.size == 1} " \
|
|
322
|
+
"(#{bulk_entries(others.sum(&:size))})"
|
|
323
|
+
end
|
|
324
|
+
|
|
325
|
+
message = "#{failed.size} of #{total} log entries were not indexed, and are discarded: #{listed.join('; ')}"
|
|
326
|
+
logger.error(message, error)
|
|
327
|
+
end
|
|
328
|
+
|
|
329
|
+
# Returns [Array] the kind of failure of an entry, from the result of its action: its status,
|
|
330
|
+
# error type, and index, and the type of the innermost error that caused it, so that a number
|
|
331
|
+
# and a date that could not be parsed, both a mapping error, are told apart. An error that is a
|
|
332
|
+
# String, as from Elasticsearch 1.x, has no type.
|
|
333
|
+
def bulk_failure_kind(result)
|
|
334
|
+
error = result["error"]
|
|
335
|
+
return [result["status"], nil, result["_index"], nil] unless error.is_a?(Hash)
|
|
336
|
+
|
|
337
|
+
[result["status"], error["type"], result["_index"], bulk_causes(error).last&.fetch("type", nil)]
|
|
338
|
+
end
|
|
339
|
+
|
|
340
|
+
# Returns [String] a kind of failure of the given number of entries: its status, error type,
|
|
341
|
+
# and index, then the error of the first, as an example when there are others.
|
|
342
|
+
def bulk_failure(kind, error, count)
|
|
343
|
+
status, type, index = kind
|
|
344
|
+
failure = [status, type, "in #{index}"].compact.join(" ")
|
|
345
|
+
failure += " (#{bulk_entries(count)})" if count > 1
|
|
346
|
+
reason = bulk_error_reason(error)
|
|
347
|
+
return failure unless reason
|
|
217
348
|
|
|
218
|
-
|
|
349
|
+
"#{failure}#{', e.g.' if count > 1}: #{reason}"
|
|
350
|
+
end
|
|
351
|
+
|
|
352
|
+
# Returns [String] the reason for an error, followed by each error that caused it, such as the
|
|
353
|
+
# parser's error under a mapping error's "failed to parse", or nil when it has none. An error
|
|
354
|
+
# that is a String is its reason. A cause without a reason is written as its type alone.
|
|
355
|
+
def bulk_error_reason(error)
|
|
356
|
+
return bulk_reason_text(error) unless error.is_a?(Hash)
|
|
357
|
+
|
|
358
|
+
reasons = [bulk_reason_text(error["reason"])]
|
|
359
|
+
bulk_causes(error).each do |cause|
|
|
360
|
+
reason = bulk_reason_text(cause["reason"])
|
|
361
|
+
reasons << (reason ? "caused by #{cause['type']}: #{reason}" : "caused by #{cause['type']}")
|
|
362
|
+
end
|
|
363
|
+
reasons.compact!
|
|
364
|
+
reasons.join(", ") unless reasons.empty?
|
|
365
|
+
end
|
|
366
|
+
|
|
367
|
+
# Returns [Array<Hash>] the errors that caused this one, from the first to the innermost.
|
|
368
|
+
def bulk_causes(error)
|
|
369
|
+
causes = []
|
|
370
|
+
cause = error
|
|
371
|
+
causes << cause while (cause = cause["caused_by"]).is_a?(Hash)
|
|
372
|
+
causes
|
|
373
|
+
end
|
|
374
|
+
|
|
375
|
+
# Returns [String] a reason as the report writes it, or nil when there is none: its first line
|
|
376
|
+
# only, since the JSON parser adds the error's location on the next, with part of the document;
|
|
377
|
+
# cut to MAX_REPORTED_REASON characters, followed by "..."; and inspected, since it can repeat a
|
|
378
|
+
# value of the entry, so that a control character in that value, such as a line break, cannot
|
|
379
|
+
# forge a line of the log.
|
|
380
|
+
def bulk_reason_text(reason)
|
|
381
|
+
text = reason.to_s.partition("\n").first
|
|
382
|
+
return if text.empty?
|
|
383
|
+
return text.inspect if text.size <= MAX_REPORTED_REASON
|
|
384
|
+
|
|
385
|
+
"#{text[0, MAX_REPORTED_REASON].inspect}..."
|
|
386
|
+
end
|
|
219
387
|
|
|
220
|
-
|
|
221
|
-
|
|
388
|
+
# Returns [String] the number of entries, such as "1 entry" or "3 entries".
|
|
389
|
+
def bulk_entries(count)
|
|
390
|
+
count == 1 ? "1 entry" : "#{count} entries"
|
|
222
391
|
end
|
|
223
392
|
|
|
224
393
|
def bulk_index(log)
|
|
225
|
-
expanded_index_name = log.time.strftime("#{index}-#{date_pattern}")
|
|
226
394
|
return {"create" => {}} if @data_stream
|
|
227
395
|
|
|
228
|
-
{"index" => {"_index" =>
|
|
396
|
+
{"index" => {"_index" => log.time.strftime("#{index}-#{date_pattern}")}}
|
|
229
397
|
end
|
|
230
398
|
|
|
231
399
|
def default_formatter
|
|
@@ -3,7 +3,8 @@ require "date"
|
|
|
3
3
|
#
|
|
4
4
|
# Note:
|
|
5
5
|
# * Other than in very low volume environments it is recommended to rather use the Elasticsearch appender,
|
|
6
|
-
# since it supports bulk logging.
|
|
6
|
+
# since it supports bulk logging. This appender cannot be batched: with `batch: true`, add_appender raises
|
|
7
|
+
# ArgumentError (see #batch_refusal).
|
|
7
8
|
#
|
|
8
9
|
# Example:
|
|
9
10
|
# SemanticLogger.add_appender(
|
|
@@ -31,7 +32,8 @@ module SemanticLogger
|
|
|
31
32
|
#
|
|
32
33
|
# level: [:trace | :debug | :info | :warn | :error | :fatal]
|
|
33
34
|
# Override the log level for this appender.
|
|
34
|
-
# Default:
|
|
35
|
+
# Default: none (:trace), so it writes every entry that a logger emits; each logger
|
|
36
|
+
# filters by its own level.
|
|
35
37
|
#
|
|
36
38
|
# formatter: [Object|Proc|Symbol|Hash]
|
|
37
39
|
# An instance of a class that implements #call, or a Proc to be used to format
|
|
@@ -57,10 +59,9 @@ module SemanticLogger
|
|
|
57
59
|
**http_args,
|
|
58
60
|
&)
|
|
59
61
|
if type
|
|
60
|
-
|
|
62
|
+
Deprecation.warn(
|
|
61
63
|
"The Elasticsearch/OpenSearch appender `type:` parameter is deprecated and will be removed in v6. " \
|
|
62
|
-
"Document `_type` has been unused since Elasticsearch 7 and is ignored by OpenSearch."
|
|
63
|
-
category: :deprecated
|
|
64
|
+
"Document `_type` has been unused since Elasticsearch 7 and is ignored by OpenSearch."
|
|
64
65
|
)
|
|
65
66
|
end
|
|
66
67
|
|
|
@@ -80,6 +81,22 @@ module SemanticLogger
|
|
|
80
81
|
def delete_all(date = Date.today)
|
|
81
82
|
delete(date.strftime(@request_path))
|
|
82
83
|
end
|
|
84
|
+
|
|
85
|
+
# Elasticsearch indexes a batch of documents only through its bulk API, which the :elasticsearch
|
|
86
|
+
# appender uses. The #batch inherited from Appender::Http posts the batch as a JSON array to the
|
|
87
|
+
# url's own path, such as `/`, which Elasticsearch rejects, so add_appender refuses to batch it.
|
|
88
|
+
#
|
|
89
|
+
# Answers only while that #batch is the one in use (see Subscriber#batch_defined_by?), so that a
|
|
90
|
+
# subclass with a #batch of its own, such as one that posts the batch to the bulk API, is batched
|
|
91
|
+
# as before. One whose #batch calls super still posts a JSON array, so it defines its own
|
|
92
|
+
# #batch_refusal.
|
|
93
|
+
def batch_refusal
|
|
94
|
+
return unless batch_defined_by?(Http)
|
|
95
|
+
|
|
96
|
+
"Elasticsearch indexes a batch of entries only through its bulk API, which this appender does not " \
|
|
97
|
+
"use. Use appender: :elasticsearch to send the entries in batches, or add this appender without " \
|
|
98
|
+
"batch: true."
|
|
99
|
+
end
|
|
83
100
|
end
|
|
84
101
|
end
|
|
85
102
|
end
|
|
@@ -56,7 +56,8 @@ module SemanticLogger
|
|
|
56
56
|
#
|
|
57
57
|
# :level [:trace | :debug | :info | :warn | :error | :fatal]
|
|
58
58
|
# Override the log level for this appender.
|
|
59
|
-
# Default:
|
|
59
|
+
# Default: none (:trace), so it writes every entry that a logger emits; each logger
|
|
60
|
+
# filters by its own level.
|
|
60
61
|
#
|
|
61
62
|
# :formatter: [Object|Proc]
|
|
62
63
|
# An instance of a class that implements #call, or a Proc to be used to format
|
|
@@ -135,7 +136,7 @@ module SemanticLogger
|
|
|
135
136
|
# Example
|
|
136
137
|
# require "semantic_logger"
|
|
137
138
|
#
|
|
138
|
-
# #
|
|
139
|
+
# # Log :info and above
|
|
139
140
|
# SemanticLogger.default_level = :info
|
|
140
141
|
#
|
|
141
142
|
# # Log to a file
|
|
@@ -211,21 +212,23 @@ module SemanticLogger
|
|
|
211
212
|
return refused unless file
|
|
212
213
|
|
|
213
214
|
# Formatted once, outside the retry below: reopening the file cannot fix the content.
|
|
214
|
-
|
|
215
|
-
count
|
|
215
|
+
line = format_log(log) { |text| TextOutput.line(text) }
|
|
216
|
+
count = 0
|
|
216
217
|
begin
|
|
217
|
-
file.
|
|
218
|
+
# The number of bytes written, in the file's `encoding`, as IO#write returns it.
|
|
219
|
+
written = TextOutput.write(file, line)
|
|
218
220
|
@log_count += 1
|
|
219
|
-
@log_size +=
|
|
221
|
+
@log_size += written
|
|
220
222
|
rescue StandardError => e
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
223
|
+
# Nor can it fix text that the file refuses even converted (see TextOutput and
|
|
224
|
+
# #message_error?).
|
|
225
|
+
raise(e) if count >= retry_count || message_error?(e)
|
|
226
|
+
|
|
227
|
+
count += 1
|
|
228
|
+
file = reopen
|
|
229
|
+
return refused unless file
|
|
230
|
+
|
|
231
|
+
retry
|
|
229
232
|
end
|
|
230
233
|
true
|
|
231
234
|
end
|
|
@@ -236,6 +239,18 @@ module SemanticLogger
|
|
|
236
239
|
@file&.flush
|
|
237
240
|
end
|
|
238
241
|
|
|
242
|
+
# Closes the log file, such as when the appender is removed, and forgets it, so that a write after
|
|
243
|
+
# it opens the file again, whatever the retry_count. An error closing it, such as EIO when the
|
|
244
|
+
# file's last writes did not reach a network file system, is reported rather than raised.
|
|
245
|
+
def close
|
|
246
|
+
@file&.close
|
|
247
|
+
rescue StandardError => e
|
|
248
|
+
logger.warn("Could not close the log file #{current_file_name}", e)
|
|
249
|
+
ensure
|
|
250
|
+
@file = nil
|
|
251
|
+
@refused_retry_at = nil
|
|
252
|
+
end
|
|
253
|
+
|
|
239
254
|
# See Subscriber#inspect.
|
|
240
255
|
def inspect_details
|
|
241
256
|
"file_name=#{file_name.inspect}"
|