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
@@ -0,0 +1,120 @@
1
+ module SemanticLogger
2
+ # Internal, experimental: what Ruby can copy from one Ractor to another, and how to replace what it
3
+ # cannot. Ruby 4.0 and later only.
4
+ #
5
+ # Sending a value to another Ractor copies it, unless it is shareable. Ruby cannot copy some
6
+ # objects, such as a Proc, a Thread, a Method, or an Enumerator, or anything that holds one.
7
+ module RactorCopy
8
+ # Returns [Array] the log entry, and the backtraces of its exceptions, to send to another Ractor.
9
+ #
10
+ # Ruby 4.0 leaves an exception copied to another Ractor without its backtrace (Ruby bug #21818), so
11
+ # .unpack sets it again.
12
+ def self.pack(log)
13
+ backtraces = []
14
+ log.each_exception { |exception, i| backtraces[i] = exception.backtrace }
15
+ [log, backtraces]
16
+ end
17
+
18
+ # Returns [Log] the log entry received from another Ractor (see .pack), with the backtraces of its
19
+ # exceptions.
20
+ def self.unpack(log, backtraces)
21
+ log.each_exception do |exception, i|
22
+ backtrace = backtraces[i]
23
+ exception.set_backtrace(backtrace) if backtrace && exception.backtrace != backtrace
24
+ end
25
+ log
26
+ end
27
+
28
+ # Returns the value when it can be copied to another Ractor. Otherwise a Hash or an Array with
29
+ # each element that cannot be copied replaced, and any other value replaced by its #inspect. A
30
+ # Hash or an Array is always rebuilt, so that each value in it is tried once, not with every Hash
31
+ # or Array that holds it.
32
+ def self.copyable(value, depth = 0)
33
+ case value
34
+ when Hash
35
+ return Utils.safe_inspect(value) if depth >= Utils::MAX_JSON_SAFE_DEPTH
36
+
37
+ value.to_h { |key, val| [copyable(key, depth + 1), copyable(val, depth + 1)] }
38
+ when Array
39
+ return Utils.safe_inspect(value) if depth >= Utils::MAX_JSON_SAFE_DEPTH
40
+
41
+ value.map { |element| copyable(element, depth + 1) }
42
+ else
43
+ plain?(value) || copyable?(value) ? value : Utils.safe_inspect(value)
44
+ end
45
+ end
46
+
47
+ # Returns the exception when it can be copied to another Ractor. Otherwise a copy of the same
48
+ # class with the message it was raised with, its backtrace, its cause, which is copied the same
49
+ # way, and its instance variables, made copyable as by .copyable. Or a RuntimeError with the class
50
+ # name in its message, for an exception whose #message needs what could not be copied.
51
+ def self.copyable_exception(exception, depth = 0)
52
+ copyable?(exception) ? exception : plain_exception(exception, depth)
53
+ end
54
+
55
+ # Whether the value can be copied to another Ractor: sends it through a port of this Ractor.
56
+ def self.copyable?(value)
57
+ port = ::Ractor::Port.new
58
+ port << value
59
+ port.receive
60
+ true
61
+ rescue StandardError
62
+ false
63
+ ensure
64
+ port&.close
65
+ end
66
+
67
+ # Whether the value is one that Ruby always copies, so that .copyable need not try it.
68
+ def self.plain?(value)
69
+ case value
70
+ when nil, true, false, Symbol, Integer, Float
71
+ true
72
+ when String
73
+ value.instance_of?(String) && value.instance_variables.empty?
74
+ else
75
+ false
76
+ end
77
+ end
78
+ private_class_method :plain?
79
+
80
+ def self.plain_exception(exception, depth)
81
+ copy = exception.class.allocate
82
+ Exception.instance_method(:initialize).bind_call(copy, Utils.raised_message(exception))
83
+ exception.instance_variables.each do |name|
84
+ copy.instance_variable_set(name, copyable_variable(exception.instance_variable_get(name), depth))
85
+ end
86
+ copy.set_backtrace(exception.backtrace || [])
87
+ copy = with_cause(copy, exception.cause, depth)
88
+ # Raises when the class's #message needs a value that could not be copied.
89
+ copy.message
90
+ copy
91
+ rescue StandardError
92
+ # Joined whatever their encodings, such as a UTF-8 class name and an ISO-8859-1 message.
93
+ message = Utils.join_texts(Utils.exception_name(exception), ": ", Utils.exception_message(exception))
94
+ plain = RuntimeError.new(message)
95
+ plain.set_backtrace(exception.backtrace || [])
96
+ with_cause(plain, exception.cause, depth)
97
+ end
98
+ private_class_method :plain_exception
99
+
100
+ def self.copyable_variable(value, depth)
101
+ return copyable(value, depth + 1) unless value.is_a?(Exception)
102
+
103
+ depth < Log::MAX_EXCEPTIONS_TO_UNWRAP ? copyable_exception(value, depth + 1) : Utils.safe_inspect(value)
104
+ end
105
+ private_class_method :copyable_variable
106
+
107
+ # Returns the copy of an exception with a copy of its cause. Ruby only sets the cause of an
108
+ # exception when raising it, and keeps the backtrace already set.
109
+ def self.with_cause(copy, cause, depth)
110
+ return copy unless cause && depth < Log::MAX_EXCEPTIONS_TO_UNWRAP
111
+
112
+ begin
113
+ raise copy, cause: copyable_exception(cause, depth + 1)
114
+ rescue Exception => e
115
+ e
116
+ end
117
+ end
118
+ private_class_method :with_cause
119
+ end
120
+ end
@@ -0,0 +1,82 @@
1
+ module SemanticLogger
2
+ # Internal, experimental: the processor of a Ractor other than the main one. Ruby 4.0 and later
3
+ # only.
4
+ #
5
+ # The appenders belong to the main Ractor, which only it can use, so this sends each log entry to
6
+ # RactorReceiver in the main Ractor, which writes it to the appenders. It knows the name its Ractor
7
+ # is logged as. Adding or changing appenders, like every other setting, is only possible in the main
8
+ # Ractor.
9
+ class RactorProcessor
10
+ # Returns [RactorProcessor] the processor of the current Ractor.
11
+ def self.current
12
+ ::Ractor.store_if_absent(:semantic_logger_processor) { new }
13
+ end
14
+
15
+ # Returns [String] the name that identifies this Ractor in the thread name of its log entries: its
16
+ # own name, or its number, as in "ractor-2".
17
+ attr_reader :name
18
+
19
+ def initialize
20
+ ractor = ::Ractor.current
21
+ @name = ractor.name || "ractor-#{ractor.inspect[/\A#<Ractor:#(\d+)/, 1]}"
22
+ end
23
+
24
+ # Sends the log entry to the main Ractor. Its thread name is prefixed with this Ractor's name.
25
+ #
26
+ # Sending copies the entry. When something in it cannot be copied, such as a Proc in its payload,
27
+ # those values are replaced (see Log#make_copyable) and it is sent again.
28
+ def log(log)
29
+ log.thread_name = "#{name}/#{log.thread_name}"
30
+ begin
31
+ RactorReceiver.port << [:log, *RactorCopy.pack(log)]
32
+ rescue StandardError
33
+ RactorReceiver.port << [:log, *RactorCopy.pack(log.make_copyable)]
34
+ end
35
+ true
36
+ end
37
+
38
+ # Waits until the main Ractor has written the entries sent before this call, and has flushed the
39
+ # appenders. Returns the result of the main Ractor's flush, as SemanticLogger.flush there would.
40
+ # Returns false without waiting when the main Ractor is not receiving, for example since no
41
+ # appender was added.
42
+ def flush
43
+ return false unless RactorReceiver.running?
44
+
45
+ reply = ::Ractor::Port.new
46
+ RactorReceiver.port << [:flush, reply]
47
+ reply.receive
48
+ ensure
49
+ reply&.close
50
+ end
51
+
52
+ # Returns the internal logger, to report problems logging in this Ractor, such as an on_log
53
+ # subscriber that raised. It writes to this Ractor's $stderr.
54
+ def logger
55
+ @logger ||= Appender::IO.new($stderr, level: :warn).tap { |logger| logger.name = self.class.name }
56
+ end
57
+
58
+ # The operations that only the main Ractor can do, such as adding an appender.
59
+ %i[appenders close reopen start queue queue_size stats lag_check_interval lag_threshold_s
60
+ non_blocking?].each do |method|
61
+ class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
62
+ def #{method}(*) # def appenders(*)
63
+ raise ::Ractor::IsolationError, main_only(:#{method}) # raise ::Ractor::IsolationError, main_only(:appenders)
64
+ end # end
65
+ RUBY
66
+ end
67
+
68
+ def lag_check_interval=(_value)
69
+ raise ::Ractor::IsolationError, main_only(:lag_check_interval=)
70
+ end
71
+
72
+ def non_blocking=(_value)
73
+ raise ::Ractor::IsolationError, main_only(:non_blocking=)
74
+ end
75
+
76
+ private
77
+
78
+ def main_only(method)
79
+ "Semantic Logger can only be configured in the main Ractor, not in #{name} (#{self.class.name}##{method})"
80
+ end
81
+ end
82
+ end
@@ -0,0 +1,282 @@
1
+ module SemanticLogger
2
+ # Internal, experimental: in the main Ractor, receives the log entries logged in other Ractors and
3
+ # hands them to the processor, which writes them to the appenders. Ruby 4.0 and later only.
4
+ #
5
+ # It knows the port that the other Ractors send to (see RactorProcessor), and runs the thread in
6
+ # the main Ractor that receives from it. The thread starts with the processor's thread, when an
7
+ # appender is added. Entries sent before then wait on the port.
8
+ #
9
+ # Ruby 4.0 can crash, or hang, a forked child process that uses a port, when a thread of the parent
10
+ # was waiting on a port at the time of the fork. So no thread of the main Ractor other than the
11
+ # receiving thread ever waits on a port: a thread that waits for the receiving thread, such as one
12
+ # flushing, waits on a Queue instead. And the receiving thread itself waits on a Queue while the
13
+ # process forks (see .pause).
14
+ #
15
+ # A thread that waits for the receiving thread hands it that Queue without locking a Mutex, so that
16
+ # it can do so in a signal trap, such as one that forks or flushes, where Ruby does not allow one to
17
+ # be locked.
18
+ module RactorReceiver
19
+ # Seconds that .pause waits for the receiving thread to finish the entry it is handing over.
20
+ PAUSE_TIMEOUT = 5
21
+
22
+ # Seconds that .pause waits at a time for the receiving thread to get to the pause, before it checks
23
+ # again. Ruby does not end a wait on a Queue that a signal trap interrupted when the Queue is closed
24
+ # while the trap runs, until the wait times out; the receiving thread does that when it gets to a
25
+ # pause that a pause in the trap shares.
26
+ PAUSE_CHECK_SECONDS = 0.1
27
+
28
+ # The thread variable that holds, while a thread pauses the receiving thread, the Queue that the
29
+ # receiving thread closes once it waits for the fork to be over (see .pause).
30
+ PAUSING = :semantic_logger_pausing_ractor_receiver
31
+
32
+ @port = ::Ractor::Port.new
33
+ @pid = ::Process.pid
34
+ @thread = nil
35
+ # Whether the receiving thread was started, so that .reopen starts it again in a child process.
36
+ @started = false
37
+ # The pid of the process whose receiving thread runs, or nil when none runs.
38
+ @running = nil
39
+ # The Queues that threads of the main Ractor wait on for the receiving thread, each with its token,
40
+ # in the order they were registered. Only the receiving thread takes them off.
41
+ @waits = Queue.new
42
+ # The Queues that the receiving thread took off @waits before it got to their token. Only the
43
+ # receiving thread, or .reopen in a child process, uses it.
44
+ @registered = {}
45
+ @mutex = Mutex.new
46
+
47
+ class << self
48
+ # Returns [Ractor::Port] where other Ractors send their log entries and requests. Any Ractor
49
+ # can read it, since a port is shareable.
50
+ attr_reader :port
51
+
52
+ # Returns [true|false] whether a receiving thread runs in this process. Any Ractor can read it.
53
+ def running?
54
+ @running == ::Process.pid
55
+ end
56
+
57
+ # Starts the receiving thread, unless it is running.
58
+ def start
59
+ @mutex.synchronize do
60
+ return false if @thread&.alive?
61
+
62
+ port = @port
63
+ @started = true
64
+ @running = ::Process.pid
65
+ @thread = Thread.new do
66
+ Thread.current.name = "SL Ractors"
67
+ receive(port)
68
+ ensure
69
+ @running = nil
70
+ end
71
+ end
72
+ true
73
+ end
74
+
75
+ # Restarts the receiving thread, if it was started: in the child process after a fork, which the
76
+ # thread does not survive, or after it stopped. The child also gets a new port, since the port it
77
+ # inherited still holds the entries sent to the parent before the fork, which the parent writes.
78
+ #
79
+ # Also called from a signal trap, such as one that reopens the log files after a rotation, where
80
+ # Ruby does not allow a Mutex to be locked. So within the same process, a receiving thread that
81
+ # runs, or none that was started, is left as it is without taking the lock. When there is more
82
+ # to do, and Ruby refuses the lock, a new thread, which can take it, does it instead, once this
83
+ # call has returned.
84
+ def reopen
85
+ return if @pid == ::Process.pid && (!@started || @thread&.alive?)
86
+
87
+ locked = TrapSafe.try_synchronize(@mutex) do
88
+ unless @pid == ::Process.pid
89
+ @port = ::Ractor::Port.new
90
+ @pid = ::Process.pid
91
+ @thread = nil
92
+ @waits = Queue.new
93
+ @registered = {}
94
+ end
95
+ end
96
+ if locked
97
+ start if @started
98
+ else
99
+ Thread.new { reopen }
100
+ nil
101
+ end
102
+ end
103
+
104
+ # Runs the block, which forks the process, while the receiving thread waits on a Queue rather
105
+ # than on the port. Returns the result of the block.
106
+ #
107
+ # The receiving thread first finishes handing over the entries sent before, waiting at most
108
+ # PAUSE_TIMEOUT seconds, after which the fork goes ahead anyway.
109
+ #
110
+ # A pause in a signal trap that interrupted another one on the same thread shares it, rather than
111
+ # asking the receiving thread to pause again: it would only get to the request once the other
112
+ # pause is over, which cannot be before the trap is.
113
+ #
114
+ # Takes no lock, so that it can be called in a signal trap, such as one that forks.
115
+ def pause(&)
116
+ thread = @thread unless RactorSupport.other_ractor?
117
+ return yield unless thread&.alive? && !Thread.current.equal?(thread)
118
+
119
+ paused = Thread.current.thread_variable_get(PAUSING)
120
+ if paused
121
+ wait_until_paused(paused)
122
+ # Unless the other pause ended meanwhile, which another Fiber of this thread can do.
123
+ return yield if Thread.current.thread_variable_get(PAUSING).equal?(paused)
124
+ end
125
+
126
+ hold_receiving_thread(&)
127
+ end
128
+
129
+ # Waits until every entry sent to the port before this call has been handed to the processor,
130
+ # then flushes the processor. Returns the result of the processor's flush.
131
+ #
132
+ # It flushes the processor without waiting on a thread that pauses the receiving thread (see
133
+ # .pause), such as one that flushes while it forks: the receiving thread has handed over the
134
+ # entries sent before the fork began, and waits until it is over. And on a thread inside the
135
+ # processor, such as in a signal trap that interrupted a log call in synchronous mode: the
136
+ # receiving thread would wait for that call to return before it could hand over another entry.
137
+ #
138
+ # Takes no lock, so that it can be called in a signal trap.
139
+ def flush
140
+ thread = @thread
141
+ return Logger.processor.flush unless waits_for_receiving_thread?(thread)
142
+
143
+ done = Queue.new
144
+ @port << [:flush, register(done)]
145
+ loop do
146
+ reply = done.pop(timeout: 1)
147
+ return reply.first if reply
148
+ return Logger.processor.flush unless thread.alive?
149
+ end
150
+ end
151
+
152
+ private
153
+
154
+ # Whether a flush on this thread waits for the receiving thread (see .flush).
155
+ def waits_for_receiving_thread?(thread)
156
+ thread&.alive? && !Thread.current.equal?(thread) && !pausing? && !Logger.processor.current_thread_inside?
157
+ end
158
+
159
+ # Whether this thread pauses the receiving thread (see .pause).
160
+ def pausing?
161
+ !Thread.current.thread_variable_get(PAUSING).nil?
162
+ end
163
+
164
+ # Runs the block while the receiving thread waits on a Queue (see .pause).
165
+ #
166
+ # The thread variable is set only once the request is sent, so that a pause in a signal trap
167
+ # that interrupted this one before then asks for its own; and cleared before the receiving
168
+ # thread resumes, so that one in a trap after then does too. Both wait for the receiving thread
169
+ # to get to their request, at most PAUSE_TIMEOUT seconds, rather than fork while it waits on the
170
+ # port.
171
+ def hold_receiving_thread
172
+ paused = Queue.new
173
+ resume = Queue.new
174
+ begin
175
+ @port << [:pause, register([paused, resume])]
176
+ Thread.current.thread_variable_set(PAUSING, paused)
177
+ wait_until_paused(paused)
178
+ yield
179
+ ensure
180
+ # Only if it is this pause's, which a pause in another Fiber of this thread may have replaced.
181
+ Thread.current.thread_variable_set(PAUSING, nil) if Thread.current.thread_variable_get(PAUSING).equal?(paused)
182
+ resume.push(true)
183
+ end
184
+ end
185
+
186
+ # Waits until the receiving thread closes the Queue, once it waits for the fork to be over, at
187
+ # most PAUSE_TIMEOUT seconds, checking every PAUSE_CHECK_SECONDS.
188
+ def wait_until_paused(paused)
189
+ deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + PAUSE_TIMEOUT
190
+ until paused.closed?
191
+ remaining = deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
192
+ break unless remaining.positive?
193
+
194
+ paused.pop(timeout: [remaining, PAUSE_CHECK_SECONDS].min)
195
+ end
196
+ end
197
+
198
+ # Returns [Integer] the token under which the receiving thread finds the supplied Queue(s). Takes
199
+ # no lock: the receiving thread takes them off @waits when it gets to the token.
200
+ def register(waiting)
201
+ token = waiting.object_id
202
+ @waits.push([token, waiting])
203
+ token
204
+ end
205
+
206
+ # Returns the Queue(s) registered under the token, or nil. Called only by the receiving thread.
207
+ # Those registered ahead of the token, whose token it has not got to yet, wait in @registered.
208
+ def registered(token)
209
+ waiting = @registered.delete(token)
210
+ return waiting if waiting
211
+
212
+ while (entry = @waits.pop(timeout: 0))
213
+ return entry.last if entry.first == token
214
+
215
+ @registered.store(*entry)
216
+ end
217
+ end
218
+
219
+ # Receives from the port until it is closed.
220
+ def receive(port)
221
+ loop do
222
+ kind, *args = port.receive
223
+ case kind
224
+ when :log
225
+ Logger.processor.log(RactorCopy.unpack(*args))
226
+ when :flush
227
+ flush_and_reply(args.first)
228
+ when :pause
229
+ wait_for_fork(args.first)
230
+ end
231
+ rescue ::Ractor::ClosedError
232
+ break
233
+ rescue StandardError => e
234
+ report("Ractor: Failed to log an entry from another Ractor", e)
235
+ end
236
+ end
237
+
238
+ # Flushes the processor, then replies with the result of its flush, or with false when it failed
239
+ # or the thread was stopped meanwhile, so that whoever asked never waits forever.
240
+ def flush_and_reply(requester)
241
+ result = false
242
+ begin
243
+ result = Logger.processor.flush
244
+ rescue StandardError => e
245
+ report("Ractor: Failed to flush the appenders for another Ractor", e)
246
+ end
247
+ ensure
248
+ reply(requester, result)
249
+ end
250
+
251
+ # Replies to the thread of the main Ractor that registered the token, or to the Ractor that sent
252
+ # its reply port.
253
+ def reply(requester, result)
254
+ if requester.is_a?(Integer)
255
+ registered(requester)&.push([result])
256
+ else
257
+ requester << result
258
+ end
259
+ rescue ::Ractor::ClosedError
260
+ # The Ractor that asked has stopped waiting.
261
+ end
262
+
263
+ # Acknowledges a pause request (see .pause), then waits until the fork is over. It acknowledges by
264
+ # closing the Queue, rather than pushing onto it, so that every wait on it ends, including that of
265
+ # a pause in a signal trap that shares this one, whether or not the pause that the trap
266
+ # interrupted has had the acknowledgement yet.
267
+ def wait_for_fork(token)
268
+ paused, resume = registered(token)
269
+ return unless paused
270
+
271
+ paused.close
272
+ resume.pop
273
+ end
274
+
275
+ def report(message, exception)
276
+ Logger.processor.logger.error(message, exception)
277
+ rescue StandardError
278
+ nil
279
+ end
280
+ end
281
+ end
282
+ end
@@ -0,0 +1,28 @@
1
+ module SemanticLogger
2
+ # Internal, experimental: whether this Ruby can log from Ractors other than the main one (Ruby 4.0
3
+ # and later), and whether the code running now is in such a Ractor. The rest of Semantic Logger asks
4
+ # this module rather than checking Ractor itself.
5
+ module RactorSupport
6
+ if defined?(::Ractor::Port)
7
+ # Returns [true] since this Ruby can log from Ractors other than the main one.
8
+ def self.enabled?
9
+ true
10
+ end
11
+
12
+ # Returns [true|false] whether the current Ractor is one other than the main one.
13
+ def self.other_ractor?
14
+ !::Ractor.main?
15
+ end
16
+ else
17
+ # Returns [false] since this Ruby cannot log from Ractors other than the main one.
18
+ def self.enabled?
19
+ false
20
+ end
21
+
22
+ # Returns [false] since every log call runs in the main Ractor.
23
+ def self.other_ractor?
24
+ false
25
+ end
26
+ end
27
+ end
28
+ end