julewire-core 1.0.0

data/lib/julewire/core/diagnostics/health.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+      class Health
+        def initialize(
+          counter_keys:,
+          callback_failure_counter: nil,
+          callback_metadata: {},
+          failure_counter: nil,
+          track_failures: true
+        )
+          @callback_failure_counter = callback_failure_counter
+          @callback_metadata = callback_metadata
+          @failure_counter = failure_counter
+          @track_failures = track_failures
+          @mutex = Mutex.new
+          counter_keys = counter_keys.to_a
+          counter_keys = counter_keys.union([:failures]) if @track_failures
+          @counts = counter_keys.to_h { [it, 0] }
+          @current_degradation = nil
+          @last_callback_failure = nil
+          @last_failure = nil
+          @last_loss = nil
+        end
+
+        def increment(key, by: 1)
+          @mutex.synchronize { increment_unlocked(key, by: by) }
+        end
+
+        def counts
+          @mutex.synchronize { @counts.dup.freeze }
+        end
+
+        def degradation_marker
+          @mutex.synchronize { @current_degradation }
+        end
+
+        def degraded?(status_from: :current)
+          @mutex.synchronize { degraded_unlocked?(status_from) }
+        end
+
+        def last_callback_failure
+          @mutex.synchronize { @last_callback_failure }
+        end
+
+        def last_failure
+          @mutex.synchronize { @last_failure }
+        end
+
+        def last_loss
+          @mutex.synchronize { @last_loss }
+        end
+
+        def clear_degradation
+          @mutex.synchronize { @current_degradation = nil }
+        end
+
+        def clear_degradation_if_unchanged(marker)
+          @mutex.synchronize { @current_degradation = nil if @current_degradation.equal?(marker) }
+        end
+
+        def clear_failures!
+          @mutex.synchronize do
+            @current_degradation = nil
+            @last_callback_failure = nil
+            @last_failure = nil
+            @last_loss = nil
+          end
+          self
+        end
+
+        def record_failure(error, callback: nil, counter: @failure_counter, degrade: true, **metadata)
+          failure = FailureSnapshot.build(error, **metadata)
+          @mutex.synchronize do
+            increment_unlocked(:failures) if @track_failures
+            increment_unlocked(counter) if counter && counter != :failures && @counts.key?(counter)
+            @last_failure = failure
+            @current_degradation = failure if degrade
+          end
+          notify_failure_callback(callback, error, metadata)
+          failure
+        end
+
+        def record_callback_failure(callback_failure)
+          @mutex.synchronize do
+            @last_callback_failure = callback_failure.to_h
+            increment_unlocked(@callback_failure_counter) if @callback_failure_counter
+          end
+        end
+
+        def record_loss(reason:, counter: reason, degrade: true, **metadata)
+          loss = { reason: reason }.merge(metadata).compact.freeze
+          @mutex.synchronize do
+            increment_unlocked(counter) if counter && @counts.key?(counter)
+            @last_loss = loss
+            @current_degradation = loss if degrade
+          end
+          loss
+        end
+
+        def record_success
+          @mutex.synchronize { @current_degradation = nil }
+          self
+        end
+
+        def snapshot(status: nil, status_from: :current, include_loss: false, **fields)
+          @mutex.synchronize do
+            result = {
+              counts: @counts.dup.freeze,
+              last_failure: @last_failure,
+              status: status || (degraded_unlocked?(status_from) ? :degraded : :ok)
+            }
+            result[:last_loss] = @last_loss if include_loss
+            result.merge(fields).compact.freeze
+          end
+        end
+
+        private
+
+        def notify_failure_callback(callback, error, metadata)
+          callback_result = CallbackNotifier.call(callback, error, @callback_metadata.merge(metadata))
+          record_callback_failure(callback_result) if CallbackNotifier.failure?(callback_result)
+        end
+
+        def increment_unlocked(key, by: 1)
+          @counts[key] = @counts.fetch(key) + by
+        end
+
+        def degraded_unlocked?(status_from)
+          case status_from
+          when :current
+            !!@current_degradation
+          when :failure_or_loss
+            !!(@last_failure || @last_loss)
+          else
+            raise ArgumentError, "unknown health status source: #{status_from.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/diagnostics/integration_health_store.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+      class IntegrationHealthStore
+        def initialize
+          @mutex = Mutex.new
+          @entries = {}
+        end
+
+        def record_failure(integration, error, **metadata)
+          name = normalize_name(integration)
+          metadata = { phase: :integration, integration: name }.merge(metadata)
+          @mutex.synchronize do
+            entry_for(name).record_failure(error, **metadata)
+          end
+          nil
+        rescue StandardError
+          nil
+        end
+
+        def record_success(integration)
+          name = normalize_name(integration)
+          @mutex.synchronize do
+            entry_for(name).record_success
+          end
+          nil
+        rescue StandardError
+          nil
+        end
+
+        def health
+          @mutex.synchronize do
+            @entries.to_h { |name, entry| [name, entry.snapshot] }.freeze
+          end
+        end
+
+        def reset!
+          @mutex.synchronize { @entries.clear }
+          nil
+        end
+
+        def after_fork!
+          @mutex = Mutex.new
+          @entries = {}
+          nil
+        end
+
+        private
+
+        def entry_for(name)
+          @entries[name] ||= Health.new(counter_keys: [:failures])
+        end
+
+        def normalize_name(value)
+          Core.normalize_name(value, name: :integration)
+        rescue StandardError
+          :unknown
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/diagnostics/internal_records.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+      module InternalRecords
+        class << self
+          def emit_error(error, error_backtrace_lines:)
+            Core::Records::Draft.build(
+              {
+                severity: :error,
+                kind: :point,
+                event: "julewire.emit_error",
+                source: "julewire",
+                message: "Julewire emit failed",
+                payload: {
+                  error: failure_details(error)
+                }
+              },
+              context: {},
+              scope: nil,
+              error_backtrace_lines: error_backtrace_lines
+            )
+          end
+
+          def processor_error(processor_name:, error:, record_metadata:, error_backtrace_lines:)
+            Core::Records::Draft.build(
+              {
+                severity: :error,
+                kind: :point,
+                event: "julewire.processor_error",
+                source: "julewire",
+                message: "Julewire processor failed",
+                labels: labels(record_metadata),
+                payload: {
+                  processor: processor_name,
+                  error: failure_details(error),
+                  record: record_metadata
+                }
+              },
+              context: {},
+              scope: nil,
+              error_backtrace_lines: error_backtrace_lines
+            )
+          end
+
+          private
+
+          def labels(record_metadata)
+            labels = record_metadata[:labels]
+            labels.is_a?(Hash) ? labels : {}
+          end
+
+          def failure_details(error)
+            { class: error.class.name }.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/diagnostics/invalid_severity_reporter.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+      module InvalidSeverityReporter
+        @warned = false
+        @mutex = Mutex.new
+
+        class RuntimeCounter
+          def initialize
+            @mutex = Mutex.new
+            @count = 0
+            @last = nil
+          end
+
+          def call(value, source: nil, event: nil)
+            metadata = InvalidSeverityReporter.metadata(value, source: source, event: event)
+            @mutex.synchronize do
+              @count += 1
+              @last = metadata
+            end
+            InvalidSeverityReporter.warn_once(metadata)
+          rescue StandardError
+            nil
+          end
+
+          def health
+            @mutex.synchronize do
+              {
+                count: @count,
+                last_event: @last&.fetch(:event, nil),
+                last_source: @last&.fetch(:source, nil),
+                last_value_class: @last&.fetch(:value_class, nil)
+              }.compact
+            end
+          end
+
+          def reset!
+            @mutex.synchronize do
+              @count = 0
+              @last = nil
+            end
+            nil
+          end
+
+          def reset_after_fork!
+            @mutex = Mutex.new
+            @count = 0
+            @last = nil
+            nil
+          end
+        end
+
+        private_constant :RuntimeCounter
+
+        class << self
+          def call(value, source: nil, event: nil)
+            warning_only.call(value, source: source, event: event)
+          rescue StandardError
+            nil
+          end
+
+          def counter = RuntimeCounter.new
+
+          def warn_once(metadata)
+            return unless first_warning?
+
+            # Bypass Ruby's verbosity gates; this warning is emitted once.
+            Warning.warn("julewire: unsupported record severity #{metadata.fetch(:value_class)}; using :info\n")
+          end
+
+          def reset!
+            @mutex.synchronize { @warned = false }
+            nil
+          end
+
+          def reset_after_fork!
+            @mutex = Mutex.new
+            @warned = false
+            nil
+          end
+
+          def metadata(value, source:, event:)
+            {
+              event: event,
+              source: source,
+              value_class: value.class.name || value.class.to_s
+            }.compact.freeze
+          rescue StandardError
+            { value_class: "unknown" }.freeze
+          end
+
+          private
+
+          def warning_only
+            @warning_only ||= RuntimeCounter.new
+          end
+
+          def first_warning?
+            @mutex.synchronize do
+              return false if @warned
+
+              @warned = true
+              true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/diagnostics/meta_observer.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+      class MetaObserver
+        DEFAULT_EVENT = "julewire.runtime_health"
+        DEFAULT_INTERVAL = 30
+
+        class << self
+          def attach!(runtime_name = :default, target: :meta, start: true, **)
+            observer = new(
+              runtime: Julewire.runtime(runtime_name),
+              target_runtime: Julewire.runtime(target),
+              runtime_name: runtime_name,
+              target_name: target,
+              **
+            )
+            observer.start! if start
+            observer
+          end
+        end
+
+        def initialize(
+          runtime:,
+          target_runtime:,
+          runtime_name: :default,
+          target_name: :meta,
+          event: DEFAULT_EVENT,
+          interval: DEFAULT_INTERVAL,
+          include_ok: false,
+          scheduler: Scheduling::SharedScheduler
+        )
+          @runtime = runtime
+          @target_runtime = target_runtime
+          @runtime_name = Core.normalize_name(runtime_name, name: :runtime_name)
+          @target_name = Core.normalize_name(target_name, name: :target_name)
+          @event = event.to_s
+          @interval = Validation.validate_integer_limit!(interval, name: :interval, positive: true)
+          @include_ok = include_ok ? true : false
+          @scheduler = scheduler
+          @mutex = Mutex.new
+          @last_signature = nil
+          @last_failure = nil
+          @started = false
+          @stopped = false
+          @token = nil
+          @serializer_pool_key = :"julewire_core_meta_observer_serializers_#{object_id}"
+        end
+
+        def start!
+          @mutex.synchronize do
+            return self if @started && !@stopped
+
+            @started = true
+            @stopped = false
+            schedule_next
+          end
+          self
+        end
+
+        def stop!
+          token = @mutex.synchronize do
+            @stopped = true
+            @started = false
+            @token
+          end
+          @scheduler.cancel(token) if token
+          self
+        end
+
+        def sample!
+          health = @runtime.health
+          signature = signature_for(health)
+          changed = @mutex.synchronize do
+            changed = signature != @last_signature
+            @last_signature = signature
+            changed
+          end
+          return false unless changed
+          return false unless emit_health?(health)
+
+          emit_health(health)
+          true
+        rescue StandardError => e
+          record_failure(e)
+          false
+        end
+
+        def health
+          @mutex.synchronize do
+            {
+              event: @event,
+              include_ok: @include_ok,
+              interval: @interval,
+              last_failure: @last_failure,
+              observed_runtime: @runtime_name,
+              running: @started && !@stopped,
+              status: @last_failure ? :degraded : :ok,
+              target_runtime: @target_name
+            }.compact.freeze
+          end
+        end
+
+        private
+
+        def schedule_next
+          @token = @scheduler.schedule(@interval) { scheduled_sample }
+        end
+
+        def scheduled_sample
+          sample!
+          @mutex.synchronize { schedule_next unless @stopped }
+        rescue StandardError => e
+          record_failure(e)
+        end
+
+        def emit_health?(health)
+          @include_ok || health[:status] != :ok
+        end
+
+        def emit_health(health)
+          status = health.fetch(:status, :unknown)
+          @target_runtime.emit_without_level(
+            severity: severity_for(status),
+            source: :julewire,
+            event: @event,
+            message: "Julewire runtime #{@runtime_name} is #{status}",
+            runtime: @runtime_name,
+            status: status,
+            health: health
+          )
+        end
+
+        def severity_for(status)
+          status == :ok ? :info : :warn
+        end
+
+        def signature_for(health)
+          serializer = cached_serializer
+          return build_serializer.serialize(health).hash if serializer.in_use?
+
+          serializer.serialize(health).hash
+        end
+
+        def cached_serializer
+          Serialization::SerializerPool.serializer(@serializer_pool_key, :signature) { build_serializer }
+        end
+
+        def build_serializer
+          Serialization::Serializer.new(compact_empty: true)
+        end
+
+        def record_failure(error)
+          failure = FailureSnapshot.build(error, phase: :meta_observer)
+          @mutex.synchronize { @last_failure = failure }
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/diagnostics/process_integration_health.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+      module ProcessIntegrationHealth
+        @store = IntegrationHealthStore.new
+
+        class << self
+          def record_failure(...) = @store.record_failure(...)
+
+          def record_success(...) = @store.record_success(...)
+
+          def health = @store.health
+
+          def reset! = @store.reset!
+
+          def after_fork!
+            @store = IntegrationHealthStore.new
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/diagnostics/tail/renderer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+      class Tail
+        class Renderer
+          DEFAULT_MAX_VALUE_BYTES = Serialization::TextEncoder::DEFAULT_MAX_VALUE_BYTES
+
+          def initialize(max_value_bytes: DEFAULT_MAX_VALUE_BYTES)
+            @max_value_bytes = Validation.validate_integer_limit!(
+              max_value_bytes,
+              name: :max_value_bytes,
+              positive: true
+            )
+          end
+
+          def call(entries, color: false)
+            encoder = Serialization::TextEncoder.new(
+              color: color,
+              max_value_bytes: @max_value_bytes
+            )
+            entries.map { encoder.call(payload_for(it)) }.join
+          end
+
+          private
+
+          def payload_for(entry)
+            record = entry.record
+            record.merge("timestamp" => record["timestamp"] || entry.at.iso8601(6))
+          end
+        end
+      end
+    end
+  end
+end