mammoth 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03761ea16810e4f57a0029f8df6e9022545833671db797692fdea532a4824dc6
-  data.tar.gz: 40bde74258be786105aa85e728125a72d27158e870565ad41d493592a3761462
+  metadata.gz: 7d16f1b05d2ae82569933033416a20892ae7e7afc9cdd282aacd6343789157c3
+  data.tar.gz: 1af59d9757dd584f462c5a888246c73693459aff503f6ef775e24aa4c4d19b49
 SHA512:
-  metadata.gz: c107f0f46a2e7e9da588a0835de73851c0d87133967b99f15244b8b2b4867c1795a6cc73bf5005428819a59c76cf8f71fa3827083662ed1bfdb8f7df2b317256
-  data.tar.gz: 0f59b536c3b9fe2585c850935eeb68541e73ac59830fcbe3969ac10b7b8f90473acdae762d2de4d9f55b36a7aec8274004e50a329b5d06986371aa53bf2e51b0
+  metadata.gz: 14452ab3df0aaae412be115a33b25b20ae3ef9698146e2f0e00c38f0453245ea9abec2a1cdd93a6f780288e722fb982b3fa3f7ab7fafc0de979c19abccd9a74e
+  data.tar.gz: 39832167b4069a9b8b8b4bab5ad86f2a3a150449e216d41a4a915fc2e748b471d3361f183b088a7a990402515351d6bf7e3e19c5576a683dabdb463e6e508dce

data/CHANGELOG.md

@@ -1,7 +1,54 @@
+<!--
+# @title Changelog
+-->
+
 # 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
+
+- Declared PostgreSQL 14 through PostgreSQL 18, inclusive, as Mammoth's
+  supported server range.
+- Replaced the PostgreSQL 17-only CI gate with real logical-replication E2E
+  coverage across PostgreSQL 14, 15, 16, 17, and 18.
+- Documented the maintained-version support policy, version-dependent
+  `pg_replication_slots` fields, and PostgreSQL 18-only
+  `idle_replication_slot_timeout`.
+
+### Fixed
+
+- Query `pg_replication_slots.invalidation_reason` in the E2E helper only on
+  PostgreSQL 17 and newer; PostgreSQL 16 does not expose that field.
+
 ## 1.3.0 - 2026-07-19
 
 ### Added

data/README.md

@@ -1,3 +1,9 @@
+<!--
+# @markup markdown
+# @title Github Repo README
+# @author Ken C. Demanawa
+-->
+
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kanutocd/mammoth/main/docs/branding/logo/exports/png/mammoth-primary-horizontal-reversed-transparent.png">
@@ -8,10 +14,13 @@
 
 # Mammoth
 
-[![Gem Version](https://badge.fury.io/rb/mammoth.svg)](https://badge.fury.io/rb/mammoth)
-[![CI](https://github.com/kanutocd/mammoth/workflows/CI/badge.svg)](https://github.com/kanutocd/mammoth/actions)
-[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%204.0-ruby.svg)](https://www.ruby-lang.org/en/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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)
+
 
 Mammoth is a self-hosted PostgreSQL event relay focused on reliable delivery
 of database change events.
@@ -32,6 +41,20 @@ Mammoth is intentionally boring infrastructure. It uses YAML configuration,
 JSON Schema validation, local SQLite operational state, and the CDC Ecosystem's
 shared vocabulary so operators can inspect, recover, and reason about delivery.
 
+## Supported PostgreSQL versions
+
+Mammoth supports PostgreSQL 14 through PostgreSQL 18, inclusive. These are the
+PostgreSQL major versions currently maintained by the PostgreSQL community and
+covered by Mammoth's real logical-replication E2E compatibility matrix.
+
+Mammoth supports PostgreSQL major versions that are both maintained by the
+PostgreSQL community and included in Mammoth's compatibility test matrix. New
+PostgreSQL majors are unsupported until explicitly tested and documented. EOL
+versions may be removed from the supported range in a subsequent Mammoth minor
+release with release-note notice.
+
+PostgreSQL 19 is a development release and is not supported.
+
 ## Documentation
 
 Documentation site:
@@ -84,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
@@ -235,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:
 
@@ -270,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.3.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.3.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