semantic_logger 5.2.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. checksums.yaml +4 -4
  2. data/docs/api.md +160 -9
  3. data/docs/appenders.md +461 -34
  4. data/docs/config.md +543 -36
  5. data/docs/log.md +38 -7
  6. data/docs/metrics.md +139 -28
  7. data/docs/operations.md +293 -24
  8. data/docs/rails.md +319 -5
  9. data/docs/security.md +135 -107
  10. data/docs/testing.md +23 -0
  11. data/docs/upgrading.md +644 -1
  12. data/lib/semantic_logger/appender/async.rb +29 -11
  13. data/lib/semantic_logger/appender/bugsnag.rb +7 -2
  14. data/lib/semantic_logger/appender/cloudwatch_logs.rb +46 -6
  15. data/lib/semantic_logger/appender/elasticsearch_base.rb +197 -29
  16. data/lib/semantic_logger/appender/elasticsearch_http.rb +22 -5
  17. data/lib/semantic_logger/appender/file.rb +29 -14
  18. data/lib/semantic_logger/appender/graylog.rb +81 -7
  19. data/lib/semantic_logger/appender/honeybadger.rb +7 -1
  20. data/lib/semantic_logger/appender/honeybadger_insights.rb +8 -2
  21. data/lib/semantic_logger/appender/http.rb +244 -41
  22. data/lib/semantic_logger/appender/io.rb +11 -6
  23. data/lib/semantic_logger/appender/kafka.rb +192 -46
  24. data/lib/semantic_logger/appender/loki.rb +42 -6
  25. data/lib/semantic_logger/appender/mongodb.rb +94 -9
  26. data/lib/semantic_logger/appender/new_relic.rb +2 -3
  27. data/lib/semantic_logger/appender/new_relic_logs.rb +30 -8
  28. data/lib/semantic_logger/appender/open_telemetry.rb +37 -35
  29. data/lib/semantic_logger/appender/rabbitmq.rb +241 -17
  30. data/lib/semantic_logger/appender/sentry.rb +2 -3
  31. data/lib/semantic_logger/appender/sentry_ruby.rb +82 -15
  32. data/lib/semantic_logger/appender/splunk.rb +4 -4
  33. data/lib/semantic_logger/appender/splunk_http.rb +92 -1
  34. data/lib/semantic_logger/appender/syslog.rb +89 -10
  35. data/lib/semantic_logger/appender/tcp.rb +68 -98
  36. data/lib/semantic_logger/appender/text_output.rb +65 -0
  37. data/lib/semantic_logger/appender/udp.rb +130 -18
  38. data/lib/semantic_logger/appender/wrapper.rb +10 -7
  39. data/lib/semantic_logger/appender.rb +115 -10
  40. data/lib/semantic_logger/appenders.rb +136 -4
  41. data/lib/semantic_logger/backtrace_cleaning.rb +77 -0
  42. data/lib/semantic_logger/base.rb +53 -71
  43. data/lib/semantic_logger/call_site.rb +235 -0
  44. data/lib/semantic_logger/context.rb +222 -0
  45. data/lib/semantic_logger/core_ext/process.rb +20 -5
  46. data/lib/semantic_logger/core_ext/warning.rb +70 -0
  47. data/lib/semantic_logger/deprecation.rb +139 -0
  48. data/lib/semantic_logger/exception_details.rb +4 -3
  49. data/lib/semantic_logger/formatters/base.rb +139 -19
  50. data/lib/semantic_logger/formatters/color.rb +3 -4
  51. data/lib/semantic_logger/formatters/default.rb +35 -7
  52. data/lib/semantic_logger/formatters/ecs.rb +9 -4
  53. data/lib/semantic_logger/formatters/json.rb +9 -0
  54. data/lib/semantic_logger/formatters/logfmt.rb +9 -7
  55. data/lib/semantic_logger/formatters/loki/labels.rb +282 -0
  56. data/lib/semantic_logger/formatters/loki.rb +412 -24
  57. data/lib/semantic_logger/formatters/new_relic_logs.rb +15 -13
  58. data/lib/semantic_logger/formatters/one_line.rb +44 -10
  59. data/lib/semantic_logger/formatters/open_telemetry.rb +186 -29
  60. data/lib/semantic_logger/formatters/pattern.rb +60 -8
  61. data/lib/semantic_logger/formatters/raw.rb +38 -8
  62. data/lib/semantic_logger/formatters/signalfx.rb +55 -15
  63. data/lib/semantic_logger/formatters/syslog.rb +4 -2
  64. data/lib/semantic_logger/formatters/syslog_cee.rb +10 -4
  65. data/lib/semantic_logger/formatters/syslog_header.rb +49 -0
  66. data/lib/semantic_logger/formatters.rb +1 -0
  67. data/lib/semantic_logger/log.rb +236 -80
  68. data/lib/semantic_logger/loggable.rb +55 -95
  69. data/lib/semantic_logger/logger.rb +31 -5
  70. data/lib/semantic_logger/metric/new_relic.rb +32 -17
  71. data/lib/semantic_logger/metric/signalfx.rb +21 -12
  72. data/lib/semantic_logger/metric/statsd.rb +26 -8
  73. data/lib/semantic_logger/processor.rb +194 -5
  74. data/lib/semantic_logger/queue_processor/backoff.rb +140 -0
  75. data/lib/semantic_logger/queue_processor/batch_failure.rb +69 -0
  76. data/lib/semantic_logger/queue_processor/held_write.rb +62 -0
  77. data/lib/semantic_logger/queue_processor/inbox.rb +97 -0
  78. data/lib/semantic_logger/queue_processor/reopener.rb +56 -0
  79. data/lib/semantic_logger/queue_processor/reporter.rb +113 -0
  80. data/lib/semantic_logger/queue_processor/request.rb +48 -10
  81. data/lib/semantic_logger/queue_processor/throttled_counter.rb +60 -17
  82. data/lib/semantic_logger/queue_processor.rb +426 -176
  83. data/lib/semantic_logger/ractor_copy.rb +120 -0
  84. data/lib/semantic_logger/ractor_processor.rb +82 -0
  85. data/lib/semantic_logger/ractor_receiver.rb +282 -0
  86. data/lib/semantic_logger/ractor_support.rb +28 -0
  87. data/lib/semantic_logger/redactor.rb +310 -0
  88. data/lib/semantic_logger/semantic_logger.rb +313 -79
  89. data/lib/semantic_logger/subscriber.rb +169 -15
  90. data/lib/semantic_logger/sync_processor.rb +226 -26
  91. data/lib/semantic_logger/test/capture_log_events.rb +20 -2
  92. data/lib/semantic_logger/test/minitest.rb +2 -1
  93. data/lib/semantic_logger/test/rspec.rb +1 -1
  94. data/lib/semantic_logger/trap_safe.rb +113 -0
  95. data/lib/semantic_logger/utils.rb +266 -79
  96. data/lib/semantic_logger/version.rb +1 -1
  97. data/lib/semantic_logger.rb +35 -2
  98. metadata +22 -2
@@ -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, :console_output?
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, :thread, :active?, :queue, :max_queue_size,
28
- :capped?, :non_blocking?, :non_blocking=, :batch?,
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
- # When non_blocking is enabled, log the count of dropped messages to the internal logger
77
- # at most once every this number of seconds. Also limits how often messages discarded
78
- # because their content could not be written are reported, after the first.
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 (only possible when non_blocking is enabled).
117
- # failed: [Integer] Cumulative number of log messages discarded because their
118
- # content could not be written (see Subscriber#message_error?).
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
- hash = format_log(log)
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
- task.shutdown
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
- @buffered_logs = Concurrent::Array.new
111
- @client = Aws::CloudWatchLogs::Client.new(client_kwargs)
112
-
113
- @task = Concurrent::TimerTask.new(execution_interval: force_flush_interval_seconds,
114
- interval_type: :fixed_rate) do
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: SemanticLogger.default_level
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
- # Default: :raw_json (See: #call)
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; `host` or `url` keys are also valid.
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
- Kernel.warn(
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: false, &)
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([bulk_index(log), bulk_line(log)])
194
+ bulk_write([bulk_entry(log)])
166
195
  true
167
196
  end
168
197
 
169
198
  def batch(logs)
170
- messages = []
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
- # Serializes the action lines; the documents already are (see #bulk_line).
209
- def bulk_write(messages)
210
- body = messages.map { |message| message.is_a?(String) ? message : message.to_json }
211
- bulk_result =
212
- if @data_stream
213
- @client.bulk(index: index, body: body)
214
- else
215
- @client.bulk(body: body)
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
- return unless bulk_result["errors"]
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
- failed = bulk_result["items"].reject { |x| x["status"] == 201 }
221
- logger.error("#{self.class.name}: Write failed. Messages discarded. : #{failed}")
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" => expanded_index_name}}
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: SemanticLogger.default_level
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
- Kernel.warn(
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: SemanticLogger.default_level
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
- # # Enable trace level logging
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
- message = format_log(log) << "\n"
215
- count = 0
215
+ line = format_log(log) { |text| TextOutput.line(text) }
216
+ count = 0
216
217
  begin
217
- file.write(message)
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 += message.size
221
+ @log_size += written
220
222
  rescue StandardError => e
221
- if count < retry_count
222
- count += 1
223
- file = reopen
224
- return refused unless file
225
-
226
- retry
227
- end
228
- raise(e)
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}"