mammoth 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d7d570675d2b6731d783c6eba0f347ab00c1d7f9e524c20eef4908af129c41a
-  data.tar.gz: f14c3223b20cd1ea8e7d795e1cd2fe4e512766a0a4ed275515e4d1174bb3d6f5
+  metadata.gz: 8fdbb7afb90f584e11024c75d7300f54978f5e5b1a3628597bb460f96a306c22
+  data.tar.gz: 9ced2250d7e2f95558a8bcce51809aa4d670d49953d8d970e168a0c48cf90215
 SHA512:
-  metadata.gz: cf649aba9068bdc1c3b0e01c1254f8f16804e80ec88de725d2743e99be9b9010bd880590fde044c9d7dff3b0b99fac54c6c9776af4504fb566eeceb1e5b00fd9
-  data.tar.gz: a7396f91f4fe84b3780f9b176931d728707b6e55ecab9b168b5eb3e87cb384c2066d9ed0b944dd14405d2e06a02e0e363a28348325578bb652aa4ba1df56caee
+  metadata.gz: cd6b5b3246cf70adb9beb0cc9243e6a35788d20f3442ab406bca66a4cb08bd4a7d80639386c4e42291b518190a0198f960ed9e16cbd165f335a7f3fee10317b7
+  data.tar.gz: 87aa4ee77c38aa69d1a505bf7eb2b838de86504316840dfc26b4e875870333f64da906c85aa180a205e5e3bff4f439e36d2f82ffa79d650117d9f5ccc4c29b69

data/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## Unreleased
 
-## 0.3.0
+## 0.4.0
+
+### Added
+
+- Added optional observability support with `/healthz`, `/readyz`, and `/metrics` endpoints, plus CLI startup, configuration, and documentation coverage.
+
+## 0.4.0
 
 ### Added
 

data/README.md

@@ -53,6 +53,7 @@ https://kanutocd.github.io/mammoth/Mammoth.html
 - Docker image support
 - public Helm chart support
 - unit and e2e test tasks
+- Health and metrics endpoints
 
 ## Boundary
 
@@ -84,6 +85,7 @@ bundle exec ./exe/mammoth validate config/mammoth.example.yml
 bundle exec ./exe/mammoth bootstrap config/mammoth.example.yml
 bundle exec ./exe/mammoth status config/mammoth.example.yml
 bundle exec ./exe/mammoth start config/mammoth.example.yml
+bundle exec ./exe/mammoth observability config/mammoth.example.yml
 ```
 
 Deliver a single normalized event JSON file through Mammoth's delivery path:

data/config/mammoth.example.yml

@@ -274,6 +274,13 @@ sqlite:
   # In Kubernetes, back this path with a PersistentVolumeClaim.
   path: data/mammoth.db
 
+observability:
+  # Bind host for the optional health, readiness, and metrics server.
+  host: 0.0.0.0
+
+  # HTTP port for /healthz, /readyz, and /metrics.
+  port: 9393
+
 logging:
   # Log verbosity.
   #

data/config/mammoth.schema.json

@@ -319,6 +319,24 @@
         }
       },
       "description": "Downstream delivery runtime settings. Runtime concurrency affects webhook/destination delivery only, not PostgreSQL replication stream count."
+    },
+    "observability": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "host": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Bind host for the optional Mammoth observability HTTP server exposing /healthz, /readyz, and /metrics."
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535,
+          "description": "TCP port for the optional Mammoth observability HTTP server."
+        }
+      },
+      "description": "Optional health, readiness, and metrics endpoint settings."
     }
   },
   "description": "Mammoth relay configuration. Mammoth consumes PostgreSQL logical replication changes and delivers them to downstream destinations while preserving checkpoint, retry, and dead-letter semantics."

data/lib/mammoth/cli.rb

@@ -26,7 +26,8 @@ module Mammoth
       "  mammoth deliver-sample CONFIG EVENT_JSON",
       "  mammoth dead-letters list CONFIG [--status STATUS] [--limit N]",
       "  mammoth dead-letters show CONFIG ID",
-      "  mammoth dead-letters replay CONFIG [ID ...]"
+      "  mammoth dead-letters replay CONFIG [ID ...]",
+      "  mammoth observability CONFIG"
     ].join("\n")
 
     # Run the CLI.
@@ -56,6 +57,7 @@ module Mammoth
       when "start" then start
       when "deliver-sample" then deliver_sample
       when "dead-letters" then dead_letters
+      when "observability" then observability
       else
         warn USAGE
         1
@@ -130,6 +132,14 @@ module Mammoth
       DeadLetterCommands.call(argv)
     end
 
+    def observability
+      config = load_config
+      server = ObservabilityServer.new(config)
+      puts "Mammoth observability listening on #{server.host}:#{server.port}"
+      server.start
+      0
+    end
+
     def load_config
       raise ConfigurationError, "configuration path required\n#{USAGE}" unless config_path
 

data/lib/mammoth/observability_server.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "webrick"
+
+module Mammoth
+  # Small HTTP server exposing Mammoth health, readiness, and metrics endpoints.
+  #
+  # The server is intentionally independent from the replication loop. Operators
+  # may run it as a sidecar-like process or in a separate process that points at
+  # the same SQLite operational database.
+  class ObservabilityServer
+    DEFAULT_HOST = "0.0.0.0"
+    DEFAULT_PORT = 9393
+
+    attr_reader :config, :host, :port, :sqlite_store, :logger, :server
+
+    # @param config [Mammoth::Configuration] loaded configuration
+    # @param host [String, nil] bind host override
+    # @param port [Integer, nil] bind port override
+    # @param sqlite_store [Mammoth::SQLiteStore, nil] optional operational store
+    # @param logger [WEBrick::Log, nil] optional WEBrick logger
+    def initialize(config, host: nil, port: nil, sqlite_store: nil, logger: nil)
+      @config = config
+      @host = host || config.dig("observability", "host") || DEFAULT_HOST
+      @port = port || config.dig("observability", "port") || DEFAULT_PORT
+      @sqlite_store = sqlite_store
+      @logger = logger || WEBrick::Log.new($stderr, WEBrick::Log::WARN)
+      @server = build_server
+      mount_endpoints
+    end
+
+    # Start the blocking HTTP server.
+    #
+    # @return [void]
+    def start
+      server.start
+    end
+
+    # Stop the HTTP server.
+    #
+    # @return [void]
+    def shutdown
+      server.shutdown
+    end
+
+    private
+
+    def build_server
+      WEBrick::HTTPServer.new(
+        BindAddress: host,
+        Port: port,
+        Logger: logger,
+        AccessLog: []
+      )
+    end
+
+    def mount_endpoints
+      server.mount_proc("/healthz") { |_request, response| write_json(response, snapshot.health, status: 200) }
+      server.mount_proc("/readyz") { |_request, response| write_readiness(response) }
+      server.mount_proc("/metrics") { |_request, response| write_metrics(response) }
+    end
+
+    def write_readiness(response)
+      payload = snapshot.readiness
+      write_json(response, payload, status: payload.fetch(:status) == "ready" ? 200 : 503)
+    end
+
+    def write_metrics(response)
+      response.status = 200
+      response["Content-Type"] = "text/plain; version=0.0.4; charset=utf-8"
+      response.body = snapshot.prometheus
+    end
+
+    def write_json(response, payload, status:)
+      response.status = status
+      response["Content-Type"] = "application/json"
+      response.body = JSON.generate(payload)
+    end
+
+    def snapshot
+      ObservabilitySnapshot.new(config, sqlite_store: sqlite_store)
+    end
+  end
+end

data/lib/mammoth/observability_snapshot.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Mammoth
+  # Builds health, readiness, and metrics snapshots from Mammoth's local
+  # operational state.
+  #
+  # ObservabilitySnapshot is intentionally read-only. It does not start the
+  # relay, mutate checkpoints, replay dead letters, or inspect PostgreSQL. The
+  # health and metrics endpoints use this object to expose Mammoth process and
+  # SQLite operational-state status in a predictable format.
+  class ObservabilitySnapshot
+    attr_reader :config, :sqlite_store, :clock
+
+    # @param config [Mammoth::Configuration] loaded configuration
+    # @param sqlite_store [Mammoth::SQLiteStore, nil] optional operational store
+    # @param clock [#call] time source returning a Time-like object
+    def initialize(config, sqlite_store: nil, clock: -> { Time.now.utc })
+      @config = config
+      @sqlite_store = sqlite_store
+      @clock = clock
+    end
+
+    # Build a liveness response.
+    #
+    # @return [Hash] health payload
+    def health
+      {
+        status: "ok",
+        service: "mammoth",
+        name: mammoth_name,
+        version: Mammoth::VERSION,
+        checked_at: checked_at
+      }
+    end
+
+    # Build a readiness response.
+    #
+    # @return [Hash] readiness payload
+    def readiness
+      store = operational_store
+      store.bootstrap!
+
+      {
+        status: "ready",
+        service: "mammoth",
+        name: mammoth_name,
+        sqlite: "ok",
+        tables: store.tables,
+        checked_at: checked_at
+      }
+    rescue Mammoth::Error, SQLite3::Exception => e
+      {
+        status: "unready",
+        service: "mammoth",
+        name: mammoth_name,
+        sqlite: "error",
+        error_class: e.class.name,
+        error_message: e.message,
+        checked_at: checked_at
+      }
+    end
+
+    # Build a Prometheus text exposition document.
+    #
+    # @return [String] Prometheus metrics text
+    def prometheus
+      store = operational_store.bootstrap!
+      checkpoint_store = CheckpointStore.new(store)
+      dead_letter_store = DeadLetterStore.new(store)
+      delivered_store = DeliveredEnvelopeStore.new(store)
+
+      lines = metric_headers + [
+        metric_line("mammoth_up", 1),
+        metric_line("mammoth_checkpoints_total", checkpoint_store.count),
+        metric_line("mammoth_dead_letters_total", dead_letter_store.count),
+        metric_line("mammoth_dead_letters_pending_total", dead_letter_store.count(status: "pending")),
+        metric_line("mammoth_dead_letters_resolved_total", dead_letter_store.count(status: "resolved")),
+        metric_line("mammoth_dead_letters_ignored_total", dead_letter_store.count(status: "ignored")),
+        metric_line("mammoth_delivered_envelopes_total", delivered_store.count)
+      ]
+      "#{lines.join("\n")}\n"
+    rescue Mammoth::Error, SQLite3::Exception
+      "#{(metric_headers + [metric_line("mammoth_up", 0)]).join("\n")}\n"
+    end
+
+    private
+
+    def operational_store
+      sqlite_store || SQLiteStore.connect(config.dig("sqlite", "path"))
+    end
+
+    def mammoth_name
+      config.dig("mammoth", "name")
+    end
+
+    def checked_at
+      clock.call.utc.iso8601
+    end
+
+    def metric_headers
+      [
+        "# HELP mammoth_up 1 when Mammoth operational state can be inspected, 0 otherwise.",
+        "# TYPE mammoth_up gauge",
+        "# HELP mammoth_checkpoints_total Number of checkpoint rows stored by Mammoth.",
+        "# TYPE mammoth_checkpoints_total gauge",
+        "# HELP mammoth_dead_letters_total Number of dead-letter rows stored by Mammoth.",
+        "# TYPE mammoth_dead_letters_total gauge",
+        "# HELP mammoth_dead_letters_pending_total Number of pending dead-letter rows.",
+        "# TYPE mammoth_dead_letters_pending_total gauge",
+        "# HELP mammoth_dead_letters_resolved_total Number of resolved dead-letter rows.",
+        "# TYPE mammoth_dead_letters_resolved_total gauge",
+        "# HELP mammoth_dead_letters_ignored_total Number of ignored dead-letter rows.",
+        "# TYPE mammoth_dead_letters_ignored_total gauge",
+        "# HELP mammoth_delivered_envelopes_total Number of delivered-envelope ledger rows.",
+        "# TYPE mammoth_delivered_envelopes_total gauge"
+      ]
+    end
+
+    def metric_line(name, value)
+      %(#{name}{mammoth_name="#{escape_label(mammoth_name)}"} #{Integer(value)})
+    end
+
+    def escape_label(value)
+      value.to_s.gsub("\\", "\\\\").gsub('"', '\\"').gsub("\n", "\\n")
+    end
+  end
+end

data/lib/mammoth/version.rb

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

data/lib/mammoth.rb

@@ -4,6 +4,8 @@ require_relative "mammoth/version"
 require_relative "mammoth/errors"
 require_relative "mammoth/configuration"
 require_relative "mammoth/status"
+require_relative "mammoth/observability_snapshot"
+require_relative "mammoth/observability_server"
 require_relative "mammoth/sqlite_store"
 require_relative "mammoth/checkpoint_store"
 require_relative "mammoth/dead_letter_store"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -157,6 +157,8 @@ files:
 - lib/mammoth/delivery_worker.rb
 - lib/mammoth/errors.rb
 - lib/mammoth/event_serializer.rb
+- lib/mammoth/observability_server.rb
+- lib/mammoth/observability_snapshot.rb
 - lib/mammoth/replication_consumer.rb
 - lib/mammoth/sources/postgres.rb
 - lib/mammoth/sql/__bootstrap__.sql