karafka 2.5.2 → 2.5.4.rc1

data/lib/karafka/cli/help.rb

@@ -10,7 +10,7 @@ module Karafka
       # Print available commands
       def call
         # Find the longest command for alignment purposes
-        max_command_length = self.class.commands.map(&:name).map(&:size).max
+        max_command_length = self.class.commands.map { |command| command.name.size }.max
 
         puts 'Karafka commands:'
 

data/lib/karafka/cli/install.rb

@@ -24,6 +24,7 @@ module Karafka
         'example_consumer.rb.erb' => 'app/consumers/example_consumer.rb'
       }.freeze
 
+      # Initializes the install command
       def initialize
         super
 
@@ -52,7 +53,7 @@ module Karafka
           FileUtils.mkdir_p File.dirname(pathed_target)
 
           template = File.read(Karafka.core_root.join("templates/#{source}"))
-          render = ::ERB.new(template, trim_mode: '-').result(binding)
+          render = ERB.new(template, trim_mode: '-').result(binding)
 
           File.write(pathed_target, render)
 

data/lib/karafka/cli/server.rb

@@ -10,7 +10,7 @@ module Karafka
       )
 
       # Types of things we can include / exclude from the routing via the CLI options
-      SUPPORTED_TYPES = ::Karafka::Routing::ActivityManager::SUPPORTED_TYPES
+      SUPPORTED_TYPES = Karafka::Routing::ActivityManager::SUPPORTED_TYPES
 
       private_constant :SUPPORTED_TYPES
 

data/lib/karafka/cli/swarm.rb

@@ -13,7 +13,7 @@ module Karafka
 
       # Starts the swarm
       def call
-        ::Karafka::Swarm.ensure_supported!
+        Karafka::Swarm.ensure_supported!
 
         # Print our banner and info in the dev mode
         print_marketing_info if Karafka::App.env.development?

data/lib/karafka/connection/client.rb

@@ -8,7 +8,7 @@ module Karafka
     # It is threadsafe and provides some security measures so we won't end up operating on a
     # closed consumer instance as it causes Ruby VM process to crash.
     class Client
-      include ::Karafka::Core::Helpers::Time
+      include Karafka::Core::Helpers::Time
       include Helpers::ConfigImporter.new(
         logger: %i[logger],
         tick_interval: %i[internal tick_interval],
@@ -37,7 +37,7 @@ module Karafka
       COOP_UNSUBSCRIBE_FACTOR = 0.5
 
       # Errors upon which we early report that something is off without retrying prior to the
-      # report
+      # report. Aside from those we ALWAYS early report on any fatal error.
       EARLY_REPORT_ERRORS = [
         :inconsistent_group_protocol, # 23
         :max_poll_exceeded, # -147
@@ -48,10 +48,7 @@ module Karafka
         :cluster_authorization_failed, # 31
         :illegal_generation,
         # this will not recover as fencing is permanent
-        :fenced, # -144
         :auto_offset_reset, # -140
-        # This can happen for many reasons, including issues with static membership being fenced
-        :fatal, # -150,
         # This can happen with new rebalance protocol and same group.instance.id in use
         :unreleased_instance_id # 111
       ].freeze
@@ -489,7 +486,7 @@ module Karafka
         # If the seek message offset is in a time format, we need to find the closest "real"
         # offset matching before we seek
         if message.offset.is_a?(Time)
-          tpl = ::Rdkafka::Consumer::TopicPartitionList.new
+          tpl = Rdkafka::Consumer::TopicPartitionList.new
           tpl.add_topic_and_partitions_with_offsets(
             message.topic,
             message.partition => message.offset
@@ -546,9 +543,9 @@ module Karafka
         sg_id = @subscription_group.id
 
         # Remove callbacks runners that were registered
-        ::Karafka::Core::Instrumentation.statistics_callbacks.delete(sg_id)
-        ::Karafka::Core::Instrumentation.error_callbacks.delete(sg_id)
-        ::Karafka::Core::Instrumentation.oauthbearer_token_refresh_callbacks.delete(sg_id)
+        Karafka::Core::Instrumentation.statistics_callbacks.delete(sg_id)
+        Karafka::Core::Instrumentation.error_callbacks.delete(sg_id)
+        Karafka::Core::Instrumentation.oauthbearer_token_refresh_callbacks.delete(sg_id)
 
         kafka.close
         @kafka = nil
@@ -564,7 +561,7 @@ module Karafka
       #   ignored. We do however want to instrument on it
       def unsubscribe
         kafka.unsubscribe
-      rescue ::Rdkafka::RdkafkaError => e
+      rescue Rdkafka::RdkafkaError => e
         Karafka.monitor.instrument(
           'error.occurred',
           caller: self,
@@ -593,8 +590,8 @@ module Karafka
       #   established. It may be `-1` in case we lost the assignment or we did not yet fetch data
       #   for this topic partition
       def topic_partition_position(topic, partition)
-        rd_partition = ::Rdkafka::Consumer::Partition.new(partition, nil, 0)
-        tpl = ::Rdkafka::Consumer::TopicPartitionList.new(topic => [rd_partition])
+        rd_partition = Rdkafka::Consumer::Partition.new(partition, nil, 0)
+        tpl = Rdkafka::Consumer::TopicPartitionList.new(topic => [rd_partition])
 
         kafka.position(tpl).to_h.fetch(topic).first.offset || -1
       end
@@ -645,7 +642,7 @@ module Karafka
         # If we did not exceed total time allocated, it means that we finished because of the
         # tick interval time limitations and not because time run out without any data
         time_poll.exceeded? ? nil : :tick_time
-      rescue ::Rdkafka::RdkafkaError => e
+      rescue Rdkafka::RdkafkaError => e
         early_report = false
 
         retryable = time_poll.attempts <= MAX_POLL_RETRIES && time_poll.retryable?
@@ -655,6 +652,7 @@ module Karafka
         # Those are mainly network issues and exceeding the max poll interval
         # We want to report early on max poll interval exceeding because it may mean that the
         # underlying processing is taking too much time and it is not LRJ
+
         case e.code
         when *EARLY_REPORT_ERRORS
           early_report = true
@@ -678,6 +676,9 @@ module Karafka
           return e.details
         end
 
+        # Any fatal error should always cause early report
+        early_report = true if e.fatal?
+
         if early_report || !retryable
           Karafka.monitor.instrument(
             'error.occurred',
@@ -704,7 +705,7 @@ module Karafka
       # Builds a new rdkafka consumer instance based on the subscription group configuration
       # @return [Rdkafka::Consumer]
       def build_consumer
-        ::Rdkafka::Config.logger = logger
+        Rdkafka::Config.logger = logger
 
         # We need to refresh the setup of this subscription group in case we started running in a
         # swarm. The initial configuration for validation comes from the parent node, but it needs
@@ -712,7 +713,7 @@ module Karafka
         # group instance id.
         @subscription_group.refresh
 
-        config = ::Rdkafka::Config.new(@subscription_group.kafka)
+        config = Rdkafka::Config.new(@subscription_group.kafka)
         config.consumer_rebalance_listener = @rebalance_callback
         # We want to manage the events queue independently from the messages queue. Thanks to that
         # we can ensure, that we get statistics and errors often enough even when not polling
@@ -724,7 +725,7 @@ module Karafka
         @name = consumer.name
 
         # Register statistics runner for this particular type of callbacks
-        ::Karafka::Core::Instrumentation.statistics_callbacks.add(
+        Karafka::Core::Instrumentation.statistics_callbacks.add(
           @subscription_group.id,
           Instrumentation::Callbacks::Statistics.new(
             @subscription_group.id,
@@ -734,7 +735,7 @@ module Karafka
         )
 
         # Register error tracking callback
-        ::Karafka::Core::Instrumentation.error_callbacks.add(
+        Karafka::Core::Instrumentation.error_callbacks.add(
           @subscription_group.id,
           Instrumentation::Callbacks::Error.new(
             @subscription_group.id,
@@ -743,7 +744,7 @@ module Karafka
           )
         )
 
-        ::Karafka::Core::Instrumentation.oauthbearer_token_refresh_callbacks.add(
+        Karafka::Core::Instrumentation.oauthbearer_token_refresh_callbacks.add(
           @subscription_group.id,
           Instrumentation::Callbacks::OauthbearerTokenRefresh.new(
             consumer

data/lib/karafka/connection/manager.rb

@@ -8,6 +8,7 @@ module Karafka
     # In the OSS version it starts listeners as they are without any connection management or
     # resources utilization supervision and shuts them down or quiets  when time has come
     class Manager
+      # Initializes the connection manager
       def initialize
         @once_executions = Set.new
       end

data/lib/karafka/connection/proxy.rb

@@ -155,7 +155,7 @@ module Karafka
 
       # @param tpl [Rdkafka::Consumer::TopicPartitionList] list of topics and partitions for which
       #   we want to get the lag on the defined CG
-      # @return [Hash<String, Hash>] hash with topics and their partitions lags
+      # @return [Hash{String => Hash}] hash with topics and their partitions lags
       def lag(tpl)
         l_config = proxy_config.committed
 

data/lib/karafka/connection/rebalance_manager.rb

@@ -43,7 +43,7 @@ module Karafka
         @buffer = buffer
 
         # Connects itself to the instrumentation pipeline so rebalances can be tracked
-        ::Karafka.monitor.subscribe(self)
+        Karafka.monitor.subscribe(self)
       end
 
       # Resets the rebalance manager state

data/lib/karafka/connection/status.rb

@@ -46,6 +46,7 @@ module Karafka
         RUBY
       end
 
+      # Initializes the connection status and sets it to pending
       def initialize
         @mutex = Mutex.new
         pending!

data/lib/karafka/constraints.rb

@@ -42,7 +42,7 @@ module Karafka
       # @param string [String]
       # @return [::Gem::Version]
       def version(string)
-        ::Gem::Version.new(string)
+        Gem::Version.new(string)
       end
     end
   end

data/lib/karafka/contracts/base.rb

@@ -3,7 +3,7 @@
 module Karafka
   module Contracts
     # Base contract for all Karafka contracts
-    class Base < ::Karafka::Core::Contractable::Contract
+    class Base < Karafka::Core::Contractable::Contract
       # @param data [Hash] data for validation
       # @param scope [Array<String>] nested scope if in use
       # @return [Boolean] true if all good

data/lib/karafka/deserializers/payload.rb

@@ -9,7 +9,7 @@ module Karafka
       # @return [Hash] hash with deserialized JSON data
       def call(message)
         # nil payload can be present for example for tombstone messages
-        message.raw_payload.nil? ? nil : ::JSON.parse(message.raw_payload)
+        message.raw_payload.nil? ? nil : JSON.parse(message.raw_payload)
       end
     end
   end

data/lib/karafka/helpers/async.rb

@@ -20,7 +20,7 @@ module Karafka
         #
         # @param base [Class] class we're including this module in
         def included(base)
-          base.extend ::Forwardable
+          base.extend Forwardable
 
           base.def_delegators :@thread, :join, :terminate, :name
         end

data/lib/karafka/helpers/config_importer.rb

@@ -5,7 +5,7 @@ module Karafka
     # Module allowing for configuration injections. By default injects whole app config
     # Allows for granular config injection
     class ConfigImporter < Module
-      # @param attributes [Hash<Symbol, Array<Symbol>>] map defining what we want to inject.
+      # @param attributes [Hash{Symbol => Array<Symbol>}] map defining what we want to inject.
       #   The key is the name under which attribute will be visible and the value is the full
       #   path to the attribute
       def initialize(attributes = { config: %i[itself] })
@@ -20,7 +20,7 @@ module Karafka
         @attributes.each do |name, path|
           model.class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{name}
-              @#{name} ||= ::Karafka::App.config.#{path.join('.')}
+              @#{name} ||= Karafka::App.config.#{path.join('.')}
             end
           RUBY
         end
@@ -33,7 +33,7 @@ module Karafka
         @attributes.each do |name, path|
           model.class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def self.#{name}
-              @#{name} ||= ::Karafka::App.config.#{path.join('.')}
+              @#{name} ||= Karafka::App.config.#{path.join('.')}
             end
           RUBY
         end

data/lib/karafka/helpers/multi_delegator.rb

@@ -25,6 +25,9 @@ module Karafka
           self
         end
 
+        # Creates an alias `to` for the `new` method to enable nice chaining API
+        # @return [MultiDelegator] new instance of the multi delegator
+        # @see #delegate
         alias to new
       end
     end

data/lib/karafka/instrumentation/assignments_tracker.rb

@@ -14,6 +14,7 @@ module Karafka
     class AssignmentsTracker
       include Singleton
 
+      # Initializes the assignments tracker with empty assignments
       def initialize
         @mutex = Mutex.new
         @assignments = Hash.new { |hash, key| hash[key] = [] }
@@ -21,7 +22,7 @@ module Karafka
 
       # Returns all the active/current assignments of this given process
       #
-      # @return [Hash<Karafka::Routing::Topic, Array<Integer>>]
+      # @return [Hash{Karafka::Routing::Topic => Array<Integer>}]
       #
       # @note Keep in mind, that those assignments can change any time, especially when working
       #   with multiple consumer groups or subscription groups.

data/lib/karafka/instrumentation/callbacks/error.rb

@@ -10,8 +10,8 @@ module Karafka
           monitor: %i[monitor]
         )
 
-        # @param subscription_group_id [String] id of the current subscription group instance
-        # @param consumer_group_id [String] id of the current consumer group
+        # @param subscription_group_id [String]
+        # @param consumer_group_id [String]
         # @param client_name [String] rdkafka client name
         def initialize(subscription_group_id, consumer_group_id, client_name)
           @subscription_group_id = subscription_group_id

data/lib/karafka/instrumentation/callbacks/statistics.rb

@@ -11,14 +11,14 @@ module Karafka
           monitor: %i[monitor]
         )
 
-        # @param subscription_group_id [String] id of the current subscription group
-        # @param consumer_group_id [String] id of the current consumer group
+        # @param subscription_group_id [String]
+        # @param consumer_group_id [String]
         # @param client_name [String] rdkafka client name
         def initialize(subscription_group_id, consumer_group_id, client_name)
           @subscription_group_id = subscription_group_id
           @consumer_group_id = consumer_group_id
           @client_name = client_name
-          @statistics_decorator = ::Karafka::Core::Monitoring::StatisticsDecorator.new
+          @statistics_decorator = Karafka::Core::Monitoring::StatisticsDecorator.new
         end
 
         # Emits decorated statistics to the monitor

data/lib/karafka/instrumentation/logger.rb

@@ -3,15 +3,15 @@
 module Karafka
   module Instrumentation
     # Default logger for Event Delegator
-    # @note It uses ::Logger features - providing basic logging
+    # @note It uses Logger features - providing basic logging
     class Logger < ::Logger
       # Map containing information about log level for given environment
       ENV_MAP = {
-        'production' => ::Logger::ERROR,
-        'test' => ::Logger::ERROR,
-        'development' => ::Logger::INFO,
-        'debug' => ::Logger::DEBUG,
-        'default' => ::Logger::INFO
+        'production' => Logger::ERROR,
+        'test' => Logger::ERROR,
+        'development' => Logger::INFO,
+        'debug' => Logger::DEBUG,
+        'default' => Logger::INFO
       }.freeze
 
       private_constant :ENV_MAP

data/lib/karafka/instrumentation/logger_listener.rb

@@ -24,8 +24,6 @@ module Karafka
         @log_polling = log_polling
       end
 
-      #
-      #
       # @param event [Karafka::Core::Monitoring::Event] event details including payload
       def on_connection_listener_before_fetch_loop(event)
         listener_id = event[:caller].id

data/lib/karafka/instrumentation/monitor.rb

@@ -5,14 +5,14 @@ module Karafka
     # Karafka instrumentation monitor that we use to publish events
     # By default uses our internal notifications bus but can be used with
     # `ActiveSupport::Notifications` as well
-    class Monitor < ::Karafka::Core::Monitoring::Monitor
+    class Monitor < Karafka::Core::Monitoring::Monitor
       attr_reader :notifications_bus
 
       # @param notifications_bus [Object] either our internal notifications bus or
       #   `ActiveSupport::Notifications`
       # @param namespace [String, nil] namespace for events or nil if no namespace
       def initialize(
-        notifications_bus = ::Karafka::Instrumentation::Notifications.new,
+        notifications_bus = Karafka::Instrumentation::Notifications.new,
         namespace = nil
       )
         super

data/lib/karafka/instrumentation/vendors/appsignal/base.rb

@@ -9,7 +9,7 @@ module Karafka
       module Appsignal
         # Base for all the instrumentation listeners
         class Base
-          include ::Karafka::Core::Configurable
+          include Karafka::Core::Configurable
           extend Forwardable
 
           # @param block [Proc] configuration block

data/lib/karafka/instrumentation/vendors/appsignal/metrics_listener.rb

@@ -44,11 +44,15 @@ module Karafka
 
           # Types of errors originating from user code in the consumer flow
           USER_CONSUMER_ERROR_TYPES = %w[
+            consumer.initialized.error
+            consumer.wrap.error
             consumer.consume.error
             consumer.revoked.error
+            consumer.idle.error
             consumer.shutdown.error
             consumer.tick.error
             consumer.eofed.error
+            consumer.after_consume.error
           ].freeze
 
           private_constant :USER_CONSUMER_ERROR_TYPES

data/lib/karafka/instrumentation/vendors/datadog/logger_listener.rb

@@ -9,7 +9,7 @@ module Karafka
         # A karafka's logger listener for Datadog
         # It depends on the 'ddtrace' gem
         class LoggerListener
-          include ::Karafka::Core::Configurable
+          include Karafka::Core::Configurable
           extend Forwardable
 
           def_delegators :config, :client, :service_name
@@ -90,42 +90,58 @@ module Karafka
             client.active_span&.set_error(error)
 
             case event[:type]
+            when 'consumer.initialized.error'
+              error "Consumer initialized error: #{error}"
+            when 'consumer.wrap.error'
+              error "Consumer wrap failed due to an error: #{error}"
             when 'consumer.consume.error'
               error "Consumer consuming error: #{error}"
             when 'consumer.revoked.error'
               error "Consumer on revoked failed due to an error: #{error}"
-            when 'consumer.before_schedule.error'
-              error "Consumer before schedule failed due to an error: #{error}"
-            when 'consumer.before_consume.error'
-              error "Consumer before consume failed due to an error: #{error}"
-            when 'consumer.after_consume.error'
-              error "Consumer after consume failed due to an error: #{error}"
+            when 'consumer.idle.error'
+              error "Consumer idle failed due to an error: #{error}"
             when 'consumer.shutdown.error'
               error "Consumer on shutdown failed due to an error: #{error}"
             when 'consumer.tick.error'
-              error "Consumer tick failed due to an error: #{error}"
+              error "Consumer on tick failed due to an error: #{error}"
             when 'consumer.eofed.error'
-              error "Consumer eofed failed due to an error: #{error}"
+              error "Consumer on eofed failed due to an error: #{error}"
+            when 'consumer.after_consume.error'
+              error "Consumer on after_consume failed due to an error: #{error}"
             when 'worker.process.error'
               fatal "Worker processing failed due to an error: #{error}"
             when 'connection.listener.fetch_loop.error'
               error "Listener fetch loop error: #{error}"
+            when 'swarm.supervisor.error'
+              fatal "Swarm supervisor crashed due to an error: #{error}"
             when 'runner.call.error'
               fatal "Runner crashed due to an error: #{error}"
             when 'app.stopping.error'
               error 'Forceful Karafka server stop'
-            when 'swarm.supervisor.error'
-              fatal "Swarm supervisor crashed due to an error: #{error}"
+            when 'app.forceful_stopping.error'
+              error "Forceful shutdown error occurred: #{error}"
             when 'librdkafka.error'
               error "librdkafka internal error occurred: #{error}"
-              # Those will only occur when retries in the client fail and when they did not stop
-              # after back-offs
+            when 'callbacks.statistics.error'
+              error "callbacks.statistics processing failed due to an error: #{error}"
+            when 'callbacks.error.error'
+              error "callbacks.error processing failed due to an error: #{error}"
+            # Those will only occur when retries in the client fail and when they did not stop
+            # after back-offs
             when 'connection.client.poll.error'
               error "Data polling error occurred: #{error}"
+            when 'connection.client.rebalance_callback.error'
+              error "Rebalance callback error occurred: #{error}"
+            when 'connection.client.unsubscribe.error'
+              error "Client unsubscribe error occurred: #{error}"
+            when 'parallel_segments.reducer.error'
+              error "Parallel segments reducer error occurred: #{error}"
+            when 'parallel_segments.partitioner.error'
+              error "Parallel segments partitioner error occurred: #{error}"
+            when 'virtual_partitions.partitioner.error'
+              error "Virtual partitions partitioner error occurred: #{error}"
             else
-              pop_tags
-              # This should never happen. Please contact the maintainers
-              raise Errors::UnsupportedCaseError, event
+              error "#{event[:type]} error occurred: #{error}"
             end
 
             pop_tags

data/lib/karafka/instrumentation/vendors/datadog/metrics_listener.rb

@@ -11,7 +11,7 @@ module Karafka
         #
         # @note You need to setup the `dogstatsd-ruby` client and assign it
         class MetricsListener
-          include ::Karafka::Core::Configurable
+          include Karafka::Core::Configurable
           extend Forwardable
 
           def_delegators(
@@ -212,7 +212,7 @@ module Karafka
               )
             else
               raise(
-                ::ArgumentError,
+                ArgumentError,
                 'distribution_mode setting value must be either :histogram or :distribution'
               )
             end

data/lib/karafka/instrumentation/vendors/kubernetes/base_listener.rb

@@ -10,7 +10,7 @@ module Karafka
         # Base Kubernetes Listener providing basic HTTP server capabilities to respond with health
         # statuses
         class BaseListener
-          include ::Karafka::Core::Helpers::Time
+          include Karafka::Core::Helpers::Time
 
           # All good with Karafka
           OK_CODE = '200 OK'

data/lib/karafka/instrumentation/vendors/kubernetes/liveness_listener.rb

@@ -26,19 +26,6 @@ module Karafka
         #
         # @note Please use `Kubernetes::SwarmLivenessListener` when operating in the swarm mode
         class LivenessListener < BaseListener
-          # When any of those occurs, it means something went wrong in a way that cannot be
-          # recovered. In such cases we should report that the consumer process is not healthy.
-          # - `fenced` - This instance has been fenced by a newer instance and will not do any
-          #   processing at all never. Fencing most of the time means the instance.group.id has
-          #   been reused without properly terminating the previous consumer process first
-          # - `fatal` - any fatal error that halts the processing forever
-          UNRECOVERABLE_RDKAFKA_ERRORS = [
-            :fenced, # -144
-            :fatal # -150
-          ].freeze
-
-          private_constant :UNRECOVERABLE_RDKAFKA_ERRORS
-
           # @param hostname [String, nil] hostname or nil to bind on all
           # @param port [Integer] TCP port on which we want to run our HTTP status server
           # @param consuming_ttl [Integer] time in ms after which we consider consumption hanging.
@@ -113,8 +100,9 @@ module Karafka
 
             # We are only interested in the rdkafka errors
             return unless error.is_a?(Rdkafka::RdkafkaError)
-            # We mark as unrecoverable only on certain errors that will not be fixed by retrying
-            return unless UNRECOVERABLE_RDKAFKA_ERRORS.include?(error.code)
+            # When any of those occurs, it means something went wrong in a way that cannot be
+            # recovered. In such cases we should report that the consumer process is not healthy.
+            return unless error.fatal?
 
             @unrecoverable = error.code
           end

data/lib/karafka/licenser.rb

@@ -46,7 +46,7 @@ module Karafka
 
         # We gsub and strip in case someone copy-pasted it as a multi line string
         formatted_token = license_config.token.strip.delete("\n").delete(' ')
-        decoded_token = Base64.decode64(formatted_token)
+        decoded_token = formatted_token.unpack1('m') # decode from base64
 
         begin
           data = public_key.public_decrypt(decoded_token)

data/lib/karafka/messages/builders/batch_metadata.rb

@@ -46,7 +46,7 @@ module Karafka
           # @note Message can be from the future in case consumer machine and Kafka cluster drift
           #   apart and the machine is behind the cluster.
           def local_created_at(last_message)
-            now = ::Time.now
+            now = Time.now
 
             return now unless last_message
 

data/lib/karafka/messages/messages.rb

@@ -64,6 +64,38 @@ module Karafka
         @messages_array.dup
       end
 
+      # Returns the underlying messages array directly without duplication.
+      #
+      # This method exists to provide Karafka internals with direct access to the messages array,
+      # bypassing any monkey patches that external libraries may apply to enumerable methods.
+      #
+      # ## Why this method exists
+      #
+      # External instrumentation libraries like DataDog's `dd-trace-rb` patch the `#each` method
+      # on this class to create tracing spans around message iteration. While this is desirable
+      # for user code (to trace message processing), it causes problems when Karafka's internal
+      # infrastructure iterates over messages for housekeeping tasks (offset tracking,
+      # deserialization, etc.) - creating empty/unwanted spans.
+      #
+      # By using `raw.map` or `raw.each` instead of `map` or `each` directly, internal code
+      # bypasses the patched `#each` method since it operates on the raw Array, not this class.
+      #
+      # ## Usage
+      #
+      # This method should ONLY be used by Karafka internals. User-facing code (consumers,
+      # ActiveJob processors, etc.) should use regular `#each`/`#map` so that instrumentation
+      # libraries can properly trace message processing.
+      #
+      # @return [Array<Karafka::Messages::Message>] the underlying messages array (not a copy)
+      #
+      # @note This returns the actual internal array, not a copy. Do not modify it.
+      # @see https://github.com/karafka/karafka/issues/2939
+      #
+      # @private
+      def raw
+        @messages_array
+      end
+
       alias count size
     end
   end