mammoth 1.4.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55bd93a58c383e07fe1930ed71f20ea52c05dbfa77a2354e258caddd726865ce
-  data.tar.gz: 2b01106f391f82ed0079d7efdf934447cdeb168d2ee5d6029fb8ac7cd8a617b8
+  metadata.gz: 3d7fd1f170a51138c5f3f1b8cc31c388428dd9052020f38653242c774bc6a92e
+  data.tar.gz: 134f6734ff5a1c377ba318a924630f6792dd51f66b0510ca37157836caacc993
 SHA512:
-  metadata.gz: 4359b50a25fada22578bca1ab80c3afcc187ce6d181110d83157d7231bdc9fb5f32ab407b24d39619cd7e63fa8d4a4fc01c14fd27474f640d53c874c5411eff8
-  data.tar.gz: 62eb55bba9825caaf491f8ed38ceb9f3da95580a57736c6998bb2349fa1980eb472e2ce7c775972ce7d7d9f8d6fa1ad43daffb22da7847b03c6b898c02e25762
+  metadata.gz: 7421871882b9288892ee4c3c2e3e0701839dd60165b238b771a98cd2ec21aa0ed1323b4605ce1f1c9270cd711430aae97f61b0e5f7edd5316a6b77a8686e1f39
+  data.tar.gz: 6b9d480c5c71beadbbf2633597e6af88176764b1a8e44e49b41cfa24c4636e0f14a08287f2522ce8bf885b0b7b95930600836697cd66acefb67452e5e2c3f2b5

data/CHANGELOG.md

@@ -4,6 +4,42 @@
 
 # Changelog
 
+## Unreleased
+
+## 1.5.1 - 2026-07-25
+
+### Changed
+
+- Adopt Mammoth as the ecosystem brand, identify this open-source project as
+  Mammoth Data Plane, and align documentation, published gem metadata,
+  configuration descriptions, and branding assets with the new hierarchy.
+
+## 1.5.0 - 2026-07-24
+
+### 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)
 
@@ -24,6 +25,17 @@
 Mammoth is a self-hosted PostgreSQL event relay focused on reliable delivery
 of database change events.
 
+This repository contains the **Mammoth Data Plane**, the open-source runtime in
+the broader Mammoth ecosystem:
+
+```text
+Mammoth
+├── Mammoth Data Plane
+├── Mammoth Control Plane
+├── Mammoth Control Agent
+└── Mammoth Extensions
+```
+
 ```text
 PostgreSQL
       ↓
@@ -31,7 +43,7 @@ CDC Ecosystem source adapter
       ↓
 CDC::Core::TransactionEnvelope
       ↓
-Mammoth
+Mammoth Data Plane
       ↓
 Webhook fanout
 ```
@@ -106,6 +118,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
@@ -196,7 +209,7 @@ payload policy.
 
 ## Extensions
 
-Mammoth OSS exposes small adapter registries for future extensions:
+Mammoth Data Plane exposes small adapter registries for future extensions:
 
 - operational state adapters
 - destination adapters
@@ -257,6 +270,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:
 
@@ -281,22 +318,35 @@ rather than opening SQLite directly.
 
 ## Performance
 
-Mammoth includes local benchmarks for the product surfaces operators tune in
-production:
-
-- event and transaction serialization, including deterministic fallback IDs
-- concurrent delivery runtime
-- real webhook delivery
-- multi-destination webhook fanout
-- SQLite operational state
-- 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
-[`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.
+A reference benchmark run on Ruby 4.0.5 produced:
+
+| Benchmark                                           |                Result |
+| --------------------------------------------------- | --------------------: |
+| Event payload projection with explicit ID           | **56,265 events/sec** |
+| Transaction payload projection with explicit IDs    | **55,612 events/sec** |
+| Mask payload-policy projection                      | **72,403 events/sec** |
+| Concurrent delivery, 25 workers                     |  **3,825 events/sec** |
+| Concurrent delivery, 50 workers                     |  **7,447 events/sec** |
+| Signed webhook delivery with 10 ms receiver latency | **83.5 requests/sec** |
+| SQLite delivered-ledger writes                      |  **1,630 writes/sec** |
+| Dead-letter replay mechanics                        | **1,030 entries/sec** |
+
+At concurrency 50 with a synthetic 25 ms destination, Mammoth processed
+**1,862 transactions/sec** against a theoretical ceiling of 2,000, while
+maintaining **28.4 ms P95 latency**. This indicates low scheduling overhead for
+I/O-bound downstream delivery.
+
+These are local, single-trial reference measurements, not universal capacity
+claims or comparisons with other CDC platforms. The benchmarks isolate specific
+Mammoth components and may exclude PostgreSQL transport, decoding, checkpoint
+coordination, network latency, or destination processing.
+
+The [reference snapshot](https://github.com/kanutocd/mammoth/blob/main/benchmark/results/20260724T104950Z/snapshot.md)
+records the exact commands, environment, raw output, and detailed
+interpretation. Re-run the scripts in
+[`benchmark/`](https://github.com/kanutocd/mammoth/tree/main/benchmark)
+on your own hardware when choosing `runtime.concurrency`, destination count,
+SQLite storage, scrape frequency, and DLQ replay expectations.
 
 Create a publishable benchmark snapshot with:
 
@@ -352,4 +402,4 @@ building a writable database copy. See
 
 ## License
 
-Mammoth OSS is licensed under the [MIT License](LICENSE.txt).
+Mammoth OSS Data Plane is licensed under the [MIT License](LICENSE.txt).

data/config/mammoth.example.yml

@@ -380,12 +380,16 @@ sqlite:
   path: data/mammoth.db
 
 operational_state:
-  # Mammoth OSS 0.7.x ships the sqlite operational state adapter.
+  # Mammoth Data Plane 0.7.x ships the sqlite operational state adapter.
   adapter: sqlite
 
 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/config/mammoth.schema.json

@@ -158,7 +158,7 @@
           "description": "Operator-defined node metadata."
         }
       },
-      "description": "Optional local node identity. Mammoth OSS uses this for status and future extension surfaces only."
+      "description": "Optional local node identity. Mammoth Data Plane uses this for status and future extension surfaces only."
     },
     "postgres": {
       "type": "object",
@@ -346,7 +346,7 @@
             "enum": [
               "webhook"
             ],
-            "description": "Destination adapter type. Mammoth OSS 0.7.x supports webhook destinations."
+            "description": "Destination adapter type. Mammoth Data Plane 0.7.x supports webhook destinations."
           },
           "enabled": {
             "type": "boolean",
@@ -520,7 +520,7 @@
           "enum": [
             "sqlite"
           ],
-          "description": "Operational state adapter. Mammoth OSS 0.7.x ships the sqlite adapter."
+          "description": "Operational state adapter. Mammoth Data Plane 0.7.x ships the sqlite adapter."
         }
       },
       "description": "Operational state adapter selection. SQLite remains the default OSS adapter."

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/lifecycle_hooks.rb

@@ -7,6 +7,7 @@ module Mammoth
   # future control agents stable observation points without changing the data
   # plane or introducing remote behavior into OSS.
   class LifecycleHooks
+    # Supported lifecycle callback names.
     EVENTS = %i[
       before_start
       after_start
@@ -15,6 +16,8 @@ module Mammoth
       before_replay
       after_replay
     ].freeze
+
+    # Frozen empty callback list used for events without registrations.
     EMPTY_CALLBACKS = [nil].compact.freeze
 
     attr_reader :callbacks

data/lib/mammoth/logging.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Mammoth
+  # Container-friendly structured application logging.
+  module Logging
+    # Supported severity names mapped to their filtering priority.
+    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
+
+      # Emit a debug event when debug logging is enabled.
+      #
+      # @param event [String, Symbol] stable event name
+      # @param context [Hash] structured event fields
+      # @return [Boolean] whether the event was emitted
+      def debug(event, **context) = write("debug", event, context)
+
+      # Emit an informational event when info logging is enabled.
+      #
+      # @param event [String, Symbol] stable event name
+      # @param context [Hash] structured event fields
+      # @return [Boolean] whether the event was emitted
+      def info(event, **context) = write("info", event, context)
+
+      # Emit a warning event when warn logging is enabled.
+      #
+      # @param event [String, Symbol] stable event name
+      # @param context [Hash] structured event fields
+      # @return [Boolean] whether the event was emitted
+      def warn(event, **context) = write("warn", event, context)
+
+      # Emit an error event.
+      #
+      # @param event [String, Symbol] stable event name
+      # @param context [Hash] structured event fields
+      # @return [Boolean] whether the event was emitted
+      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
+      # Shared immutable no-op logger.
+      INSTANCE = new
+
+      # Suppress a debug event.
+      #
+      # @return [false]
+      def debug(_event, **_context) = false
+
+      # Suppress an informational event.
+      #
+      # @return [false]
+      def info(_event, **_context) = false
+
+      # Suppress a warning event.
+      #
+      # @return [false]
+      def warn(_event, **_context) = false
+
+      # Suppress an error event.
+      #
+      # @return [false]
+      def error(_event, **_context) = false
+
+      def enabled?(_severity) = false
+    end
+
+    module_function
+
+    # Build the configured structured logger.
+    #
+    # @param config [Mammoth::Configuration, Hash] loaded Mammoth configuration
+    # @param output [IO] destination for newline-delimited JSON
+    # @param clock [#call] UTC-compatible time source
+    # @return [Mammoth::Logging::Logger]
+    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/operational_state/sqlite_adapter.rb

@@ -2,7 +2,7 @@
 
 module Mammoth
   module OperationalState
-    # SQLite-backed operational state adapter used by Mammoth OSS.
+    # SQLite-backed operational state adapter used by Mammoth Data Plane.
     class SQLiteAdapter < Adapter
       attr_reader :sqlite_store
 

data/lib/mammoth/payload_policy.rb

@@ -10,8 +10,13 @@ module Mammoth
   # items. Column rules scrub every canonical row-value representation: data,
   # identity, and old/new values in changes.
   class PayloadPolicy
+    # Default replacement used by mask rules.
     DEFAULT_MASK = "[REDACTED]"
+
+    # Payload metadata key containing the applied policy fingerprint.
     POLICY_METADATA_KEY = "mammoth_payload_policy"
+
+    # Transformation actions accepted by payload-policy rules.
     SUPPORTED_ACTIONS = %w[remove mask].freeze
 
     attr_reader :config, :fingerprint

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/sources/postgres_publication_inspector.rb

@@ -70,6 +70,7 @@ module Mammoth
 
     # Read-only PostgreSQL publication and replica-identity catalog inspector.
     class PostgresPublicationInspector
+      # Catalog query used to inspect publication actions and replica identity.
       QUERY = <<~SQL
         SELECT
           relation.oid AS relation_id,

data/lib/mammoth/version.rb

@@ -2,5 +2,5 @@
 
 module Mammoth
   # Current Mammoth gem version.
-  VERSION = "1.4.0"
+  VERSION = "1.5.1"
 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.1
 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
@@ -162,14 +182,15 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.9'
 description: |
-  Mammoth is an OSS PostgreSQL change-event delivery appliance for Ruby.
+  Mammoth Data Plane is the open-source PostgreSQL change-event delivery
+  runtime in the Mammoth ecosystem.
 
   It realizes the CDC Ecosystem pgoutput and cdc-core libraries for PostgreSQL,
   then delivers normalized changes to webhook endpoints with durable
   checkpointing, retry state, dead letters, and operational visibility.
 
-  Mammoth is application-first: it can be installed as a Ruby gem, packaged
-  into a container image, or deployed into Kubernetes with Helm.
+  Mammoth Data Plane is application-first: it can be installed as a Ruby gem,
+  packaged into a container image, or deployed into Kubernetes with Helm.
 email:
 - kenneth.c.demanawa@gmail.com
 executables:
@@ -211,6 +232,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
@@ -265,6 +287,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Reliable delivery of PostgreSQL logical replication events with retries,
-  dead letters, and operational state.
+summary: Mammoth Data Plane for reliable PostgreSQL change-event delivery.
 test_files: []