karafka 1.4.12 → 2.2.10

data/lib/karafka/instrumentation/logger_listener.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Instrumentation
+    # Default listener that hooks up to our instrumentation and uses its events for logging
+    # It can be removed/replaced or anything without any harm to the Karafka app flow.
+    class LoggerListener
+      # Log levels that we use in this particular listener
+      USED_LOG_LEVELS = %i[
+        debug
+        info
+        warn
+        error
+        fatal
+      ].freeze
+
+      private_constant :USED_LOG_LEVELS
+
+      # Logs each messages fetching attempt
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_connection_listener_fetch_loop(event)
+        listener = event[:caller]
+        debug "[#{listener.id}] Polling messages..."
+      end
+
+      # Logs about messages that we've received from Kafka
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_connection_listener_fetch_loop_received(event)
+        listener = event[:caller]
+        time = event[:time]
+        messages_count = event[:messages_buffer].size
+
+        message = "[#{listener.id}] Polled #{messages_count} messages in #{time}ms"
+
+        # We don't want the "polled 0" in dev as it would spam the log
+        # Instead we publish only info when there was anything we could poll and fail over to the
+        # zero notifications when in debug mode
+        messages_count.zero? ? debug(message) : info(message)
+      end
+
+      # Prints info about the fact that a given job has started
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_worker_process(event)
+        job = event[:job]
+        job_type = job.class.to_s.split('::').last
+        consumer = job.executor.topic.consumer
+        topic = job.executor.topic.name
+        partition = job.executor.partition
+        info "[#{job.id}] #{job_type} job for #{consumer} on #{topic}/#{partition} started"
+      end
+
+      # Prints info about the fact that a given job has finished
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_worker_processed(event)
+        job = event[:job]
+        time = event[:time]
+        job_type = job.class.to_s.split('::').last
+        consumer = job.executor.topic.consumer
+        topic = job.executor.topic.name
+        partition = job.executor.partition
+        info <<~MSG.tr("\n", ' ').strip!
+          [#{job.id}] #{job_type} job for #{consumer}
+          on #{topic}/#{partition} finished in #{time}ms
+        MSG
+      end
+
+      # Prints info about a consumer pause occurrence. Irrelevant if user or system initiated.
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      # @note There may be no offset provided in case user wants to pause on the consecutive offset
+      #   position. This can be beneficial when not wanting to purge the buffers.
+      def on_client_pause(event)
+        topic = event[:topic]
+        partition = event[:partition]
+        offset = event[:offset]
+        client = event[:caller]
+
+        info <<~MSG.tr("\n", ' ').strip!
+          [#{client.id}]
+          Pausing on topic #{topic}/#{partition}
+          on #{offset ? "offset #{offset}" : 'the consecutive offset'}
+        MSG
+      end
+
+      # Prints information about resuming of processing of a given topic partition
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_client_resume(event)
+        topic = event[:topic]
+        partition = event[:partition]
+        client = event[:caller]
+
+        info <<~MSG.tr("\n", ' ').strip!
+          [#{client.id}] Resuming on topic #{topic}/#{partition}
+        MSG
+      end
+
+      # Prints info about retry of processing after an error
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_consumer_consuming_retry(event)
+        topic = event[:topic]
+        partition = event[:partition]
+        offset = event[:offset]
+        consumer = event[:caller]
+        timeout = event[:timeout]
+
+        info <<~MSG.tr("\n", ' ').strip!
+          [#{consumer.id}] Retrying of #{consumer.class} after #{timeout} ms
+          on topic #{topic}/#{partition} from offset #{offset}
+        MSG
+      end
+
+      # Logs info about system signals that Karafka received and prints backtrace for threads in
+      # case of ttin
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_process_notice_signal(event)
+        info "Received #{event[:signal]} system signal"
+
+        # We print backtrace only for ttin
+        return unless event[:signal] == :SIGTTIN
+
+        # Inspired by Sidekiq
+        Thread.list.each do |thread|
+          tid = (thread.object_id ^ ::Process.pid).to_s(36)
+
+          warn "Thread TID-#{tid} #{thread['label']}"
+
+          if thread.backtrace
+            warn thread.backtrace.join("\n")
+          else
+            warn '<no backtrace available>'
+          end
+        end
+      end
+
+      # Logs info that we're running Karafka app.
+      #
+      # @param _event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_app_running(_event)
+        info "Running in #{RUBY_DESCRIPTION}"
+        info "Running Karafka #{Karafka::VERSION} server"
+
+        return if Karafka.pro?
+
+        info 'See LICENSE and the LGPL-3.0 for licensing details'
+      end
+
+      # @param _event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_app_quieting(_event)
+        info 'Switching to quiet mode. New messages will not be processed'
+      end
+
+      # @param _event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_app_quiet(_event)
+        info 'Reached quiet mode. No messages will be processed anymore'
+      end
+
+      # Logs info that we're going to stop the Karafka server.
+      #
+      # @param _event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_app_stopping(_event)
+        info 'Stopping Karafka server'
+      end
+
+      # Logs info that we stopped the Karafka server.
+      #
+      # @param _event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_app_stopped(_event)
+        info 'Stopped Karafka server'
+      end
+
+      # Logs info when we have dispatched a message the the DLQ
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_dead_letter_queue_dispatched(event)
+        consumer = event[:caller]
+        topic = consumer.topic.name
+        message = event[:message]
+        offset = message.offset
+        dlq_topic = consumer.topic.dead_letter_queue.topic
+        partition = message.partition
+
+        info <<~MSG.tr("\n", ' ').strip!
+          [#{consumer.id}] Dispatched message #{offset}
+          from #{topic}/#{partition}
+          to DLQ topic: #{dlq_topic}
+        MSG
+      end
+
+      # Logs info about throttling event
+      #
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_filtering_throttled(event)
+        consumer = event[:caller]
+        topic = consumer.topic.name
+        # Here we get last message before throttle
+        message = event[:message]
+        partition = message.partition
+        offset = message.offset
+
+        info <<~MSG.tr("\n", ' ').strip!
+          [#{consumer.id}] Throttled and will resume
+          from message #{offset}
+          on #{topic}/#{partition}
+        MSG
+      end
+
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_filtering_seek(event)
+        consumer = event[:caller]
+        topic = consumer.topic.name
+        # Message to which we seek
+        message = event[:message]
+        partition = message.partition
+        offset = message.offset
+
+        info <<~MSG.tr("\n", ' ').strip!
+          [#{consumer.id}] Post-filtering seeking to message #{offset}
+          on #{topic}/#{partition}
+        MSG
+      end
+
+      # There are many types of errors that can occur in many places, but we provide a single
+      # handler for all of them to simplify error instrumentation.
+      # @param event [Karafka::Core::Monitoring::Event] event details including payload
+      def on_error_occurred(event)
+        type = event[:type]
+        error = event[:error]
+        details = (error.backtrace || []).join("\n")
+
+        case type
+        when 'consumer.consume.error'
+          error "Consumer consuming error: #{error}"
+          error details
+        when 'consumer.revoked.error'
+          error "Consumer on revoked failed due to an error: #{error}"
+          error details
+        when 'consumer.before_enqueue.error'
+          error "Consumer before enqueue failed due to an error: #{error}"
+          error details
+        when 'consumer.before_consume.error'
+          error "Consumer before consume failed due to an error: #{error}"
+          error details
+        when 'consumer.after_consume.error'
+          error "Consumer after consume failed due to an error: #{error}"
+          error details
+        when 'consumer.idle.error'
+          error "Consumer idle failed due to an error: #{error}"
+          error details
+        when 'consumer.shutdown.error'
+          error "Consumer on shutdown failed due to an error: #{error}"
+          error details
+        when 'worker.process.error'
+          fatal "Worker processing failed due to an error: #{error}"
+          fatal details
+        when 'connection.listener.fetch_loop.error'
+          error "Listener fetch loop error: #{error}"
+          error details
+        when 'runner.call.error'
+          fatal "Runner crashed due to an error: #{error}"
+          fatal details
+        when 'app.stopping.error'
+          error 'Forceful Karafka server stop'
+        when 'librdkafka.error'
+          error "librdkafka internal error occurred: #{error}"
+          error details
+        # Those can occur when emitted statistics are consumed by the end user and the processing
+        # of statistics fails. The statistics are emitted from librdkafka main loop thread and
+        # any errors there crash the whole thread
+        when 'statistics.emitted.error'
+          error "statistics.emitted processing failed due to an error: #{error}"
+          error details
+        # 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}"
+          error details
+        when 'connection.client.rebalance_callback.error'
+          error "Rebalance callback error occurred: #{error}"
+          error details
+        when 'connection.client.unsubscribe.error'
+          error "Client unsubscribe error occurred: #{error}"
+          error details
+        else
+          # This should never happen. Please contact the maintainers
+          raise Errors::UnsupportedCaseError, event
+        end
+      end
+
+      USED_LOG_LEVELS.each do |log_level|
+        define_method log_level do |*args|
+          Karafka.logger.send(log_level, *args)
+        end
+      end
+    end
+  end
+end

data/lib/karafka/instrumentation/monitor.rb

@@ -1,69 +1,21 @@
 # frozen_string_literal: true
 
 module Karafka
-  # Namespace for all the things related with Karafka instrumentation process
   module Instrumentation
-    # Monitor is used to hookup external monitoring services to monitor how Karafka works
-    # It provides a standardized API for checking incoming messages/enqueueing etc
-    # Since it is a pub-sub based on dry-monitor, you can use as many subscribers/loggers at the
-    # same time, which means that you might have for example file logging and NewRelic at the same
-    # time
-    # @note This class acts as a singleton because we are only permitted to have single monitor
-    #   per running process (just as logger)
-    class Monitor < Dry::Monitor::Notifications
-      # List of events that we support in the system and to which a monitor client can hook up
-      # @note The non-error once support timestamp benchmarking
-      # @note Depending on Karafka extensions and additional engines, this might not be the
-      #   complete list of all the events. Please use the #available_events on fully loaded
-      #   Karafka system to determine all of the events you can use.
-      #   Last 4 events are from WaterDrop but for convenience we use the same monitor for the
-      #   whole karafka ecosystem
-      BASE_EVENTS = %w[
-        params.params.deserialize
-        params.params.deserialize.error
-        connection.listener.before_fetch_loop
-        connection.listener.fetch_loop
-        connection.listener.fetch_loop.error
-        connection.client.fetch_loop.error
-        connection.batch_delegator.call
-        connection.message_delegator.call
-        fetcher.call.error
-        backends.inline.process
-        process.notice_signal
-        consumers.responders.respond_with
-        async_producer.call.error
-        async_producer.call.retry
-        sync_producer.call.error
-        sync_producer.call.retry
-        app.initializing
-        app.initialized
-        app.running
-        app.stopping
-        app.stopping.error
-        app.stopped
-      ].freeze
+    # 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
+      attr_reader :notifications_bus
 
-      private_constant :BASE_EVENTS
-
-      # @return [Karafka::Instrumentation::Monitor] monitor instance for system instrumentation
-      def initialize
-        super(:karafka)
-        BASE_EVENTS.each(&method(:register_event))
-      end
-
-      # Allows us to subscribe to events with a code that will be yielded upon events
-      # @param event_name_or_listener [String, Object] name of the event we want to subscribe to
-      #   or a listener if we decide to go with object listener
-      def subscribe(event_name_or_listener)
-        return super unless event_name_or_listener.is_a?(String)
-        return super if available_events.include?(event_name_or_listener)
-
-        raise Errors::UnregisteredMonitorEventError, event_name_or_listener
-      end
-
-      # @return [Array<String>] names of available events to which we can subscribe
-      def available_events
-        __bus__.events.keys
+      # @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,
+        namespace = nil
+      )
+        super(notifications_bus, namespace)
       end
     end
   end

data/lib/karafka/instrumentation/notifications.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Karafka
+  # Namespace for all the things related with Karafka instrumentation process
+  module Instrumentation
+    # Monitor is used to hookup external monitoring services to monitor how Karafka works
+    # It provides a standardized API for checking incoming messages/enqueueing etc
+    # Since it is a pub-sub based on dry-monitor, you can use as many subscribers/loggers at the
+    # same time, which means that you might have for example file logging and NewRelic at the same
+    # time
+    # @note This class acts as a singleton because we are only permitted to have single monitor
+    #   per running process (just as logger)
+    class Notifications < Karafka::Core::Monitoring::Notifications
+      # List of events that we support in the system and to which a monitor client can hook up
+      # @note The non-error once support timestamp benchmarking
+      # @note Depending on Karafka extensions and additional engines, this might not be the
+      #   complete list of all the events. Please use the #available_events on fully loaded
+      #   Karafka system to determine all of the events you can use.
+      EVENTS = %w[
+        active_job.consume
+        active_job.consumed
+
+        app.initialized
+        app.running
+        app.quieting
+        app.quiet
+        app.stopping
+        app.stopped
+        app.terminated
+
+        client.pause
+        client.resume
+
+        connection.listener.before_fetch_loop
+        connection.listener.fetch_loop
+        connection.listener.fetch_loop.received
+
+        connection.client.poll.error
+        connection.client.unsubscribe.error
+
+        rebalance.partitions_assign
+        rebalance.partitions_assigned
+        rebalance.partitions_revoke
+        rebalance.partitions_revoked
+
+        consumer.consume
+        consumer.consumed
+        consumer.consuming.pause
+        consumer.consuming.retry
+        consumer.idle
+        consumer.revoke
+        consumer.revoked
+        consumer.shutting_down
+        consumer.shutdown
+
+        dead_letter_queue.dispatched
+
+        filtering.throttled
+        filtering.seek
+
+        process.notice_signal
+
+        statistics.emitted
+
+        worker.process
+        worker.processed
+        worker.completed
+
+        error.occurred
+      ].freeze
+
+      # @return [Karafka::Instrumentation::Monitor] monitor instance for system instrumentation
+      def initialize
+        super
+        EVENTS.each { |event| register_event(event) }
+      end
+    end
+  end
+end

data/lib/karafka/instrumentation/proctitle_listener.rb

@@ -4,22 +4,13 @@ module Karafka
   module Instrumentation
     # Listener that sets a proc title with a nice descriptive value
     class ProctitleListener
-      # Updates proc title to an initializing one
-      # @param _event [Dry::Events::Event] event details including payload
-      def on_app_initializing(_event)
-        setproctitle('initializing')
-      end
-
-      # Updates proc title to a running one
-      # @param _event [Dry::Events::Event] event details including payload
-      def on_app_running(_event)
-        setproctitle('running')
-      end
-
-      # Updates proc title to a stopping one
-      # @param _event [Dry::Events::Event] event details including payload
-      def on_app_stopping(_event)
-        setproctitle('stopping')
+      Status::STATES.each_key do |state|
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          # Updates proc title to an appropriate state
+          def on_app_#{state}(_event)
+            setproctitle('#{state}')
+          end
+        RUBY
       end
 
       private

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'client'
+
+module Karafka
+  module Instrumentation
+    module Vendors
+      # Namespace for Appsignal instrumentation
+      module Appsignal
+        # Base for all the instrumentation listeners
+        class Base
+          include ::Karafka::Core::Configurable
+          extend Forwardable
+
+          # @param block [Proc] configuration block
+          def initialize(&block)
+            configure
+            setup(&block) if block
+          end
+
+          # @param block [Proc] configuration block
+          # @note We define this alias to be consistent with `Karafka#setup`
+          def setup(&block)
+            configure(&block)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Instrumentation
+    module Vendors
+      module Appsignal
+        # Appsignal client wrapper
+        # We wrap the native client so we can inject our own stub in specs when needed
+        #
+        # It also abstracts away the notion of transactions and their management
+        #
+        # @note This client is abstract, it has no notion of Karafka whatsoever
+        class Client
+          # Starts an appsignal transaction with a given action name
+          #
+          # @param action_name [String] action name. For processing this should be equal to
+          #   consumer class + method name
+          def start_transaction(action_name)
+            transaction = ::Appsignal::Transaction.create(
+              SecureRandom.uuid,
+              ::Appsignal::Transaction::BACKGROUND_JOB,
+              ::Appsignal::Transaction::GenericRequest.new({})
+            )
+
+            transaction.set_action_if_nil(action_name)
+          end
+
+          # Stops the current transaction (if any)
+          def stop_transaction
+            return unless transaction?
+
+            ::Appsignal::Transaction.complete_current!
+          end
+
+          # Sets metadata on a current transaction (if any)
+          #
+          # @param metadata_hash [Hash] hash with metadata we want to set
+          def metadata=(metadata_hash)
+            return unless transaction?
+
+            transaction = ::Appsignal::Transaction.current
+
+            stringify_hash(metadata_hash).each do |key, value|
+              transaction.set_metadata(key, value)
+            end
+          end
+
+          # Increments counter with the given value and tags
+          #
+          # @param key [String] key we want to use
+          # @param value [Integer] increment value
+          # @param tags [Hash] additional extra tags
+          def count(key, value, tags)
+            ::Appsignal.increment_counter(
+              key,
+              value,
+              stringify_hash(tags)
+            )
+          end
+
+          # Sets gauge with the given value and tags
+          #
+          # @param key [String] key we want to use
+          # @param value [Integer] gauge value
+          # @param tags [Hash] additional extra tags
+          def gauge(key, value, tags)
+            ::Appsignal.set_gauge(
+              key,
+              value,
+              stringify_hash(tags)
+            )
+          end
+
+          # Sends the error that occurred to Appsignal
+          #
+          # @param error [Object] error we want to ship to Appsignal
+          def send_error(error)
+            # If we have an active transaction we should use it instead of creating a generic one
+            # That way proper namespace and other data may be transferred
+            #
+            # In case there is no transaction, a new generic background job one will be used
+            if transaction?
+              transaction.set_error(error)
+            else
+              ::Appsignal.send_error(error) do |transaction|
+                transaction.set_namespace(::Appsignal::Transaction::BACKGROUND_JOB)
+              end
+            end
+          end
+
+          # Registers the probe under a given name
+          # @param name [Symbol] probe name
+          # @param probe [Proc] code to run every minute
+          def register_probe(name, probe)
+            ::Appsignal::Minutely.probes.register(name, probe)
+          end
+
+          private
+
+          # @return [Boolean] do we have a transaction
+          def transaction?
+            ::Appsignal::Transaction.current?
+          end
+
+          # @return [::Appsignal::Transaction, nil] transaction or nil if not started
+          def transaction
+            ::Appsignal::Transaction.current
+          end
+
+          # Converts both keys and values of a hash into strings
+          # @param hash [Hash]
+          # @return [Hash]
+          def stringify_hash(hash)
+            hash
+              .transform_values(&:to_s)
+              .transform_keys!(&:to_s)
+          end
+        end
+      end
+    end
+  end
+end