karafka-web 0.11.5 → 0.11.6

data/lib/karafka/web/ui/models/metrics/charts/aggregated.rb

@@ -19,9 +19,9 @@ module Karafka
               # @return [String] JSON with bytes sent and bytes received metrics
               def data_transfers
                 scale_factor = Processing::TimeSeriesTracker::TIME_RANGES
-                               .fetch(@period)
-                               .fetch(:resolution)
-                               .then { |factor| factor / 1_024.to_f }
+                  .fetch(@period)
+                  .fetch(:resolution)
+                  .then { |factor| factor / 1_024.to_f }
 
                 received = bytes_received.map do |element|
                   [element[0], element[1] * scale_factor]

data/lib/karafka/web/ui/models/metrics/charts/topics.rb

@@ -44,7 +44,7 @@ module Karafka
 
                 # We name it with a space because someone may have a topic called "total" and we
                 # want to avoid collisions
-                per_topic.merge('total sum' => total.to_a).to_json
+                per_topic.merge("total sum" => total.to_a).to_json
               end
 
               # @return [String] JSON with per-topic, highest LSO freeze duration. Useful for
@@ -53,7 +53,7 @@ module Karafka
                 topics = Hash.new { |h, k| h[k] = Hash.new { |h2, k2| h2[k2] = [] } }
 
                 @data.to_h.each do |topic, metrics|
-                  topic_without_cg = topic.split('[').first
+                  topic_without_cg = topic.split("[").first
 
                   metrics.each do |current|
                     ls_offset_fd = current.last[:ls_offset_fd] || 0
@@ -86,7 +86,7 @@ module Karafka
                 topics = {}
 
                 @data.to_h.each do |topic, metrics|
-                  topic_without_cg = topic.split('[').first
+                  topic_without_cg = topic.split("[").first
 
                   # If we've already seen this topic data, we can skip
                   next if topics.include?(topic_without_cg)

data/lib/karafka/web/ui/models/metrics/topics.rb

@@ -61,14 +61,14 @@ module Karafka
               # Hash with all potential keys that a single sample metric can have
               # This allows us to fill gaps not only in times but also in values
               base_samples = topics_metrics
-                             .values
-                             .map(&:values)
-                             .flatten
-                             .select { |val| val.is_a?(Hash) }
-                             .flat_map(&:keys)
-                             .uniq
-                             .to_h { |key| [key, nil] }
-                             .freeze
+                .values
+                .map(&:values)
+                .flatten
+                .select { |val| val.is_a?(Hash) }
+                .flat_map(&:keys)
+                .uniq
+                .to_h { |key| [key, nil] }
+                .freeze
 
               # Normalize data in between topics reportings
               # One topic may have a sample in a time moment when a different one does not

data/lib/karafka/web/ui/models/processes.rb

@@ -48,9 +48,9 @@ module Karafka
               return [] if processes.empty?
 
               offsets = processes
-                        .values
-                        .map { |process| process[:offset] }
-                        .sort
+                .values
+                .map { |process| process[:offset] }
+                .sort
 
               Lib::Admin.read_topic(
                 ::Karafka::Web.config.topics.consumers.reports.name,

data/lib/karafka/web/ui/models/recurring_tasks/schedule.rb

@@ -32,8 +32,8 @@ module Karafka
 
                 # Out of those messages we pick the most recent persisted schedule
                 candidate = messages
-                            .reverse
-                            .find { |message| message.key == 'state:schedule' }
+                  .reverse
+                  .find { |message| message.key == "state:schedule" }
 
                 # If there is a schedule message we use its data to build schedule, if not false
                 return false unless candidate

data/lib/karafka/web/ui/models/status/checks/base.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          # Namespace for all individual status check classes.
+          #
+          # Each check is a separate class that inherits from Base and implements
+          # the DSL for declaring dependencies and check behavior.
+          module Checks
+            # Base class for all status checks.
+            #
+            # Provides a DSL for declaring check dependencies and characteristics,
+            # as well as common functionality for executing checks.
+            #
+            # @example Creating a simple independent check
+            #   class Enabled < Base
+            #     independent!
+            #
+            #     def call
+            #       enabled = ::Karafka::App.routes.map(&:name).include?(
+            #         ::Karafka::Web.config.group_id
+            #       )
+            #       step(enabled ? :success : :failure)
+            #     end
+            #   end
+            #
+            # @example Creating a dependent check
+            #   class Connection < Base
+            #     depends_on :enabled
+            #
+            #     def call
+            #       # Implementation...
+            #       step(:success, { time: context.connection_time })
+            #     end
+            #   end
+            class Base
+              class << self
+                # @return [Symbol, nil] the dependency check name, or nil if independent
+                attr_reader :dependency
+
+                # Declares that this check depends on another check.
+                #
+                # When a check has a dependency, it will be halted if the dependency
+                # fails.
+                #
+                # @param check_name [Symbol] the name of the check this depends on
+                # @return [Symbol] the dependency name
+                #
+                # @example
+                #   class Connection < Base
+                #     depends_on :enabled
+                #   end
+                def depends_on(check_name)
+                  @dependency = check_name
+                end
+
+                # Marks this check as independent (no dependencies).
+                #
+                # Independent checks don't depend on any other check and will
+                # always execute regardless of other check results.
+                #
+                # @return [Boolean] true
+                def independent!
+                  @independent = true
+                end
+
+                # Checks if this is an independent check.
+                #
+                # @return [Boolean] true if this check has no dependencies
+                def independent?
+                  @independent || false
+                end
+
+                # Returns the halted details for this check.
+                #
+                # Override this method in subclasses to provide specific details
+                # when the check is halted due to dependency failure.
+                #
+                # @return [Hash, Array] the default details for halted state
+                def halted_details
+                  {}
+                end
+              end
+
+              # Initializes the check with a shared context.
+              #
+              # @param context [Status::Context] the shared context containing
+              #   cached data and configuration helpers
+              def initialize(context)
+                @context = context
+              end
+
+              # Executes the check and returns a Step result.
+              #
+              # Subclasses must implement this method to perform the actual check.
+              #
+              # @return [Status::Step] the result of the check
+              # @raise [NotImplementedError] if not implemented by subclass
+              def call
+                raise NotImplementedError, "Subclasses must implement #call"
+              end
+
+              private
+
+              # @return [Status::Context] the shared context
+              attr_reader :context
+
+              # Creates a new Step result.
+              #
+              # Helper method to create Step instances with less verbosity.
+              #
+              # @param status [Symbol] the status (:success, :warning, :failure, :halted)
+              # @param details [Hash, Array] optional details about the check result
+              # @return [Status::Step] a new Step instance
+              def step(status, details = {})
+                Step.new(status, details)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/commands_topic_presence.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if the commands topic exists for Pro users.
+            #
+            # The commands topic (karafka_consumers_commands) is used by Pro features
+            # like consumer commanding (pause, resume, trace, etc.). While it's created
+            # by CreateTopics for all users (to allow smooth upgrades), it's only
+            # actively used by Pro users.
+            #
+            # For OSS users, this check always succeeds since they don't use commanding.
+            # For Pro users, it warns if the topic is missing.
+            class CommandsTopicPresence < Base
+              depends_on :topics
+
+              # Executes the commands topic presence check.
+              #
+              # @return [Status::Step] success if not Pro or if topic exists,
+              #   warning if Pro and topic is missing
+              def call
+                # OSS users don't need the commands topic
+                return step(:success) unless ::Karafka.pro?
+
+                topic_name = context.topics_consumers_commands
+                present = topic_present?(topic_name)
+
+                step(present ? :success : :warning, { topic_name: topic_name, present: present })
+              end
+
+              private
+
+              # Checks if a topic exists in the cluster.
+              #
+              # @param topic_name [String] the topic name to check
+              # @return [Boolean] true if the topic exists
+              def topic_present?(topic_name)
+                context.cluster_info.topics.any? do |topic|
+                  topic[:topic_name] == topic_name
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/connection.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if we can connect to Kafka and measures connection latency.
+            #
+            # Some users try to work with Kafka over the internet with high latency,
+            # which can make the connection unstable. This check measures connection
+            # time and warns when it's too high.
+            #
+            # Connection times:
+            # - < 1 second: success
+            # - 1-1000 seconds: warning (high latency)
+            # - > 1000 seconds or failure: failure
+            class Connection < Base
+              depends_on :enabled
+
+              class << self
+                # @return [Hash] the default details for halted state
+                def halted_details
+                  { time: nil }
+                end
+              end
+
+              # Executes the connection check.
+              #
+              # Attempts to connect to Kafka and measures the connection time.
+              # Caches the result in the context for subsequent checks.
+              #
+              # @return [Status::Step] result with connection time in details
+              def call
+                connect unless context.connection_time
+
+                level = if context.connection_time < 1_000
+                  :success
+                elsif context.connection_time < 1_000_000
+                  :warning
+                else
+                  :failure
+                end
+
+                step(level, { time: context.connection_time })
+              end
+
+              private
+
+              # Attempts to connect to Kafka and stores connection info in context.
+              #
+              # On success, stores cluster_info and connection_time.
+              # On failure, sets connection_time to 1_000_000 (indicating failure).
+              def connect
+                started = Time.now.to_f
+                context.cluster_info = Models::ClusterInfo.fetch
+                context.connection_time = (Time.now.to_f - started) * 1_000
+              rescue ::Rdkafka::RdkafkaError
+                context.connection_time = 1_000_000
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/consumers_reports.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if we can read and operate on the current processes data.
+            #
+            # This verifies that the consumers reports can be parsed and loaded
+            # into process objects for display in the UI.
+            class ConsumersReports < Base
+              depends_on :initial_consumers_metrics
+
+              # Executes the consumers reports check.
+              #
+              # Attempts to load all processes from the current state. Caches
+              # the result in context for subsequent checks.
+              #
+              # @return [Status::Step] result (success or failure on parse error)
+              def call
+                context.processes ||= Models::Processes.all(context.current_state)
+                step(:success)
+              rescue JSON::ParserError
+                step(:failure)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/consumers_reports_schema_state.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if the consumer can digest the consumers reports with its schema.
+            #
+            # The schema_state in the current state indicates whether the consumer
+            # processing reports can properly deserialize them. If incompatible,
+            # data may be lost or corrupted.
+            class ConsumersReportsSchemaState < Base
+              depends_on :state_calculation
+
+              # Executes the consumers reports schema state check.
+              #
+              # Verifies that the schema_state is 'compatible'.
+              #
+              # @return [Status::Step] success if compatible, failure otherwise
+              def call
+                compatible = context.current_state[:schema_state] == "compatible"
+                step(compatible ? :success : :failure)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/consumers_schemas.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if any consumer processes have incompatible schemas.
+            #
+            # Schema compatibility is important for proper data deserialization.
+            # This check identifies processes that don't match the expected schema
+            # version used by the Web UI.
+            #
+            # @note This is a warning-only check - incompatible schemas don't block
+            #   the dependency chain but should be addressed.
+            class ConsumersSchemas < Base
+              depends_on :consumers_reports
+
+              class << self
+                # @return [Hash] details with empty incompatible list for halted state
+                def halted_details
+                  { incompatible: [] }
+                end
+              end
+
+              # Executes the consumers schemas check.
+              #
+              # Identifies processes with incompatible schema versions.
+              #
+              # @return [Status::Step] success if all compatible, warning if any incompatible
+              def call
+                incompatible = context.processes.reject(&:schema_compatible?)
+                status = incompatible.empty? ? :success : :warning
+
+                step(status, { incompatible: incompatible })
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/enabled.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if karafka-web is enabled in the karafka.rb routing.
+            #
+            # This is the first check in the chain and verifies that the consumer group
+            # for the Web UI is properly injected into the routing. Without this,
+            # the Web UI cannot function.
+            #
+            # @note This check does NOT verify if the group is active because that may
+            #   depend on configuration details. It only checks that the routing is
+            #   aware of the deserializer and other Web UI requirements.
+            class Enabled < Base
+              independent!
+
+              # Executes the enabled check.
+              #
+              # Looks for the Web UI consumer group in the Karafka routing.
+              #
+              # @return [Status::Step] success if the group is found, failure otherwise
+              def call
+                enabled = ::Karafka::App.routes.map(&:name).include?(
+                  ::Karafka::Web.config.group_id
+                )
+
+                step(enabled ? :success : :failure)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/initial_consumers_metrics.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if the initial consumers metrics are present and can be deserialized.
+            #
+            # The consumers metrics topic must contain valid data that can be parsed.
+            # This check fetches the current metrics and attempts to deserialize it.
+            class InitialConsumersMetrics < Base
+              depends_on :initial_consumers_state
+
+              class << self
+                # @return [Hash] details indicating presence issue for halted state
+                def halted_details
+                  { issue_type: :presence }
+                end
+              end
+
+              # Executes the initial consumers metrics check.
+              #
+              # Fetches the current consumers metrics from Kafka and verifies it can
+              # be deserialized. Caches the result in context for subsequent checks.
+              #
+              # @return [Status::Step] result with issue_type in details
+              def call
+                details = { issue_type: :presence }
+
+                begin
+                  context.current_metrics ||= Models::ConsumersMetrics.current
+                  status = context.current_metrics ? :success : :failure
+                rescue JSON::ParserError
+                  status = :failure
+                  details[:issue_type] = :deserialization
+                end
+
+                step(status, details)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/initial_consumers_state.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if the initial consumers state is present and can be deserialized.
+            #
+            # The consumers state topic must contain valid data that can be parsed.
+            # This check fetches the current state and attempts to deserialize it.
+            class InitialConsumersState < Base
+              depends_on :replication
+
+              class << self
+                # @return [Hash] details indicating presence issue for halted state
+                def halted_details
+                  { issue_type: :presence }
+                end
+              end
+
+              # Executes the initial consumers state check.
+              #
+              # Fetches the current consumers state from Kafka and verifies it can
+              # be deserialized. Caches the result in context for subsequent checks.
+              #
+              # @return [Status::Step] result with issue_type in details
+              def call
+                details = { issue_type: :presence }
+
+                begin
+                  context.current_state ||= Models::ConsumersState.current
+                  status = context.current_state ? :success : :failure
+                rescue JSON::ParserError
+                  status = :failure
+                  details[:issue_type] = :deserialization
+                end
+
+                step(status, details)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/live_reporting.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if there is at least one active Karafka server reporting to the Web UI.
+            #
+            # If no processes are reporting, the Web UI won't have any data to display.
+            # This is a critical check for ensuring the system is actually being monitored.
+            class LiveReporting < Base
+              depends_on :consumers_reports
+
+              # Executes the live reporting check.
+              #
+              # Verifies that there is at least one process in the list.
+              #
+              # @return [Status::Step] success if processes exist, failure if empty
+              def call
+                status = context.processes.empty? ? :failure : :success
+                step(status)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/web/ui/models/status/checks/materializing_lag.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Web
+    module Ui
+      module Models
+        class Status
+          module Checks
+            # Checks if there is significant lag in the reporting of aggregated data.
+            #
+            # If there's a large gap between when data is reported and when it's
+            # materialized, the Web UI will show stale information. This often
+            # indicates over-saturation on the consumer that materializes states.
+            #
+            # The maximum acceptable lag is twice the tracking interval.
+            #
+            # @note Since both states and metrics are reported together, checking
+            #   one of them is sufficient.
+            class MaterializingLag < Base
+              depends_on :live_reporting
+
+              class << self
+                # @return [Hash] details with zero lag for halted state
+                def halted_details
+                  max_lag = (Web.config.tracking.interval * 2) / 1_000
+                  { lag: 0, max_lag: max_lag }
+                end
+              end
+
+              # Executes the materializing lag check.
+              #
+              # Compares the current state's dispatch time with the current time.
+              #
+              # @return [Status::Step] success if lag is acceptable, failure if too high
+              def call
+                max_lag = (Web.config.tracking.interval * 2) / 1_000
+                lag = Time.now.to_f - context.current_state.dispatched_at
+
+                status = (lag > max_lag) ? :failure : :success
+
+                step(status, { lag: lag, max_lag: max_lag })
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end