karafka 2.0.41 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9560b22fc8cfd59dcaeb6551bcc0b2d2ebfef2f162a12905fa3aefe0c9c5865e
-  data.tar.gz: a5b7aba125288ec96cf3b862e72447bf467fe23f923c232fe1d3ff9c48b1fdb4
+  metadata.gz: e54dc80fd5a3a93857fd6a3a175030f7cb2eee1f77668d6936b705b0789c4228
+  data.tar.gz: e7f3b02811432987048bc599c2c4a6f0444fe13d98ca4aa8e87cebd5aaa8037a
 SHA512:
-  metadata.gz: d6581af85f8900d2d5ce91b6f9ec8ed0e1f6be5f3e80c36315c44c8dc07c30949566e281f40feb1b54cc9bbca771ac2188637e916d19edcb2fe26c04aeb362e1
-  data.tar.gz: e467612b3185b5ec764d387e72507b617bf49d702436da2021d467fb0c23630aa98151c9679444a34114317a8c52e3c37f0268c6a6bdb4564ffa1bab51993109
+  metadata.gz: 871ed7a55421041b1b232c47b3da0f625b8f2114c00057daf883223d3da4dc16637c9f0b4714cebe4a5f33249beac9bd7abbe15ec122f5b1a45a3c953dcb1465
+  data.tar.gz: ac2cc50c3277bd0bac7e3a2af40cc6d5a9c3aa92fc8cc3d2b12b8645329d269d0ed0d80c462d2fa6a03a677213e84802a1dfe8fdc1c494348b1a8b4fd9ef8459

data/.github/workflows/ci.yml

@@ -62,7 +62,7 @@ jobs:
         run: \curl -sSL https://api.coditsu.io/run/ci | bash
 
   specs:
-    timeout-minutes: 45
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     needs: diffend
     strategy:
@@ -102,7 +102,7 @@ jobs:
         run: bin/rspecs
 
   integrations:
-    timeout-minutes: 30
+    timeout-minutes: 45
     runs-on: ubuntu-latest
     needs: diffend
     strategy:

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Karafka framework changelog
 
+## 2.1.4 (2023-06-06)
+- [Fix] `processing_lag` and `consumption_lag` on empty batch fail on shutdown usage (#1475)
+
+## 2.1.3 (2023-05-29)
+- [Maintenance] Add linter to ensure, that all integration specs end with `_spec.rb`.
+- [Fix] Fix `#retrying?` helper result value (Aerdayne).
+- [Fix] Fix `mark_as_consumed!` raising an error instead of `false` on `unknown_member_id` (#1461).
+- [Fix] Enable phantom tests.
+
+## 2.1.2 (2023-05-26)
+- Set minimum `karafka-core` on `2.0.13` to make sure correct version of `karafka-rdkafka` is used.
+- Set minimum `waterdrop` on `2.5.3` to make sure correct version of `waterdrop` is used.
+
+## 2.1.1 (2023-05-24)
+- [Fix] Liveness Probe Doesn't Meet HTTP 1.1 Criteria - Causing Kubernetes Restarts (#1450)
+
+## 2.1.0 (2023-05-22)
+- **[Feature]** Provide ability to use CurrentAttributes with ActiveJob's Karafka adapter (federicomoretti).
+- **[Feature]** Introduce collective Virtual Partitions offset management.
+- **[Feature]** Use virtual offsets to filter out messages that would be re-processed upon retries.
+- [Improvement] No longer break processing on failing parallel virtual partitions in ActiveJob because it is compensated by virtual marking.
+- [Improvement] Always use Virtual offset management for Pro ActiveJobs.
+- [Improvement] Do not attempt to mark offsets on already revoked partitions.
+- [Improvement] Make sure, that VP components are not injected into non VP strategies.
+- [Improvement] Improve complex strategies inheritance flow.
+- [Improvement] Optimize offset management for DLQ + MoM feature combinations.
+- [Change] Removed `Karafka::Pro::BaseConsumer` in favor of `Karafka::BaseConsumer`. (#1345)
+- [Fix] Fix for `max_messages` and `max_wait_time` not having reference in errors.yml (#1443)
+
+### Upgrade notes
+
+1. Upgrade to Karafka `2.0.41` prior to upgrading to `2.1.0`.
+2. Replace `Karafka::Pro::BaseConsumer` references to `Karafka::BaseConsumer`.
+3. Replace `Karafka::Instrumentation::Vendors::Datadog:Listener` with `Karafka::Instrumentation::Vendors::Datadog::MetricsListener`.
+
 ## 2.0.41 (2023-14-19)
 - **[Feature]** Provide `Karafka::Pro::Iterator` for anonymous topic/partitions iterations and messages lookups (#1389 and #1427).
 - [Improvement] Optimize topic lookup for `read_topic` admin method usage.
@@ -60,7 +95,7 @@
 
 ## 2.0.35 (2023-03-13)
 - **[Feature]** Allow for defining topics config via the DSL and its automatic creation via CLI command.
-- **[Feature]** Allow for full topics reset and topics repartitioning via the CLI. 
+- **[Feature]** Allow for full topics reset and topics repartitioning via the CLI.
 
 ## 2.0.34 (2023-03-04)
 - [Improvement] Attach an `embedded` tag to Karafka processes started using the embedded API.

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    karafka (2.0.41)
-      karafka-core (>= 2.0.12, < 3.0.0)
+    karafka (2.1.4)
+      karafka-core (>= 2.0.13, < 3.0.0)
       thor (>= 0.20)
-      waterdrop (>= 2.4.10, < 3.0.0)
+      waterdrop (>= 2.5.3, < 3.0.0)
       zeitwerk (~> 2.3)
 
 GEM
@@ -28,34 +28,34 @@ GEM
     ffi (1.15.5)
     globalid (1.1.0)
       activesupport (>= 5.0)
-    i18n (1.12.0)
+    i18n (1.13.0)
       concurrent-ruby (~> 1.0)
-    karafka-core (2.0.12)
+    karafka-core (2.0.13)
       concurrent-ruby (>= 1.1)
-      karafka-rdkafka (>= 0.12.1)
-    karafka-rdkafka (0.12.1)
+      karafka-rdkafka (>= 0.12.3)
+    karafka-rdkafka (0.12.3)
       ffi (~> 1.15)
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-web (0.5.1)
+    karafka-web (0.5.2)
       erubi (~> 1.4)
       karafka (>= 2.0.40, < 3.0.0)
       karafka-core (>= 2.0.12, < 3.0.0)
       roda (~> 3.63)
       tilt (~> 2.0)
-    mini_portile2 (2.8.1)
+    mini_portile2 (2.8.2)
     minitest (5.18.0)
     rack (3.0.7)
     rake (13.0.6)
-    roda (3.67.0)
+    roda (3.68.0)
       rack
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
       rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.1)
+    rspec-core (3.12.2)
       rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.2)
+    rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-mocks (3.12.5)
@@ -68,14 +68,14 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    thor (1.2.1)
+    thor (1.2.2)
     tilt (2.1.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    waterdrop (2.5.1)
-      karafka-core (>= 2.0.12, < 3.0.0)
+    waterdrop (2.5.3)
+      karafka-core (>= 2.0.13, < 3.0.0)
       zeitwerk (~> 2.3)
-    zeitwerk (2.6.7)
+    zeitwerk (2.6.8)
 
 PLATFORMS
   x86_64-linux
@@ -90,4 +90,4 @@ DEPENDENCIES
   simplecov
 
 BUNDLED WITH
-   2.4.10
+   2.4.12

data/README.md

@@ -59,8 +59,8 @@ We also maintain many [integration specs](https://github.com/karafka/karafka/tre
 1. Add and install Karafka:
 
 ```bash
-# Make sure to install Karafka 2.0
-bundle add karafka --version ">= 2.0.28"
+# Make sure to install Karafka 2.1
+bundle add karafka --version ">= 2.1.2"
 
 bundle exec karafka install
 ```

data/config/locales/errors.yml

@@ -15,6 +15,13 @@ en:
       shutdown_timeout_format: needs to be an integer bigger than 0
       max_wait_time_format: needs to be an integer bigger than 0
       kafka_format: needs to be a filled hash
+      internal.processing.jobs_builder_format: cannot be nil
+      internal.processing.scheduler: cannot be nil
+      internal.processing.coordinator_class: cannot be nil
+      internal.processing.partitioner_class: cannot be nil
+      internal.active_job.dispatcher: cannot be nil
+      internal.active_job.job_options_contract: cannot be nil
+      internal.active_job.consumer_class: cannot be nil
       internal.status_format: needs to be present
       internal.process_format: needs to be present
       internal.routing.builder_format: needs to be present
@@ -31,7 +38,10 @@ en:
       topics_missing: No topics to subscribe to
 
     topic:
+      kafka: needs to be a hash with kafka scope settings details
       missing: needs to be present
+      max_messages_format: 'needs to be an integer bigger than 0'
+      max_wait_time_format: 'needs to be an integer bigger than 0'
       name_format: 'needs to be a string with a Kafka accepted format'
       deserializer_format: needs to be present
       consumer_format: needs to be present

data/config/locales/pro_errors.yml

@@ -4,8 +4,6 @@ en:
       virtual_partitions.partitioner_respond_to_call: needs to be defined and needs to respond to `#call`
       virtual_partitions.max_partitions_format: needs to be equal or more than 1
 
-      manual_offset_management_not_with_virtual_partitions: cannot be used together with Virtual Partitions
-
       long_running_job.active_format: needs to be either true or false
 
       dead_letter_queue_with_virtual_partitions: when using Dead Letter Queue with Virtual Partitions, at least one retry is required.

data/docker-compose.yml

@@ -1,14 +1,14 @@
 version: '2'
 services:
   zookeeper:
-    container_name: karafka_20_zookeeper
+    container_name: karafka_21_zookeeper
     image: wurstmeister/zookeeper
     restart: on-failure
     ports:
       - '2181:2181'
 
   kafka:
-    container_name: karafka_20_kafka
+    container_name: karafka_21_kafka
     image: wurstmeister/kafka
     ports:
       - '9092:9092'

data/karafka.gemspec

@@ -21,9 +21,9 @@ Gem::Specification.new do |spec|
     without having to focus on things that are not your business domain.
   DESC
 
-  spec.add_dependency 'karafka-core', '>= 2.0.12', '< 3.0.0'
+  spec.add_dependency 'karafka-core', '>= 2.0.13', '< 3.0.0'
   spec.add_dependency 'thor', '>= 0.20'
-  spec.add_dependency 'waterdrop', '>= 2.4.10', '< 3.0.0'
+  spec.add_dependency 'waterdrop', '>= 2.5.3', '< 3.0.0'
   spec.add_dependency 'zeitwerk', '~> 2.3'
 
   if $PROGRAM_NAME.end_with?('gem')

data/lib/karafka/active_job/consumer.rb

@@ -24,21 +24,26 @@ module Karafka
       #
       # @param job_message [Karafka::Messages::Message] message with active job
       def consume_job(job_message)
-        # We technically speaking could set this as deserializer and reference it from the
-        # message instead of using the `#raw_payload`. This is not done on purpose to simplify
-        # the ActiveJob setup here
-        job = ::ActiveSupport::JSON.decode(job_message.raw_payload)
+        with_deserialized_job(job_message) do |job|
+          tags.add(:job_class, job['job_class'])
 
-        tags.add(:job_class, job['job_class'])
+          payload = { caller: self, job: job, message: job_message }
 
-        payload = { caller: self, job: job, message: job_message }
-
-        # We publish both to make it consistent with `consumer.x` events
-        Karafka.monitor.instrument('active_job.consume', payload)
-        Karafka.monitor.instrument('active_job.consumed', payload) do
-          ::ActiveJob::Base.execute(job)
+          # We publish both to make it consistent with `consumer.x` events
+          Karafka.monitor.instrument('active_job.consume', payload)
+          Karafka.monitor.instrument('active_job.consumed', payload) do
+            ::ActiveJob::Base.execute(job)
+          end
         end
       end
+
+      # @param job_message [Karafka::Messages::Message] message with active job
+      def with_deserialized_job(job_message)
+        # We technically speaking could set this as deserializer and reference it from the
+        # message instead of using the `#raw_payload`. This is not done on purpose to simplify
+        # the ActiveJob setup here
+        yield ::ActiveSupport::JSON.decode(job_message.raw_payload)
+      end
     end
   end
 end

data/lib/karafka/active_job/current_attributes/loading.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Karafka
+  module ActiveJob
+    module CurrentAttributes
+      # Module expanding the job deserialization to extract current attributes and load them
+      # for the time of the job execution
+      module Loading
+        # @param job_message [Karafka::Messages::Message] message with active job
+        def with_deserialized_job(job_message)
+          super(job_message) do |job|
+            resetable = []
+
+            _cattr_klasses.each do |key, cattr_klass_str|
+              next unless job.key?(key)
+
+              attributes = job.delete(key)
+
+              cattr_klass = cattr_klass_str.constantize
+
+              attributes.each do |name, value|
+                cattr_klass.public_send("#{name}=", value)
+              end
+
+              resetable << cattr_klass
+            end
+
+            yield(job)
+
+            resetable.each(&:reset)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/active_job/current_attributes/persistence.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Karafka
+  module ActiveJob
+    module CurrentAttributes
+      # Module adding the current attributes persistence into the ActiveJob jobs
+      module Persistence
+        # Alters the job serialization to inject the current attributes into the json before we
+        # send it to Kafka
+        #
+        # @param job [ActiveJob::Base] job
+        def serialize_job(job)
+          json = super(job)
+
+          _cattr_klasses.each do |key, cattr_klass_str|
+            next if json.key?(key)
+
+            attrs = cattr_klass_str.constantize.attributes
+
+            json[key] = attrs unless attrs.empty?
+          end
+
+          json
+        end
+      end
+    end
+  end
+end

data/lib/karafka/active_job/current_attributes.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'active_support/current_attributes'
+require_relative 'current_attributes/loading'
+require_relative 'current_attributes/persistence'
+
+# This code is based on Sidekiqs approach to persisting current attributes
+# @see https://github.com/sidekiq/sidekiq/blob/main/lib/sidekiq/middleware/current_attributes.rb
+module Karafka
+  module ActiveJob
+    # Module that allows to persist current attributes on Karafka jobs
+    module CurrentAttributes
+      # Allows for persistence of given current attributes via AJ + Karafka
+      #
+      # @param klasses [Array<String, Class>] classes or names of the current attributes classes
+      def persist(*klasses)
+        # Support for providing multiple classes
+        klasses = Array(klasses).flatten
+
+        [Dispatcher, Consumer]
+          .reject { |expandable| expandable.respond_to?(:_cattr_klasses) }
+          .each { |expandable| expandable.class_attribute :_cattr_klasses, default: {} }
+
+        # Do not double inject in case of running persist multiple times
+        Dispatcher.prepend(Persistence) unless Dispatcher.ancestors.include?(Persistence)
+        Consumer.prepend(Loading) unless Consumer.ancestors.include?(Loading)
+
+        klasses.map(&:to_s).each do |stringified_klass|
+          # Prevent registering same klass multiple times
+          next if Dispatcher._cattr_klasses.value?(stringified_klass)
+
+          key = "cattr_#{Dispatcher._cattr_klasses.count}"
+
+          Dispatcher._cattr_klasses[key] = stringified_klass
+          Consumer._cattr_klasses[key] = stringified_klass
+        end
+      end
+
+      module_function :persist
+    end
+  end
+end

data/lib/karafka/active_job/dispatcher.rb

@@ -18,7 +18,7 @@ module Karafka
         ::Karafka.producer.public_send(
           fetch_option(job, :dispatch_method, DEFAULTS),
           topic: job.queue_name,
-          payload: ::ActiveSupport::JSON.encode(job.serialize)
+          payload: ::ActiveSupport::JSON.encode(serialize_job(job))
         )
       end
 
@@ -34,7 +34,7 @@ module Karafka
 
           dispatches[d_method] << {
             topic: job.queue_name,
-            payload: ::ActiveSupport::JSON.encode(job.serialize)
+            payload: ::ActiveSupport::JSON.encode(serialize_job(job))
           }
         end
 
@@ -58,6 +58,12 @@ module Karafka
           .karafka_options
           .fetch(key, defaults.fetch(key))
       end
+
+      # @param job [ActiveJob::Base] job
+      # @return [Hash] json representation of the job
+      def serialize_job(job)
+        job.serialize
+      end
     end
   end
 end

data/lib/karafka/base_consumer.rb

@@ -225,7 +225,7 @@ module Karafka
     #   different flow after there is an error, for example for resources cleanup, small manual
     #   backoff or different instrumentation tracking.
     def retrying?
-      coordinator.pause_tracker.attempt.positive?
+      coordinator.pause_tracker.attempt > 1
     end
 
     # Pauses the processing from the last offset to retry on given message

data/lib/karafka/connection/client.rb

@@ -30,7 +30,7 @@ module Karafka
       #
       # @param subscription_group [Karafka::Routing::SubscriptionGroup] subscription group
       #   with all the configuration details needed for us to create a client
-      # @return [Karafka::Connection::Rdk::Consumer]
+      # @return [Karafka::Connection::Client]
       def initialize(subscription_group)
         @id = SecureRandom.hex(6)
         # Name is set when we build consumer
@@ -305,6 +305,8 @@ module Karafka
         case e.code
         when :assignment_lost
           return false
+        when :unknown_member_id
+          return false
         when :no_offset
           return true
         when :coordinator_load_in_progress

data/lib/karafka/errors.rb

@@ -46,5 +46,8 @@ module Karafka
 
     # This should never happen. Please open an issue if it does.
     StrategyNotFoundError = Class.new(BaseError)
+
+    # This should never happen. Please open an issue if it does.
+    InvalidRealOffsetUsage = Class.new(BaseError)
   end
 end

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+module Karafka
+  module Instrumentation
+    module Vendors
+      # Namespace for instrumentation related with Kubernetes
+      module Kubernetes
+        # Kubernetes HTTP listener that does not only reply when process is not fully hanging, but
+        # also allows to define max time of processing and looping.
+        #
+        # Processes like Karafka server can hang while still being reachable. For example, in case
+        # something would hang inside of the user code, Karafka could stop polling and no new
+        # data would be processed, but process itself would still be active. This listener allows
+        # for defining of a ttl that gets bumped on each poll loop and before and after processing
+        # of a given messages batch.
+        class LivenessListener
+          include ::Karafka::Core::Helpers::Time
+
+          # All good with Karafka
+          OK_CODE = '204 No Content'
+
+          # Some timeouts, fail
+          FAIL_CODE = '500 Internal Server Error'
+
+          private_constant :OK_CODE, :FAIL_CODE
+
+          # @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.
+          #   It allows us to define max consumption time after which k8s should consider given
+          #   process as hanging
+          # @param polling_ttl [Integer] max time in ms for polling. If polling (any) does not
+          #   happen that often, process should be considered dead.
+          # @note The default TTL matches the default `max.poll.interval.ms`
+          def initialize(
+            hostname: nil,
+            port: 3000,
+            consuming_ttl: 5 * 60 * 1_000,
+            polling_ttl: 5 * 60 * 1_000
+          )
+            @server = TCPServer.new(*[hostname, port].compact)
+            @polling_ttl = polling_ttl
+            @consuming_ttl = consuming_ttl
+            @mutex = Mutex.new
+            @pollings = {}
+            @consumptions = {}
+
+            Thread.new do
+              loop do
+                break unless respond
+              end
+            end
+          end
+
+          # Tick on each fetch
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_connection_listener_fetch_loop(_event)
+            mark_polling_tick
+          end
+
+          # Tick on starting work
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_consumer_consume(_event)
+            mark_consumption_tick
+          end
+
+          # Tick on finished work
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_consumer_consumed(_event)
+            clear_consumption_tick
+          end
+
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_consumer_revoke(_event)
+            mark_consumption_tick
+          end
+
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_consumer_revoked(_event)
+            clear_consumption_tick
+          end
+
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_consumer_shutting_down(_event)
+            mark_consumption_tick
+          end
+
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_consumer_shutdown(_event)
+            clear_consumption_tick
+          end
+
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_error_occurred(_event)
+            clear_consumption_tick
+            clear_polling_tick
+          end
+
+          # Stop the http server when we stop the process
+          # @param _event [Karafka::Core::Monitoring::Event]
+          def on_app_stopped(_event)
+            @server.close
+          end
+
+          private
+
+          # Wraps the logic with a mutex
+          # @param block [Proc] code we want to run in mutex
+          def synchronize(&block)
+            @mutex.synchronize(&block)
+          end
+
+          # @return [Integer] object id of the current thread
+          def thread_id
+            Thread.current.object_id
+          end
+
+          # Update the polling tick time for current thread
+          def mark_polling_tick
+            synchronize do
+              @pollings[thread_id] = monotonic_now
+            end
+          end
+
+          # Clear current thread polling time tracker
+          def clear_polling_tick
+            synchronize do
+              @pollings.delete(thread_id)
+            end
+          end
+
+          # Update the processing tick time
+          def mark_consumption_tick
+            synchronize do
+              @consumptions[thread_id] = monotonic_now
+            end
+          end
+
+          # Clear current thread consumption time tracker
+          def clear_consumption_tick
+            synchronize do
+              @consumptions.delete(thread_id)
+            end
+          end
+
+          # Responds to a HTTP request with the process liveness status
+          def respond
+            client = @server.accept
+            client.gets
+            client.print "HTTP/1.1 #{status}\r\n"
+            client.print "Content-Type: text/plain\r\n"
+            client.print "\r\n"
+            client.close
+
+            true
+          rescue Errno::ECONNRESET, Errno::EPIPE, IOError
+            !@server.closed?
+          end
+
+          # Did we exceed any of the ttls
+          # @return [String] 204 string if ok, 500 otherwise
+          def status
+            time = monotonic_now
+
+            return FAIL_CODE if @pollings.values.any? { |tick| (time - tick) > @polling_ttl }
+            return FAIL_CODE if @consumptions.values.any? { |tick| (time - tick) > @consuming_ttl }
+
+            OK_CODE
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/messages/batch_metadata.rb

@@ -20,14 +20,21 @@ module Karafka
     ) do
       # This lag describes how long did it take for a message to be consumed from the moment it was
       # created
+      #
+      #
+      # @return [Integer] number of milliseconds
+      # @note In case of usage in workless flows, this value will be set to -1
       def consumption_lag
-        time_distance_in_ms(processed_at, created_at)
+        processed_at ? time_distance_in_ms(processed_at, created_at) : -1
       end
 
       # This lag describes how long did a batch have to wait before it was picked up by one of the
       # workers
+      #
+      # @return [Integer] number of milliseconds
+      # @note In case of usage in workless flows, this value will be set to -1
       def processing_lag
-        time_distance_in_ms(processed_at, scheduled_at)
+        processed_at ? time_distance_in_ms(processed_at, scheduled_at) : -1
       end
 
       private