mammoth 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55bd93a58c383e07fe1930ed71f20ea52c05dbfa77a2354e258caddd726865ce
-  data.tar.gz: 2b01106f391f82ed0079d7efdf934447cdeb168d2ee5d6029fb8ac7cd8a617b8
+  metadata.gz: 7d16f1b05d2ae82569933033416a20892ae7e7afc9cdd282aacd6343789157c3
+  data.tar.gz: 1af59d9757dd584f462c5a888246c73693459aff503f6ef775e24aa4c4d19b49
 SHA512:
-  metadata.gz: 4359b50a25fada22578bca1ab80c3afcc187ce6d181110d83157d7231bdc9fb5f32ab407b24d39619cd7e63fa8d4a4fc01c14fd27474f640d53c874c5411eff8
-  data.tar.gz: 62eb55bba9825caaf491f8ed38ceb9f3da95580a57736c6998bb2349fa1980eb472e2ce7c775972ce7d7d9f8d6fa1ad43daffb22da7847b03c6b898c02e25762
+  metadata.gz: 14452ab3df0aaae412be115a33b25b20ae3ef9698146e2f0e00c38f0453245ea9abec2a1cdd93a6f780288e722fb982b3fa3f7ab7fafc0de979c19abccd9a74e
+  data.tar.gz: 39832167b4069a9b8b8b4bab5ad86f2a3a150449e216d41a4a915fc2e748b471d3361f183b088a7a990402515351d6bf7e3e19c5576a683dabdb463e6e508dce

data/CHANGELOG.md

@@ -4,6 +4,34 @@
 
 # Changelog
 
+## Unreleased
+
+## 1.5.0 - 2026-07-19
+
+### Changed
+
+- Default the unauthenticated observability HTTP server to the loopback
+  interface and document the network controls required for non-loopback
+  bindings.
+- Implement `logging.level` with container-friendly JSON stdout logs for
+  application and replication lifecycle, delivery outcomes, retries, dead
+  letters, checkpoints, and debug-level work progress.
+- Require a patched `json` gem and remove the vulnerable bundled default-gem
+  specification from the runtime image to address CVE-2026-33210.
+
+### Quality
+
+- Run the container quickstart smoke test on pull requests and whenever Docker,
+  application, configuration, or dependency inputs change.
+- Added Dependabot updates, Ruby dependency auditing, dependency review,
+  CodeQL analysis, and high- and critical-severity container vulnerability
+  scanning.
+- Pin the Ruby container base image to an immutable digest and publish release
+  images with SBOM and maximum provenance attestations.
+- Published a full reference benchmark snapshot with machine-readable results,
+  raw output, and documented interpretation across projection, delivery,
+  fanout, SQLite operational state, observability, and dead-letter replay.
+
 ## 1.4.0 - 2026-07-19
 
 ### Added

data/README.md

@@ -17,6 +17,7 @@
 [![Gem Version](https://img.shields.io/gem/v/mammoth?logo=rubygems&logoColor=white)](https://rubygems.org/gems/mammoth)
 [![Requires Ruby 4.0+](https://img.shields.io/badge/Requires-Ruby%204.0%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
 [![CI](https://github.com/kanutocd/mammoth/actions/workflows/ci.yml/badge.svg)](https://github.com/kanutocd/mammoth/actions/workflows/ci.yml)
+[![Security](https://img.shields.io/github/actions/workflow/status/kanutocd/mammoth/security.yml?branch=main&event=push&label=security)](https://github.com/kanutocd/mammoth/actions/workflows/security.yml)
 [![Tested Against PostgreSQL 14–18](https://img.shields.io/badge/Tested%20Against-PostgreSQL%2014--18-336791?logo=postgresql&logoColor=white)](https://github.com/kanutocd/mammoth/blob/main/.github/workflows/ci.yml#L50)
 [![License](https://img.shields.io/badge/License-MIT-22C55E)](LICENSE.txt)
 
@@ -106,6 +107,7 @@ Mammoth 1.x includes:
 - per-destination payload removal and masking policies
 - per-destination enable/disable and retry policy controls
 - delivery worker with retry, delivered-ledger, and DLQ handling
+- configurable `debug`, `info`, `warn`, and `error` JSON logging to stdout
 - contiguous delivery watermark for checkpoint and PostgreSQL acknowledgement
 - source-owned transport LSN preservation independent of payload `commit_lsn`
 - fail-closed PostgreSQL slot and checkpoint continuity preflight
@@ -257,6 +259,30 @@ bundle exec ./exe/mammoth start config/mammoth.example.yml
 bundle exec ./exe/mammoth observability config/mammoth.example.yml
 ```
 
+## Logging
+
+Mammoth emits one JSON object per line to standard output. Set
+`logging.level` to `debug`, `info`, `warn`, or `error`; `info` is the
+recommended normal setting, while `debug` adds per-work and WAL acknowledgement
+records.
+
+```yaml
+logging:
+  level: info
+```
+
+In Docker Compose, follow the application, replication, delivery, retry,
+dead-letter, and checkpoint activity with:
+
+```bash
+docker compose logs -f mammoth
+```
+
+Operational identifiers are included, but payload bodies, configured headers,
+credentials, signing secrets, and exception messages are excluded. See
+[`docs/CONFIGURATION.md`](docs/CONFIGURATION.md#logging) for the event and level
+details.
+
 Reconstruct and deliver a single persisted event JSON file through Mammoth's
 core delivery path:
 
@@ -292,8 +318,10 @@ production:
 - observability snapshots
 - DLQ replay
 
-The historical numbers in [Benchmarks](https://github.com/kanutocd/mammoth/tree/main/docs/BENCHMARKS.md) are retained as a
-snapshot, not a universal performance claim. Re-run the scripts in
+The [reference snapshot](https://github.com/kanutocd/mammoth/blob/main/benchmark/results/20260724T104950Z/snapshot.md)
+records a full local run, its exact commands, environment, raw output, and
+interpretation. It is a reproducible baseline, not a universal performance
+claim. Re-run the scripts in
 [`benchmark/`](https://github.com/kanutocd/mammoth/tree/main/benchmark) on your own hardware when choosing
 `runtime.concurrency`, `destinations`, SQLite storage, scrape frequency, and
 DLQ replay expectations.

data/config/mammoth.example.yml

@@ -385,7 +385,11 @@ operational_state:
 
 observability:
   # Bind host for the optional health, readiness, and metrics server.
-  host: 0.0.0.0
+  #
+  # The endpoints do not authenticate clients and may expose operational
+  # details. Keep the loopback default unless a trusted network boundary or
+  # authenticated reverse proxy protects the listener.
+  host: 127.0.0.1
 
   # HTTP port for /healthz, /readyz, and /metrics.
   port: 9393
@@ -397,7 +401,8 @@ logging:
   #   Very chatty; useful while diagnosing delivery or replication behavior.
   #
   # info:
-  #   Recommended normal default.
+  #   Recommended normal default. Emits lifecycle, delivery, checkpoint, retry,
+  #   and dead-letter JSON records to stdout for container log collection.
   #
   # warn/error:
   #   Quieter production modes.

data/lib/mammoth/application.rb

@@ -12,7 +12,7 @@ module Mammoth
   # rubocop:disable Metrics/ClassLength
   class Application
     attr_reader :config, :state_adapter, :consumer, :delivery_worker, :checkpoint_store, :lifecycle_hooks, :observer,
-                :progress_coordinator
+                :progress_coordinator, :logger
 
     # @param config [Mammoth::Configuration] loaded configuration
     # @param source [#each, nil] injectable event source for tests and demos
@@ -21,9 +21,11 @@ module Mammoth
     # @param sleeper [#call] retry sleep strategy
     # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
     # @param observer [CDC::Core::Observer, nil] dispatch lifecycle observer
+    # @param logger [Mammoth::Logging::Logger, nil] structured operational logger
     def initialize(config, source: nil, sink: nil, state_adapter: nil, sleeper: Kernel.method(:sleep),
-                   lifecycle_hooks: LifecycleHooks.new, observer: nil)
+                   lifecycle_hooks: LifecycleHooks.new, observer: nil, logger: nil)
       @config = config
+      @logger = logger || Logging.build(config)
       @lifecycle_hooks = build_lifecycle_hooks(lifecycle_hooks)
       @observer = observer || MetricsObserver.new
       @state_adapter = state_adapter || build_state_adapter
@@ -49,22 +51,37 @@ module Mammoth
     # Start the application runtime and deliver consumed CDC work.
     #
     # @return [Integer] number of processed work units
+    # rubocop:disable Metrics/AbcSize
     def start
       runtime = build_runtime
       processed = nil
 
+      operational_logger.info("application_started", mammoth_name: config&.dig("mammoth", "name"),
+                                                     runtime: config&.dig("runtime", "adapter"),
+                                                     delivery_unit: config&.dig("delivery", "unit"))
       lifecycle_hooks.call(:before_start, application_context(runtime: runtime))
       processed = process_consumer(runtime)
       lifecycle_hooks.call(:after_start, application_context(runtime: runtime, processed: processed))
+      operational_logger.info("application_completed", mammoth_name: config&.dig("mammoth", "name"), processed:)
       processed
+    rescue StandardError => e
+      operational_logger.error("application_failed", mammoth_name: config&.dig("mammoth", "name"),
+                                                     error_class: e.class.name)
+      raise
     ensure
       lifecycle_hooks.call(:before_shutdown, application_context(runtime: runtime, processed: processed))
       runtime.shutdown if runtime.respond_to?(:shutdown)
       lifecycle_hooks.call(:after_shutdown, application_context(runtime: runtime, processed: processed))
+      operational_logger.info("application_stopped", mammoth_name: config&.dig("mammoth", "name"), processed:)
     end
+    # rubocop:enable Metrics/AbcSize
 
     private
 
+    def operational_logger
+      logger || Logging::NullLogger::INSTANCE
+    end
+
     def build_lifecycle_hooks(hooks)
       return hooks if hooks.is_a?(LifecycleHooks)
 
@@ -84,6 +101,7 @@ module Mammoth
       processed = 0
 
       consumer.start_with_boundaries do |work, group_end|
+        operational_logger.debug("work_received", work_type: work.class.name, work_id: work_identifier(work), group_end:)
         progress_coordinator.register(work, group_end:)
         process_work(runtime, work)
         processed += 1
@@ -94,6 +112,13 @@ module Mammoth
       processed
     end
 
+    def work_identifier(work)
+      return work.transaction_id if work.respond_to?(:transaction_id)
+      return work.event_id if work.respond_to?(:event_id)
+
+      nil
+    end
+
     def process_work(runtime, work)
       runtime.process(work)
     end
@@ -115,7 +140,7 @@ module Mammoth
     end
 
     def build_source
-      Sources::Postgres.new(config, checkpoint_store: checkpoint_store)
+      Sources::Postgres.new(config, checkpoint_store: checkpoint_store, logger: logger)
     end
 
     def build_progress_coordinator
@@ -125,7 +150,8 @@ module Mammoth
         slot_name: config.dig("replication", "slot"),
         publication_name: Array(config.dig("replication", "publications")).join(","),
         acknowledger: source_acknowledger,
-        position_resolver: source_position_resolver
+        position_resolver: source_position_resolver,
+        logger: logger
       )
     end
 
@@ -147,7 +173,8 @@ module Mammoth
         dead_letter_store: state_adapter.dead_letter_store,
         delivered_envelope_store: state_adapter.delivered_envelope_store,
         sleeper: sleeper,
-        delivery_policy: delivery_policy
+        delivery_policy: delivery_policy,
+        logger: logger
       )
     end
 

data/lib/mammoth/cli.rb

@@ -109,7 +109,7 @@ module Mammoth
     def observability
       config = load_config
       server = ObservabilityServer.new(config)
-      puts "Mammoth observability listening on #{server.host}:#{server.port}"
+      Logging.build(config).info("observability_started", host: server.host, port: server.port)
       server.start
       0
     end

data/lib/mammoth/delivery_progress_coordinator.rb

@@ -36,7 +36,7 @@ module Mammoth
       end
     end
 
-    attr_reader :checkpoint_store, :source_name, :slot_name, :publication_name
+    attr_reader :checkpoint_store, :source_name, :slot_name, :publication_name, :logger
 
     # @param checkpoint_store [Mammoth::CheckpointStore] durable checkpoint persistence
     # @param source_name [String] logical source name
@@ -45,13 +45,14 @@ module Mammoth
     # @param acknowledger [#call, nil] upstream durable-progress acknowledgement
     # @param position_resolver [#call, nil] source-owned durable position resolver
     def initialize(checkpoint_store:, source_name:, slot_name:, publication_name:, acknowledger: nil,
-                   position_resolver: nil)
+                   position_resolver: nil, logger: Logging::NullLogger::INSTANCE)
       @checkpoint_store = checkpoint_store
       @source_name = source_name
       @slot_name = slot_name
       @publication_name = publication_name
       @acknowledger = acknowledger
       @position_resolver = position_resolver
+      @logger = logger
       # rubocop:disable Layout/LeadingCommentSpace -- Steep inline type syntax requires `#:`.
       @groups = [] #: Array[Group]
       @entries_by_work = {} #: Hash[untyped, Array[Entry]]
@@ -133,6 +134,8 @@ module Mammoth
         last_lsn: position
       )
       @acknowledger&.call(position)
+      logger.info("checkpoint_advanced", mammoth_name: source_name, slot: slot_name, publication: publication_name,
+                                         source_position: position)
     end
 
     def remove_group(group)

data/lib/mammoth/delivery_worker.rb

@@ -7,12 +7,12 @@ module Mammoth
   # the delivery contract small: attempt webhook delivery, record idempotent
   # success, and persist exhausted failures to the dead letter queue. Contiguous
   # checkpointing is owned by DeliveryProgressCoordinator.
-  class DeliveryWorker
+  class DeliveryWorker # rubocop:disable Metrics/ClassLength
     # Default source name used when an event does not provide one.
     DEFAULT_SOURCE = "postgresql"
 
     attr_reader :sink, :checkpoint_store, :dead_letter_store, :delivered_envelope_store, :retry_schedule, :max_attempts,
-                :sleeper, :source_name, :slot_name, :publication_name, :route_filter, :payload_policy, :enabled
+                :sleeper, :source_name, :slot_name, :publication_name, :route_filter, :payload_policy, :enabled, :logger
 
     # @param sink [#deliver] destination sink
     # @param checkpoint_store [Mammoth::CheckpointStore] retained dependency; shared progress owns writes
@@ -29,7 +29,7 @@ module Mammoth
     # @param enabled [Boolean] whether this destination accepts new deliveries
     def initialize(sink:, checkpoint_store:, dead_letter_store:, delivered_envelope_store:, source_name:, slot_name:,
                    publication_name:, max_attempts:, retry_schedule:, sleeper: Kernel.method(:sleep),
-                   route_filter: nil, payload_policy: nil, enabled: true)
+                   route_filter: nil, payload_policy: nil, enabled: true, logger: Logging::NullLogger::INSTANCE)
       @sink = sink
       @checkpoint_store = checkpoint_store
       @dead_letter_store = dead_letter_store
@@ -43,6 +43,7 @@ module Mammoth
       @route_filter = route_filter || RouteFilter.new
       @payload_policy = payload_policy || PayloadPolicy.new
       @enabled = enabled
+      @logger = logger
       return unless @payload_policy.active? && !sink.respond_to?(:deliver_payload)
 
       raise ConfigurationError, "destination #{destination_name} does not accept prepared payloads"
@@ -58,7 +59,7 @@ module Mammoth
     # @param sleeper [#call] sleep strategy
     # @return [Mammoth::DeliveryWorker]
     def self.from_config(config, sink:, checkpoint_store:, dead_letter_store:, delivered_envelope_store:,
-                         sleeper: Kernel.method(:sleep), delivery_policy: {})
+                         sleeper: Kernel.method(:sleep), delivery_policy: {}, logger: Logging::NullLogger::INSTANCE)
       new(
         sink: sink,
         checkpoint_store: checkpoint_store,
@@ -72,7 +73,8 @@ module Mammoth
         sleeper: sleeper,
         route_filter: delivery_policy.fetch("route_filter", RouteFilter.new),
         payload_policy: delivery_policy.fetch("payload_policy", PayloadPolicy.new),
-        enabled: delivery_policy.fetch("enabled", true)
+        enabled: delivery_policy.fetch("enabled", true),
+        logger: logger
       )
     end
 
@@ -109,7 +111,7 @@ module Mammoth
       deliver_prepared(prepared, work: work, delivery_method: delivery_method)
     end
 
-    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def deliver_prepared(prepared, work:, delivery_method:)
       attempts = 0
       canonical_payload = prepared.canonical_payload
@@ -118,16 +120,21 @@ module Mammoth
       idempotency_key = idempotency_key_for(payload: canonical_payload, delivery_unit: delivery_unit)
 
       skip_result = skip_result_for(canonical_payload, idempotency_key: idempotency_key)
-      return skip_result if skip_result
+      if skip_result
+        log_outcome("delivery_skipped", skip_result, delivery_unit:)
+        return skip_result
+      end
 
       if delivered_envelope_store.delivered?(idempotency_key)
-        return {
+        result = {
           status: "skipped",
           duplicate: true,
           idempotency_key: idempotency_key,
           attempts: attempts,
           destination: destination_name
         }
+        log_outcome("delivery_skipped", result, delivery_unit:)
+        return result
       end
 
       begin
@@ -142,15 +149,19 @@ module Mammoth
           transaction_id: payload["transaction_id"],
           source_position: payload["source_position"]
         )
-        result.merge(attempts: attempts, idempotency_key: idempotency_key)
+        result = result.merge(attempts: attempts, idempotency_key: idempotency_key)
+        log_outcome("delivery_succeeded", result, delivery_unit:)
+        result
       rescue DeliveryError => e
         return dead_letter(payload, e, attempts) if attempts >= max_attempts
 
-        wait_before_retry(attempts)
+        wait_seconds = wait_before_retry(attempts)
+        logger.warn("delivery_retry", destination: destination_name, delivery_unit:, attempt: attempts,
+                                      wait_seconds:, error_class: e.class.name)
         retry
       end
     end
-    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def idempotency_key_for(payload:, delivery_unit:)
       [
@@ -191,6 +202,7 @@ module Mammoth
     def wait_before_retry(attempts)
       wait_seconds = retry_schedule.fetch(attempts - 1, retry_schedule.last)
       sleeper.call(wait_seconds)
+      wait_seconds
     end
 
     def deliver_to_sink(prepared, work:, delivery_method:)
@@ -207,9 +219,18 @@ module Mammoth
         error: error,
         retry_count: attempts
       )
+      logger.error(
+        "delivery_dead_lettered",
+        destination: destination_name, attempts:, dead_letter_id: id, error_class: error.class.name
+      )
       { status: "dead_lettered", dead_letter_id: id, attempts: attempts }
     end
 
+    def log_outcome(event, result, delivery_unit:)
+      logger.info(event, destination: destination_name, delivery_unit:, status: result[:status],
+                         attempts: result[:attempts], reason: result[:reason], duplicate: result[:duplicate])
+    end
+
     def transaction_payload?(payload)
       payload["type"] == TransactionEnvelopeSerializer::PAYLOAD_TYPE
     end

data/lib/mammoth/logging.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Mammoth
+  # Container-friendly structured application logging.
+  module Logging
+    LEVELS = { "debug" => 0, "info" => 1, "warn" => 2, "error" => 3 }.freeze
+
+    # Logger that emits one JSON object per line.
+    class Logger
+      attr_reader :level, :output, :clock
+
+      def initialize(level:, output: $stdout, clock: -> { Time.now.utc })
+        @level = level.to_s
+        @output = output
+        @clock = clock
+        raise ConfigurationError, "unsupported logging level: #{@level}" unless LEVELS.key?(@level)
+      end
+
+      def debug(event, **context) = write("debug", event, context)
+      def info(event, **context) = write("info", event, context)
+      def warn(event, **context) = write("warn", event, context)
+      def error(event, **context) = write("error", event, context)
+
+      def enabled?(severity)
+        LEVELS.fetch(severity.to_s) >= LEVELS.fetch(level)
+      end
+
+      private
+
+      def write(severity, event, context)
+        return false unless enabled?(severity)
+
+        output.puts JSON.generate(
+          { timestamp: clock.call.utc.iso8601(6), severity:, service: "mammoth", event: }.merge(context.compact)
+        )
+        true
+      end
+    end
+
+    # No-op logger used at injectable library boundaries.
+    class NullLogger
+      INSTANCE = new
+
+      def debug(_event, **_context) = false
+      def info(_event, **_context) = false
+      def warn(_event, **_context) = false
+      def error(_event, **_context) = false
+      def enabled?(_severity) = false
+    end
+
+    module_function
+
+    def build(config, output: $stdout, clock: -> { Time.now.utc })
+      Logger.new(level: config.dig("logging", "level") || "info", output:, clock:)
+    end
+  end
+end

data/lib/mammoth/observability_server.rb

@@ -11,7 +11,7 @@ module Mammoth
   # the same configured operational-state backend.
   class ObservabilityServer
     # Default bind host for the observability server.
-    DEFAULT_HOST = "0.0.0.0"
+    DEFAULT_HOST = "127.0.0.1"
     # Default TCP port for the observability server.
     DEFAULT_PORT = 9393
 
@@ -29,7 +29,7 @@ module Mammoth
       @port = port || config.dig("observability", "port") || DEFAULT_PORT
       @state_adapter = state_adapter || OperationalState::Registry.build_configured(config)
       @slot_health_provider = slot_health_provider || Sources::Postgres.new(config)
-      @logger = logger || WEBrick::Log.new($stderr, WEBrick::Log::WARN)
+      @logger = logger || WEBrick::Log.new($stdout, webrick_log_level)
       @server = build_server
       mount_endpoints
     end
@@ -50,6 +50,15 @@ module Mammoth
 
     private
 
+    def webrick_log_level
+      {
+        "debug" => WEBrick::Log::DEBUG,
+        "info" => WEBrick::Log::INFO,
+        "warn" => WEBrick::Log::WARN,
+        "error" => WEBrick::Log::ERROR
+      }.fetch(config.dig("logging", "level") || "info")
+    end
+
     def build_server
       WEBrick::HTTPServer.new(
         BindAddress: host,

data/lib/mammoth/sources/postgres.rb

@@ -29,6 +29,8 @@ module Mammoth
       attr_reader :checkpoint_store
       # @return [#inspect, nil] injected PostgreSQL publication inspector
       attr_reader :publication_inspector
+      # @return [Mammoth::Logging::Logger, Mammoth::Logging::NullLogger] operational logger
+      attr_reader :logger
 
       # Build a PostgreSQL CDC source.
       #
@@ -40,7 +42,7 @@ module Mammoth
       # @param checkpoint_store [Mammoth::CheckpointStore, nil] persisted checkpoints for restart resume
       # @param publication_inspector [#inspect, nil] injected publication metadata inspector
       def initialize(config, runner: nil, parser: nil, decoder: nil, adapter: nil, checkpoint_store: nil,
-                     publication_inspector: nil)
+                     publication_inspector: nil, logger: Logging::NullLogger::INSTANCE)
         @config = config
         @runner = runner
         @parser = parser
@@ -48,6 +50,7 @@ module Mammoth
         @adapter = adapter
         @checkpoint_store = checkpoint_store
         @publication_inspector = publication_inspector
+        @logger = logger
       end
 
       # Stream CDC::Core work from PostgreSQL logical replication.
@@ -61,9 +64,12 @@ module Mammoth
       # @yieldparam work [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]
       # @return [Enumerator, nil]
       # @raise [Mammoth::ReplicationError] when the source cannot stream CDC work
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       def each(&block)
         return enum_for(:each) unless block_given?
 
+        logger.info("replication_starting", slot: config.dig("replication", "slot"),
+                                            publications: Array(config.dig("replication", "publications")))
         preflight_slot!
         preflight_replica_identity!
         normalizer = effective_adapter
@@ -72,22 +78,29 @@ module Mammoth
         end
 
         normalizer.each_normalized(decoded_stream) do |work|
-          yield_with_progress_position(validate_core_work!(work), &block)
+          core_work = validate_core_work!(work)
+          logger.debug("replication_work_normalized", work_type: core_work.class.name,
+                                                      source_position: @latest_progress_position)
+          yield_with_progress_position(core_work, &block)
         end
+        logger.info("replication_stopped", slot: config.dig("replication", "slot"))
         nil
       rescue StandardError => e
+        logger.error("replication_failed", slot: config.dig("replication", "slot"), error_class: e.class.name)
         raise e if e.is_a?(ReplicationError)
 
         raise ReplicationError, "PostgreSQL CDC source failed: #{e.message}"
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # Acknowledge a durably handled PostgreSQL WAL position.
       #
       # @param lsn [String, Integer] pgoutput-client compatible WAL position
       # @return [Integer] normalized acknowledged WAL position
       def acknowledge(lsn)
-        effective_runner.ack(lsn)
+        effective_runner.ack(lsn).tap { logger.debug("wal_acknowledged", slot: config.dig("replication", "slot"), lsn:) }
       rescue StandardError => e
+        logger.error("wal_acknowledgement_failed", slot: config.dig("replication", "slot"), error_class: e.class.name)
         raise ReplicationError, "PostgreSQL WAL acknowledgement failed: #{e.message}"
       end
 

data/lib/mammoth/version.rb

@@ -2,5 +2,5 @@
 
 module Mammoth
   # Current Mammoth gem version.
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

data/lib/mammoth.rb

@@ -6,6 +6,7 @@ require_relative "mammoth/version"
 require_relative "mammoth/errors"
 require_relative "mammoth/registry"
 require_relative "mammoth/configuration"
+require_relative "mammoth/logging"
 require_relative "mammoth/lifecycle_hooks"
 require_relative "mammoth/node_identity"
 require_relative "mammoth/capabilities"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -37,6 +37,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.19.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.19.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: json-schema
   requirement: !ruby/object:Gem::Requirement
@@ -211,6 +231,7 @@ files:
 - lib/mammoth/event_serializer.rb
 - lib/mammoth/fanout_delivery_worker.rb
 - lib/mammoth/lifecycle_hooks.rb
+- lib/mammoth/logging.rb
 - lib/mammoth/metrics_observer.rb
 - lib/mammoth/node_identity.rb
 - lib/mammoth/observability_metrics.rb