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
@@ -8,60 +8,63 @@ end
8
8
 
9
9
  # Open Telemetry Appender
10
10
  #
11
- # Writes log messages, and metrics to Open Telemetry.
11
+ # Writes log entries to Open Telemetry, as log records through its Logs API.
12
12
  #
13
13
  module SemanticLogger
14
14
  module Appender
15
15
  class OpenTelemetry < SemanticLogger::Subscriber
16
- attr_reader :name, :version, :provider, :logger
16
+ attr_reader :name, :version, :provider
17
17
 
18
- CAPTURE_CONTEXT = ->(log) { log.set_context(:open_telemetry, ::OpenTelemetry::Context.current) }
18
+ CAPTURE_CONTEXT = ->(log) { log.capture(:open_telemetry, ::OpenTelemetry::Context.current) }
19
19
 
20
20
  # Create a Open Telemetry Logger appender instance.
21
21
  #
22
- # Metric only log events are sent to the Open Telemetry Metrics API instead of the Logs API.
23
- # I.e. A metric without a message or an exception.
24
- # To disable this default behavior set `metrics: false`
22
+ # Parameters
23
+ # name: [String]
24
+ # Name of the Open Telemetry logger, which is the instrumentation scope of every log record
25
+ # it emits.
26
+ # Default: "SemanticLogger"
27
+ #
28
+ # version: [String]
29
+ # Version of that instrumentation scope.
30
+ # Default: SemanticLogger::VERSION
31
+ #
32
+ # The formatter maps each log entry to an Open Telemetry log record, returning the keyword
33
+ # arguments for `Logger#on_emit` other than `context:`.
34
+ # Default: SemanticLogger::Formatters::OpenTelemetry
35
+ #
36
+ # A metric-only entry, a metric without a message or an exception, is left out, since it is
37
+ # meant for the metric subscribers. To send them as log records with no body, their metric in
38
+ # the attributes, set `metrics: true`.
25
39
  #
26
40
  # Example
27
41
  # SemanticLogger.add_appender(appender: :open_telemetry)
28
42
  def initialize(name: "SemanticLogger",
29
43
  version: SemanticLogger::VERSION,
30
- formatter: SemanticLogger::Formatters::OpenTelemetry.new,
31
- metrics: true,
44
+ formatter: nil,
32
45
  **args,
33
46
  &)
34
47
  # Base#initialize (via Subscriber) overwrites @name with the class name,
35
48
  # so call super first and then assign our own attributes.
36
- super(formatter: formatter, metrics: metrics, **args, &)
49
+ super(formatter: formatter, **args, &)
37
50
 
38
51
  @name = name
39
52
  @version = version
40
53
  @provider = ::OpenTelemetry.logger_provider
41
- @logger = @provider.logger(name: @name, version: @version)
54
+ # Not @logger, which holds the internal logger that this appender reports its own problems
55
+ # to, as every appender does (see Subscriber#logger).
56
+ @open_telemetry_logger = @provider.logger(name: @name, version: @version)
42
57
 
43
58
  # Capture the current Open Telemetry context when a log entry is captured.
44
59
  # Prevents duplicate subscribers as long as it is from a constant.
45
60
  SemanticLogger.on_log(CAPTURE_CONTEXT)
46
61
  end
47
62
 
63
+ # Emits the log record the formatter returns, in the Open Telemetry context captured when the
64
+ # entry was logged, so that the record is correlated with the trace and span active then.
48
65
  def log(log)
49
- # return log_metric(log) if metrics && log.metric_only?
50
-
51
- body = format_log(log)
52
- level = body.delete(:level)
53
- level_index = body.delete(:level_index)
54
- time = body.delete(:time)
55
- payload = body.delete(:payload)
56
-
57
- @logger.on_emit(
58
- severity_text: level,
59
- severity_number: level_index,
60
- timestamp: time,
61
- body: body.transform_keys!(&:to_s),
62
- attributes: payload,
63
- context: (log.context && log.context[:open_telemetry]) || ::OpenTelemetry::Context.current
64
- )
66
+ context = log.captured(:open_telemetry) || ::OpenTelemetry::Context.current
67
+ @open_telemetry_logger.on_emit(**format_log(log), context: context)
65
68
  true
66
69
  end
67
70
 
@@ -72,7 +75,7 @@ module SemanticLogger
72
75
  @provider.force_flush if @provider.respond_to?(:force_flush)
73
76
  rescue StandardError => e
74
77
  # Swallow to avoid noisy shutdown exceptions.
75
- SemanticLogger::Processor.logger.warn("Flush failed: #{e.class}: #{e.message}")
78
+ logger.warn("Flush failed", e)
76
79
  end
77
80
 
78
81
  # Close the appender and release resources.
@@ -81,18 +84,17 @@ module SemanticLogger
81
84
 
82
85
  @provider.shutdown if @provider.respond_to?(:shutdown)
83
86
  rescue StandardError => e
84
- SemanticLogger::Processor.logger.warn("Shutdown failed: #{e.class}: #{e.message}")
87
+ logger.warn("Shutdown failed", e)
85
88
  ensure
86
89
  @provider = nil
87
90
  end
88
91
 
89
- # For logging metrics only log events.
90
- # def log_metric(log)
91
- # puts "**** TODO: Metric Only Event ****"
92
- # ap format_log(log)
93
- # ap log.payload
94
- # true
95
- # end
92
+ private
93
+
94
+ # Use the Open Telemetry formatter by default: #log emits the log record it returns.
95
+ def default_formatter
96
+ SemanticLogger::Formatters::OpenTelemetry.new
97
+ end
96
98
  end
97
99
  end
98
100
  end
@@ -11,7 +11,7 @@ end
11
11
  # SemanticLogger.add_appender(
12
12
  # appender: :rabbitmq,
13
13
  #
14
- # # Name of the queue in RabbitMQ where to publish the logs. This queue will be bound to "amqp.direct" exchange.
14
+ # # Name of the queue in RabbitMQ where to publish the logs, through the default exchange.
15
15
  # queue_name: 'semantic_logger',
16
16
  #
17
17
  # # This host will be used for RabbitMQ connection.
@@ -20,14 +20,26 @@ end
20
20
  #
21
21
  # # RabbitMQ credentials
22
22
  # username: 'my-username',
23
- # password: 'my-secrect-pass',
23
+ # password: 'my-secret-pass',
24
24
  #
25
25
  # # All other options accepted by Bunny.new call
26
26
  # vhost: 'production',
27
+ #
28
+ # # Leave out metric-only entries, as v6 does by default:
29
+ # metrics: false
27
30
  # )
28
31
  module SemanticLogger
29
32
  module Appender
30
33
  class Rabbitmq < SemanticLogger::Subscriber
34
+ # Seconds to wait for the channel.close that Bunny passes to Channel#on_error, once publishing found the
35
+ # channel closed without a reason: Bunny marks the channel closed before it calls on_error, on a thread
36
+ # of its own.
37
+ CLOSE_REASON_TIMEOUT = 0.1
38
+
39
+ # How Bunny::ChannelAlreadyClosed names the channel error that RabbitMQ closed the channel with. Bunny
40
+ # names it for every channel.close but those it passes to Channel#on_error instead.
41
+ CLOSE_REASON_GIVEN = "closed due to a server-reported channel error".freeze
42
+
31
43
  # Create RabbitMQ appender using Bunny gem
32
44
  #
33
45
  # Parameters:
@@ -39,12 +51,13 @@ module SemanticLogger
39
51
  #
40
52
  # level: [:trace | :debug | :info | :warn | :error | :fatal]
41
53
  # Override the log level for this appender.
42
- # Default: SemanticLogger.default_level
54
+ # Default: none (:trace), so it writes every entry that a logger emits; each logger
55
+ # filters by its own level.
43
56
  #
44
57
  # formatter: [Object|Proc|Symbol|Hash]
45
58
  # An instance of a class that implements #call, or a Proc to be used to format
46
59
  # the output from this appender
47
- # Default: :json (See: #call)
60
+ # Default: :json
48
61
  #
49
62
  # filter: [Regexp|Proc]
50
63
  # RegExp: Only include log messages where the class name matches the supplied.
@@ -62,52 +75,90 @@ module SemanticLogger
62
75
  #
63
76
  # metrics: [Boolean]
64
77
  # Also send metrics only events to rabbitmq.
65
- # Default: true
78
+ # Default: true, with a deprecation warning when it is not supplied, since v6 changes it to false.
66
79
  #
67
80
  # RabbitMQ Parameters:
68
81
  #
69
82
  # rabbitmq_host: [String]
70
83
  # Host for AMQP connection. in Bunny this is called :host but here it has
71
84
  # been remapped to avoid conflicting with SemanticLogger's :host param.
72
- # Default: localhost
85
+ # Default: Bunny's default, 127.0.0.1
73
86
  #
74
87
  # username: [String]
75
88
  # Username for AMQP connection
76
- # Default: nil
89
+ # Default: Bunny's default, guest
77
90
  #
78
91
  # password: [String]
79
92
  # Password for AMQP connection
80
- # Default: nil
93
+ # Default: Bunny's default, guest
81
94
  #
82
95
  # more parameters supported by Bunny: http://rubybunny.info/articles/connecting.html
83
96
  def initialize(queue_name: "semantic_logger", rabbitmq_host: nil,
84
97
  level: nil, formatter: nil, filter: nil, application: nil, environment: nil,
85
- host: nil, metrics: true, **args, &)
98
+ host: nil, metrics: METRICS_NOT_SUPPLIED, **args, &)
86
99
  @queue_name = queue_name
87
100
  @rabbitmq_args = args.dup
88
101
  @rabbitmq_args[:host] = rabbitmq_host
89
102
  @rabbitmq_args[:logger] = logger
90
103
 
91
104
  super(level: level, formatter: formatter, filter: filter, application: application,
92
- environment: environment, host: host, metrics: metrics, &)
105
+ environment: environment, host: host, metrics: deprecated_metrics_default(metrics, :rabbitmq), &)
93
106
  reopen
94
107
  end
95
108
 
109
+ # Connects to RabbitMQ again, with a new channel, and then closes the connection it replaces, with
110
+ # its channel, such as after a log rotation. The next entry is published on the new channel. When
111
+ # connecting fails, it raises, and the appender keeps the connection and channel it has.
112
+ #
113
+ # After a fork, the child first forgets the connection and channel it inherited, without closing
114
+ # them: they belong to the parent. Closing them would send RabbitMQ a channel.close and a
115
+ # connection.close on the parent's connection, which ends it for the parent too, and publishing on
116
+ # the parent's channel would put the child's frames on it, between the parent's. Ruby closes the
117
+ # child's copy of the socket when it collects it, which leaves the parent's open. When connecting
118
+ # fails in the child, the appender has no channel, and connects before it publishes the next entry
119
+ # (see #queue).
96
120
  def reopen
97
- @connection = Bunny.new(@rabbitmq_args)
98
- @connection.start
99
- @channel = @connection.create_channel
121
+ forget_inherited
122
+ replaced = @connection
123
+ connect
124
+ close_unused(replaced, "that a reopen replaced")
100
125
  end
101
126
 
127
+ # Closes the connection, which closes its channel, and forgets them, and the queue on that channel,
128
+ # even when closing raises, so that the next entry connects again (see #queue). Only the connection
129
+ # is closed: Bunny's Session#close closes each channel that is still open, while Channel#close
130
+ # raises Bunny::ChannelAlreadyClosed for one that RabbitMQ closed, such as after it restarted.
131
+ #
132
+ # In a forked child that has not reopened, such as one that removes the appender before its reopen
133
+ # has run, it forgets the connection and channel it inherited instead, without closing them, since
134
+ # they belong to the parent (see #reopen).
102
135
  def close
103
- @channel&.close
104
- @channel = nil
136
+ forget_inherited
105
137
  @connection&.close
138
+ ensure
139
+ @queue = nil
140
+ @channel = nil
106
141
  @connection = nil
107
142
  end
108
143
 
144
+ # Publishes the formatted entry. Bunny raises Bunny::ChannelAlreadyClosed or Bunny::ConnectionClosedError
145
+ # before it sends anything, so the entry can be published once more, without publishing it twice, when
146
+ # #restore_publishing can restore what it needs: a new channel, when RabbitMQ has closed the appender's
147
+ # channel while the connection is still open, or a new connection, when Bunny will not recover the one it
148
+ # has. Otherwise, such as while Bunny recovers the connection from a network failure, it raises, and the
149
+ # entry is written again after a back-off.
109
150
  def log(log)
110
- queue.publish(format_log(log))
151
+ message = format_log(log)
152
+ begin
153
+ had_channel = @channel
154
+ queue.publish(message)
155
+ rescue Bunny::ChannelAlreadyClosed, Bunny::ConnectionClosedError => e
156
+ # Raised while connecting, when the appender had no channel: raised as it is, without connecting
157
+ # again at once, so that the next entry, after any back-off, connects again.
158
+ raise unless had_channel && restore_publishing(e)
159
+
160
+ queue.publish(message)
161
+ end
111
162
  end
112
163
 
113
164
  def flush
@@ -119,14 +170,187 @@ module SemanticLogger
119
170
  SemanticLogger::Formatters::Json.new
120
171
  end
121
172
 
173
+ # Returns [Bunny::Queue] the queue to publish to, on the appender's channel. Connects first when the
174
+ # appender has no channel: after #close, when connecting failed as it was reopened after a fork, or once
175
+ # it forgot a connection that Bunny will not recover (see #restore_publishing).
122
176
  def queue
123
- @queue ||= @channel.queue(@queue_name)
177
+ @queue ||= (@channel || connect).queue(@queue_name)
124
178
  end
125
179
 
126
180
  # Only the queue name: the connection options hold the password. See Subscriber#inspect.
127
181
  def inspect_details
128
182
  "queue_name=#{@queue_name.inspect}"
129
183
  end
184
+
185
+ private
186
+
187
+ # Returns [Bunny::Channel] a new channel, on a new connection to RabbitMQ, after making them the
188
+ # appender's, in place of the connection, channel, and queue it had. Records the process that built
189
+ # them, which owns their connection (see #reopen). When connecting raises, the appender keeps what
190
+ # it had.
191
+ def connect
192
+ connection = Bunny.new(@rabbitmq_args)
193
+ connection.start
194
+ channel, closes = create_channel(connection)
195
+ @connection = connection
196
+ @channel = channel
197
+ @channel_closes = closes
198
+ @queue = nil
199
+ @pid = ::Process.pid
200
+ channel
201
+ end
202
+
203
+ # Returns [Array(Bunny::Channel, Thread::Queue)] a new channel on the given connection, which has
204
+ # started, and the queue that receives the channel.close with which RabbitMQ closes that channel, when
205
+ # Bunny passes it to Channel#on_error, such as for a message larger than its max_message_size. Bunny calls
206
+ # on_error on a thread of its own, after it has marked the channel closed, so the close can arrive after
207
+ # the channel was replaced: each channel has its own queue, so that it is never reported for another.
208
+ #
209
+ # When creating the channel raises, such as Bunny::ClientTimeout from a broker too busy to answer, closes
210
+ # the connection before raising: its reader and heartbeat threads would otherwise keep it open, and
211
+ # recovering, unused.
212
+ def create_channel(connection)
213
+ channel = connection.create_channel
214
+ closes = Thread::Queue.new
215
+ channel.on_error { |_channel, close| closes << close }
216
+ [channel, closes]
217
+ rescue StandardError
218
+ close_unused(connection, "whose channel could not be created")
219
+ raise
220
+ end
221
+
222
+ # Closes a connection that the appender does not publish on, which closes its channel. Reports an
223
+ # error to the internal logger, with the given description of the connection, rather than raising it:
224
+ # after a reopen, the appender already publishes on the new connection, and when creating a channel
225
+ # failed, that is the error to raise.
226
+ def close_unused(connection, description)
227
+ connection&.close
228
+ rescue StandardError => e
229
+ logger.warn("Could not close the RabbitMQ connection #{description}", e)
230
+ end
231
+
232
+ # Returns [true|false] whether the entry that raised the given Bunny::ChannelAlreadyClosed or
233
+ # Bunny::ConnectionClosedError can be published again, on a new channel, or on a new connection.
234
+ #
235
+ # When RabbitMQ has closed the appender's channel while the connection is still open, such as for an
236
+ # entry larger than its max_message_size, which RabbitMQ refuses with PRECONDITION_FAILED by closing the
237
+ # channel, opens a new channel on that connection, and reports the close to the internal logger.
238
+ # RabbitMQ closes the channel after Bunny has published the entry that it refuses, without answering the
239
+ # publish, so that entry was not raised, and cannot be told apart from the others: it is lost (see
240
+ # #report_closed_channel). The entry being published is not at fault, and is published on the new
241
+ # channel.
242
+ #
243
+ # While the connection is not open, leaves it to Bunny, and returns false, when Bunny can still recover
244
+ # it: Bunny closes every channel while it recovers the connection from a network failure, and opens them
245
+ # again once it has reconnected. Otherwise forgets it, so that the entry is published on a new
246
+ # connection (see #forget_abandoned_connection).
247
+ #
248
+ # Bunny marks the connection open again before it reopens its channels, and a closed channel looks the
249
+ # same through Bunny's public API whether RabbitMQ closed it or the network failed, so an entry published
250
+ # in that short gap replaces a channel that Bunny is about to reopen: the appender then reports a close,
251
+ # and the channel it replaced stays open, unused, until the connection is closed. That is left as it is,
252
+ # rather than reaching into Bunny's private channel registry.
253
+ #
254
+ # When opening the channel raises, the connection was closed (see #create_channel), and is forgotten,
255
+ # so that the next entry connects again (see #queue).
256
+ #
257
+ # In a forked child, it forgets the connection and channel it inherited instead, without opening a channel
258
+ # on the parent's connection, and the caller connects again (see #reopen).
259
+ def restore_publishing(error)
260
+ forget_inherited
261
+ return true unless @channel
262
+ return forget_abandoned_connection unless @connection.open?
263
+ # The connection was recovered after publishing raised: the entry is written again after a back-off.
264
+ return false unless error.is_a?(Bunny::ChannelAlreadyClosed)
265
+
266
+ closes = @channel_closes
267
+ @queue = nil
268
+ @channel = nil
269
+ report_closed_channel(channel_close(closes, error), error)
270
+ open_channel
271
+ true
272
+ end
273
+
274
+ # Returns [AMQ::Protocol::Channel::Close|nil] the channel.close that Bunny passed to Channel#on_error for
275
+ # the closed channel whose queue is given, when it is there. Waits up to CLOSE_REASON_TIMEOUT for it only
276
+ # when the given Bunny::ChannelAlreadyClosed does not name a reason: for the closes that Bunny passes to
277
+ # on_error (message_too_large, unknown_delivery_tag, delivery_ack_timeout). For every other channel.close,
278
+ # Bunny names the reason in the error, and calls no on_error. So that wait costs up to 0.1 seconds, on
279
+ # the thread that logs, once per such close, and when the channel was closed without a reason, such as
280
+ # by Channel#close. Bunny marks the channel closed, answers RabbitMQ, and only then records the reason
281
+ # it names in the error, so an entry published during that one write gets an error without the reason:
282
+ # the appender then waits the 0.1 seconds, and reports the close without the reason.
283
+ def channel_close(closes, error)
284
+ return closes.pop(timeout: 0) if error.message.include?(CLOSE_REASON_GIVEN)
285
+
286
+ closes.pop(timeout: CLOSE_REASON_TIMEOUT)
287
+ end
288
+
289
+ # Reports to the internal logger that RabbitMQ closed the channel, with the channel.close that Bunny
290
+ # passed on (see #create_channel), when it arrived, and otherwise the Bunny::ChannelAlreadyClosed that
291
+ # publishing raised. Only a close for a message larger than RabbitMQ's max_message_size says that an
292
+ # entry was refused.
293
+ def report_closed_channel(close, error)
294
+ if close.respond_to?(:message_too_large?) && close.message_too_large?
295
+ logger.warn("RabbitMQ refused an entry and closed the channel, so that entry was not written, and " \
296
+ "the next entries are published on a new channel. Reason: #{close.reply_text}")
297
+ else
298
+ logger.warn("RabbitMQ closed the channel, so the entries are published on a new one. " \
299
+ "Reason: #{close ? close.reply_text : error.message}")
300
+ end
301
+ end
302
+
303
+ # Returns [true|false] whether it closed and forgot the appender's connection, which is not open, with
304
+ # its channel and queue, so that the entry is published on a new connection (see #queue). It does so
305
+ # once Bunny will not recover the connection (see #abandoned?), and leaves it to Bunny otherwise.
306
+ def forget_abandoned_connection
307
+ return false unless abandoned?(@connection)
308
+
309
+ close_unused(@connection, "that Bunny will not recover")
310
+ @connection = nil
311
+ @channel = nil
312
+ @queue = nil
313
+ true
314
+ end
315
+
316
+ # Returns [true|false] whether Bunny will not recover the given connection, which is not open, as told
317
+ # through Bunny's public API:
318
+ # - It is closed (Bunny::Session#closed?), such as once Bunny ran out of recovery attempts.
319
+ # - Its status is still :open, its transport being closed (Session#open? is false), and automatic
320
+ # recovery is off (Session#automatically_recover?): after a network failure, Bunny leaves it so.
321
+ # A connection.close from RabbitMQ is recovered all the same, unless recover_from_connection_close is
322
+ # false; Bunny then leaves it so too. When it does recover one, it passes through that state for an
323
+ # instant first: an entry published in that instant closes the connection, which then stays unused.
324
+ #
325
+ # While Bunny recovers a connection, its status is :disconnected. With automatic recovery on, Bunny only
326
+ # passes through status :open with a closed transport, for an instant before it starts recovering, so
327
+ # that state is not taken as abandoned. The connections that Bunny does not recover in that case, with
328
+ # recover_from_connection_close: false, are left as they are, as are those that keep status
329
+ # :disconnected after an exception that Bunny is configured not to recover from (recoverable_exceptions);
330
+ # the appender connects again once it is reopened (SemanticLogger.reopen). Bunny's flag for
331
+ # recover_from_connection_close is private.
332
+ def abandoned?(connection)
333
+ connection.closed? || (connection.status == :open && !connection.automatically_recover?)
334
+ end
335
+
336
+ # Opens a new channel on the appender's connection, which it publishes on next. When that raises, the
337
+ # connection was closed (see #create_channel), and is forgotten.
338
+ def open_channel
339
+ @channel, @channel_closes = create_channel(@connection)
340
+ rescue StandardError
341
+ @connection = nil
342
+ raise
343
+ end
344
+
345
+ # In a child process, forgets the connection and channel built in the parent before a fork, and the
346
+ # queue on that channel. See #reopen.
347
+ def forget_inherited
348
+ return if @pid == ::Process.pid
349
+
350
+ @connection = nil
351
+ @channel = nil
352
+ @queue = nil
353
+ end
130
354
  end
131
355
  end
132
356
  end
@@ -39,10 +39,9 @@ module SemanticLogger
39
39
  # Name of this application to appear in log messages.
40
40
  # Default: SemanticLogger.application
41
41
  def initialize(level: :error, **args, &block)
42
- Kernel.warn(
42
+ Deprecation.warn(
43
43
  "SemanticLogger::Appender::Sentry (appender: :sentry) is deprecated and will be removed in v6. " \
44
- "It depends on the end-of-life sentry-raven gem. Use appender: :sentry_ruby instead.",
45
- category: :deprecated
44
+ "It depends on the end-of-life sentry-raven gem. Use appender: :sentry_ruby instead."
46
45
  )
47
46
  # Replace the Sentry Raven logger so that we can identify its log messages and not forward them to Sentry
48
47
  Raven.configure { |config| config.logger = SemanticLogger[Raven] }
@@ -21,6 +21,9 @@ module SemanticLogger
21
21
  # The types of value accepted in a fingerprint, which Sentry turns into Strings.
22
22
  FINGERPRINT_PART_TYPES = [String, Symbol, Numeric].freeze
23
23
 
24
+ # The key of the Sentry scope of the thread that logged the entry, as captured with the entry.
25
+ SCOPE_CAPTURE_KEY = :sentry_scope
26
+
24
27
  # Create Appender
25
28
  #
26
29
  # Parameters
@@ -56,6 +59,14 @@ module SemanticLogger
56
59
  end
57
60
  end
58
61
  super
62
+ # Sentry keeps the user, tags, contexts, breadcrumbs, and trace of a request in the Sentry
63
+ # scope of the thread or fiber handling it, but #log runs on the appender thread.
64
+ SemanticLogger::Logger.subscribe(method(:capture_scope))
65
+ end
66
+
67
+ # Stops capturing the Sentry scope of each log entry.
68
+ def close
69
+ SemanticLogger::Logger.unsubscribe(method(:capture_scope))
59
70
  end
60
71
 
61
72
  # Send an error notification to sentry
@@ -63,13 +74,17 @@ module SemanticLogger
63
74
  # Ignore logs coming from Sentry itself
64
75
  return false if log.name == "Sentry"
65
76
 
66
- context = format_log(log)
67
- # Copies, since the payload and named tags are the log entry's own, which every other
68
- # appender writes after this one, and the payload can be the application's own Hash. The
69
- # keys taken out below must only be left out of what is sent to Sentry.
70
- payload = payload_copy(context.delete(:payload))
71
- named_tags = (context[:named_tags] || {}).dup
72
- context[:named_tags] = named_tags
77
+ # Sentry serializes the event with JSON.generate itself, which raises for a binary String
78
+ # that holds bytes outside ASCII (json 3.1), or warns about it (json 2.8 to 3.0.x), and for
79
+ # invalid UTF-8, and then loses the event. So the data is sent as a copy with its text
80
+ # converted to valid UTF-8, as the JSON formatters write it, and a Hash or Array nested too
81
+ # deeply, or that holds itself, cut off there as they cut it off (see Utils.encode_utf8).
82
+ # Any other object is sent as it is, for Sentry to write as it writes it.
83
+ context = format_log(log) { |data| Utils.encode_utf8(data) }
84
+ # The payload and named tags are this appender's own copies (above), so the keys taken out
85
+ # below are left out only of what is sent to Sentry.
86
+ payload = payload_extras(context.delete(:payload), log.payload)
87
+ named_tags = (context[:named_tags] = like_original(context[:named_tags] || {}, log.named_tags))
73
88
  transaction_name = named_tags.delete(:transaction_name)
74
89
  fingerprint = extract_fingerprint!(named_tags) || extract_fingerprint!(payload, from_payload: true)
75
90
 
@@ -77,7 +92,8 @@ module SemanticLogger
77
92
  tags = extract_tags!(context)
78
93
 
79
94
  ::Sentry.with_scope do |scope|
80
- scope.set_user(user) if user
95
+ apply_captured_scope(scope, log)
96
+ scope.set_user(merged_user(scope.user, user)) if user
81
97
  scope.set_level(context.delete(:level)) if context[:level]
82
98
  scope.set_fingerprint(fingerprint) if fingerprint
83
99
  scope.set_transaction_name(transaction_name) if transaction_name
@@ -99,6 +115,44 @@ module SemanticLogger
99
115
 
100
116
  private
101
117
 
118
+ # As an on_log subscriber, on the thread that logs the entry, keeps a copy of its Sentry scope
119
+ # with the entry when it meets this appender's level. The filter is left to #log, so that it
120
+ # runs once, on the appender thread.
121
+ #
122
+ # The copy leaves out the Rack env: Sentry reads and rewinds the request body in it as it builds
123
+ # the request of an event, which must not happen on the appender thread while the request is
124
+ # still using it, or after it has closed the body.
125
+ def capture_scope(log)
126
+ return if log.captured(SCOPE_CAPTURE_KEY) || log.name == "Sentry"
127
+ return unless ::Sentry.initialized? && meets_log_level?(log)
128
+
129
+ scope = ::Sentry.get_current_scope&.dup
130
+ return unless scope
131
+
132
+ scope.set_rack_env(nil)
133
+ log.capture(SCOPE_CAPTURE_KEY, scope)
134
+ end
135
+
136
+ # Starts the scope of the event from the Sentry scope captured when the entry was logged, so
137
+ # that the event has the user, tags, contexts, breadcrumbs, trace, and event processors of the
138
+ # thread that logged it. Copies it again, since the scope adds tags and extras to its Hashes,
139
+ # which would otherwise be the ones held by the log entry.
140
+ def apply_captured_scope(scope, log)
141
+ captured = log.captured(SCOPE_CAPTURE_KEY)
142
+ return unless captured.is_a?(::Sentry::Scope)
143
+
144
+ captured = captured.dup
145
+ scope.update_from_scope(captured)
146
+ captured.event_processors.each { |processor| scope.add_event_processor(&processor) }
147
+ end
148
+
149
+ # Returns [Hash] the Sentry user of the thread with the fields of the user taken from the
150
+ # named tags, whose keys are Symbols, in place of the same fields, whether keyed by a String or
151
+ # a Symbol.
152
+ def merged_user(thread_user, user)
153
+ thread_user.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }.merge(user)
154
+ end
155
+
102
156
  # Use Raw Formatter by default
103
157
  def default_formatter
104
158
  SemanticLogger::Formatters::Raw.new
@@ -173,26 +227,39 @@ module SemanticLogger
173
227
  FINGERPRINT_PART_TYPES.any? { |type| part.is_a?(type) }
174
228
  end
175
229
 
176
- # Returns [Hash] a copy of the payload that keys can be taken out of. A payload that is not a
177
- # Hash is sent to Sentry as the extra named payload.
178
- def payload_copy(payload)
230
+ # Returns [Hash] the payload, from this appender's own copy, as a Hash that keys can be taken out
231
+ # of. A payload that is not a Hash is sent to Sentry as the extra named payload.
232
+ def payload_extras(payload, original)
179
233
  case payload
180
234
  when nil then {}
181
- when Hash then payload.dup
235
+ when Hash then like_original(payload, original)
182
236
  else {payload: payload}
183
237
  end
184
238
  end
185
239
 
240
+ # Returns [Hash] this appender's copy of the payload or named tags as a Hash of the class of the
241
+ # log entry's own, such as HashWithIndifferentAccess, so that the keys taken out of it, such as
242
+ # :user_id, are found as in the application's Hash. The class's own #update may convert the
243
+ # nested Hashes too, as HashWithIndifferentAccess does. A plain Hash, or one whose class cannot
244
+ # be rebuilt this way, is returned as it is.
245
+ def like_original(copy, original)
246
+ return copy if original.instance_of?(Hash) || !original.is_a?(Hash)
247
+
248
+ rebuilt = original.class.new.update(copy)
249
+ rebuilt.is_a?(Hash) ? rebuilt : copy
250
+ rescue StandardError
251
+ copy
252
+ end
253
+
186
254
  # Warns once that the Sentry user or fingerprint was taken from the payload.
187
255
  def payload_context_deprecated
188
256
  return if @payload_context_deprecated
189
257
 
190
258
  @payload_context_deprecated = true
191
- Kernel.warn(
259
+ Deprecation.warn(
192
260
  "SemanticLogger::Appender::SentryRuby took the Sentry user or fingerprint from the log payload. " \
193
261
  "This is deprecated and will be removed in v6, since the payload can hold untrusted data: " \
194
- "set them with named tags instead, for example SemanticLogger.tagged(user_id: user.id).",
195
- category: :deprecated
262
+ "set them with named tags instead, for example SemanticLogger.tagged(user_id: user.id)."
196
263
  )
197
264
  end
198
265
 
@@ -81,7 +81,8 @@ module SemanticLogger
81
81
  #
82
82
  # level: [:trace | :debug | :info | :warn | :error | :fatal]
83
83
  # Override the log level for this appender.
84
- # Default: SemanticLogger.default_level
84
+ # Default: none (:trace), so it writes every entry that a logger emits; each logger
85
+ # filters by its own level.
85
86
  #
86
87
  # formatter: [Object|Proc]
87
88
  # An instance of a class that implements #call, or a Proc to be used to format
@@ -94,10 +95,9 @@ module SemanticLogger
94
95
  # Proc: Only include log messages where the supplied Proc returns true
95
96
  # The Proc must return true or false.
96
97
  def initialize(index: "main", source_type: nil, **args, &)
97
- Kernel.warn(
98
+ Deprecation.warn(
98
99
  "SemanticLogger::Appender::Splunk (appender: :splunk) is deprecated and will be removed in v6. " \
99
- "Its splunk-sdk-ruby gem does not verify TLS certificates. Use appender: :splunk_http instead.",
100
- category: :deprecated
100
+ "Its splunk-sdk-ruby gem does not verify TLS certificates. Use appender: :splunk_http instead."
101
101
  )
102
102
  @index = index
103
103
  @source_type = source_type