pg_eventstore 3.0.1 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24899ca6d10bac21341f41f3a8cfee09e10ce10bf81fb4525e9660f6c708d3af
-  data.tar.gz: 07cbbca86a3cb488d9123d663e77cb66cdbf850f93e12f1f15e46dc8f465879c
+  metadata.gz: 9181ca6342afc352a02779065731ea21bb9e8ce6632b924a25342e9726e88f3c
+  data.tar.gz: 6c80c69802d7efcca8be4440d22f2dac1621f379cb710520d755335378a94725
 SHA512:
-  metadata.gz: bc33cc4bcdda545ffa4476e80b55ca2541de4da036d715644f3957d1889170bbdf3b05b1391c7f981f28163da0ce36d06b0a8282ddeddb7560eb1892df43cfaa
-  data.tar.gz: 64b63413791d2c993315d4012acb1a5bec19b237eae6761c6b9da8725483e4284f5fbf3b956df5c4a750719460087f30cec6c9db1f176ce728ad985f2aefa213
+  metadata.gz: a3d07d058fd23c8b6d19c09b2de3a5c600683205d6bd21df9a304dd0bc4e5428fd34f33dcbeea7cdd95415f8593fb99bac1801e1d08ce506c05b748d9f78ff78
+  data.tar.gz: c09027974c15266d0771c1375fbd7dedcc78841f7d36d9bb0c47f6f619b14922eb9d1561b9e1240a692c32aadef59d55ec3526479befab06e2c6c461e81d5680

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [3.1.1]
+
+- Prevent arbitrary order in replica queries
+
+## [3.1.0]
+
+- Hide "Delete stream" and "Delete" event buttons in admin UI for non-maintenance eventstore roles
+- New feature: Prometheus metrics endpoints for subscriptions observability (lag, health, throughput), served by the
+  standalone `PgEventstore::Web::Metrics::Application` rack application. Read more [here](docs/metrics.md)
+- Properly report internal errors via `failed_subscription_notifier` config option
+- Fix inaccuracy that could lead to mistakenly handle connection error as subscription handler error
+- Fix admin UI links to take into account mount path instead building a path from `'/'`
+
 ## [3.0.1]
 
 - Fix EventTracing bug: Respect user-supplied Event#correlation_id value when caused_by#correlation_id is absent
@@ -14,8 +27,10 @@
   middleware by default. Previously this wasn't the case - the deserialization phase was skipped. Such behavior was
   creating ambiguity about assumptions when deserialization happens. If you need old behavior - you have to create
   another middleware class which skips deserialization when publishing events and use it instead. Example:
-Let's say you have this middleware configured
+  Let's say you have this middleware configured
+
 ```ruby
+
 class MyMiddleware
   include PgEventstore::Middleware
 
@@ -36,9 +51,9 @@ end
 Now define another middleware that has empty `#deserialize` method
 
 ```ruby
+
 class MyMiddlewareWithoutDeserialize < MyMiddleware
-  def deserialize(event)
-  end
+  def deserialize(event) end
 end
 
 PgEventstore.configure do |config|
@@ -48,6 +63,7 @@ PgEventstore.configure do |config|
   }
 end
 ```
+
 and use only it when publishing events:
 
 ```ruby
@@ -76,12 +92,13 @@ PgEventstore.client(:write).append_to_stream(stream, event)
 - **Breaking change**: `Event#id` uniqueness is no longer guaranteed. It was dropped because there is not much usage of
   it internally. The default value was moved from the database(it was `gen_random_uuid()`) to the application level and
   is `SecureRandom.uuid_v7` now.
-- **Breaking change**: event types, stream attributes, event metadata keys, markers that start from `▒`(`"\u2592"` 
-Unicode character) character are now reserved by pg_eventstore. It is less likely you have any, but if you do - you have
-to adjust your implementation to no longer rely on it.
+- **Breaking change**: event types, stream attributes, event metadata keys, markers that start from `▒`(`"\u2592"`
+  Unicode character) character are now reserved by pg_eventstore. It is less likely you have any, but if you do - you
+  have
+  to adjust your implementation to no longer rely on it.
 - New feature: event markers. You can now mark an event and later use those markers to read events, build a projection
-using subscriptions or validate stream revision scoped to an event type and specific markers when publishing events as 
-a part of Dynamic Consistency Boundaries. Find more in [docs](docs/appending_events.md#event-markers)
+  using subscriptions or validate stream revision scoped to an event type and specific markers when publishing events as
+  a part of Dynamic Consistency Boundaries. Find more in [docs](docs/appending_events.md#event-markers)
 - New config option `config.events_subscription_position_update_interval`. See more
   in [Configuration](docs/configuration.md) docs
 - **Breaking change**: `:from_position` option of `SubscriptionManager#subscribe`, "Current position" column in admin

data/README.md

@@ -66,6 +66,7 @@ Documentation chapters:
 - [Writing middlewares](docs/writing_middleware.md)
 - [How to make multiple commands atomic](docs/multiple_commands.md)
 - [Admin UI](docs/admin_ui.md)
+- [Prometheus metrics](docs/metrics.md)
 - [Replication](docs/replication.md)
 
 To help your AI assistant to better recognize the capabilities of this gem - there is a crafted [instructions](docs/AGENTS.fragment.md)

data/docs/admin_ui.md

@@ -41,3 +41,8 @@ run PgEventstore::Web::Application
 ```
 
 Now you can use any web server to run it.
+
+## Prometheus metrics
+
+Subscriptions observability data in the Prometheus text format is served by a separate rack application, mounted
+independently of the Admin UI. See [Metrics](metrics.md).

data/docs/metrics.md

@@ -0,0 +1,233 @@
+# Prometheus metrics
+
+`pg_eventstore` ships rack endpoints which expose subscriptions observability data in the
+[Prometheus text exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). They answer the
+questions the [Admin UI](admin_ui.md) subscriptions page answers, but in a form Prometheus can scrape and Grafana can
+graph and alert on.
+
+## Endpoints
+
+Metrics are grouped into domains, and split per path within a domain so that each scrape runs only the query it
+needs and cheap families can be polled at a different interval than the expensive one. Paths below are relative to
+wherever the app is mounted - mounted at `/pg_eventstore/metrics` the first one is
+`/pg_eventstore/metrics/subscriptions/latency`.
+
+| Path | Metrics | Query cost |
+|---|---|---|
+| `/subscriptions/latency` | lag of every reported subscription + store positions | the only one looking at event positions (one index range scan per subscription) |
+| `/subscriptions/health` | state, lock, heartbeat age, restarts, last error age | single read of the `subscriptions` table |
+| `/subscriptions/throughput` | processed events counter, handler capacity | single read of the `subscriptions` table |
+| `/subscriptions` | all of the above | all of the above |
+
+The domain path (`/subscriptions`) is meant for humans and ad-hoc checks; point your scrape jobs at the split paths.
+
+**There is deliberately no route serving every domain at once.** `/metrics` is the Prometheus convention, so a route
+there would invite pointing scrape jobs at it by reflex - and every such scrape would pay for every query, including
+the expensive ones, which is exactly what the per-path split exists to avoid. Keeping aggregates per domain also
+keeps each response bounded as more domains are added.
+
+Every query is guarded by a `statement_timeout` of 5 seconds - a stuck scrape fails visibly instead of piling up on
+the database.
+
+### Which subscriptions are reported
+
+Every subscription in the queried database, unless you narrow it down with `set` params (see
+[Reporting only some subscription sets](#reporting-only-some-subscription-sets)). Note that the subscriptions registry
+never removes rows, so handlers that were renamed or removed keep theirs and are reported too.
+
+A subscription that died *without releasing its lock* is reported like any other - detecting it is what
+`pg_eventstore_subscription_heartbeat_age_seconds` is for, and it is the most useful thing to alert on: neither the
+state column nor the lock can be trusted to notice a process that went away.
+
+## Mounting
+
+`PgEventstore::Web::Metrics::Application` is a separate rack application designed to be a scrape target. In your
+`config/routes.rb`:
+
+```ruby
+require 'pg_eventstore/web'
+
+mount PgEventstore::Web::Metrics::Application, at: '/pg_eventstore/metrics'
+```
+
+Or as a standalone `config.ru`:
+
+```ruby
+require 'pg_eventstore/web'
+
+run PgEventstore::Web::Metrics::Application
+```
+
+### Authorization
+
+The application ships without authentication - how you protect the endpoint is up to you, exactly as it is for the
+[Admin UI](admin_ui.md#authorization). Wrap it in whatever middleware your setup already uses, for example:
+
+```ruby
+metrics_app = Rack::Builder.new do
+  use Rack::Auth::Basic do |_username, password|
+    Rack::Utils.secure_compare(ENV.fetch('PG_EVENTSTORE_METRICS_PASSWORD'), password)
+  end
+  run PgEventstore::Web::Metrics::Application
+end
+
+mount metrics_app, at: '/pg_eventstore/metrics'
+```
+
+### Choosing the database
+
+Which store is queried is decided per request by the `config` query param, so one mounted application can serve the
+metrics of every configured database:
+
+```ruby
+PgEventstore.configure(name: :db1) do |config|
+  config.pg_uri = ENV['DB1_URI']
+  config.connection_pool_size = 1
+end
+
+PgEventstore.configure(name: :db2) do |config|
+  config.pg_uri = ENV['DB2_URI']
+  config.connection_pool_size = 1
+end
+```
+
+```
+GET /pg_eventstore/metrics/subscriptions/latency?config=db1
+```
+
+A missing `config` means the default configuration. An unknown `config` is answered with `404` instead of being
+served from the default store, so a typo in the scrape config shows up as a failing target rather than as another
+database's numbers under the wrong labels.
+
+### Reporting only some subscription sets
+
+Rows of the subscriptions registry are never removed, so a database that has been running for a while also holds
+handlers that were renamed, removed, or never ran against it. Pass one or more `set` params to report only the
+subscriptions you care about:
+
+```
+GET /pg_eventstore/metrics/subscriptions/health?set=MyAppSet&set=MyOtherSet
+GET /pg_eventstore/metrics/subscriptions/health?set=MyAppSet,MyOtherSet
+```
+
+Both forms work - a repeated param (what Prometheus produces from `params: {set: [...]}`) and a comma separated list.
+
+Without a `set` param every subscription in the database is reported. `pg_eventstore` puts no constraints on how
+subscription sets are named, but it is convenient to name a set after the application that owns it - scoping the
+scrape by set is then the straightforward way to keep one application's dashboards to its own subscriptions.
+
+## Prometheus scrape config
+
+```yaml
+scrape_configs:
+  - job_name: 'pg-eventstore-subscriptions-latency'
+    metrics_path: /pg_eventstore/metrics/subscriptions/latency
+    scrape_interval: 30s
+    params:
+      config: ['db1']
+      set: ['MyAppSet']
+    static_configs:
+      - targets: ['your-app-host:port']
+  - job_name: 'pg-eventstore-subscriptions-health'
+    metrics_path: /pg_eventstore/metrics/subscriptions/health
+    scrape_interval: 30s
+    params:
+      config: ['db1']
+      set: ['MyAppSet']
+    static_configs:
+      - targets: ['your-app-host:port']
+  - job_name: 'pg-eventstore-subscriptions-throughput'
+    metrics_path: /pg_eventstore/metrics/subscriptions/throughput
+    scrape_interval: 60s
+    params:
+      config: ['db1']
+      set: ['MyAppSet']
+    static_configs:
+      - targets: ['your-app-host:port']
+```
+
+Add whatever credentials your chosen protection needs to these jobs - Prometheus supports `basic_auth`,
+`authorization` and `tls_config` per job.
+
+The split into three jobs is intentional - do not collapse them into a single `/subscriptions` scrape unless you
+are fine with every scrape paying the latency query.
+
+## Metrics reference
+
+All per-subscription metrics carry `set` and `name` labels.
+
+### Latency
+
+`pg_eventstore_subscription_lag_events` (gauge)
+
+How many events the subscription still has to catch up on before it reaches the edge of the `"all"` stream and starts
+processing newly appended events.
+
+Note on filters: a subscription's filter is accounted for by the store, so a caught-up subscription reports `0` no
+matter how narrow its filter is - traffic it does not care about never shows up as its lag. For a *lagging*
+subscription the value counts everything in the range it has not reached yet, matching its filter or not. Read it as
+staleness ("how far behind is this subscription"), not as the number of events its handler is about to run: that
+number is usually much smaller, because non-matching ranges are skipped without invoking the handler.
+
+`pg_eventstore_subscription_lag_seconds` (gauge)
+
+Age of the oldest event the subscription has not processed yet. `0` when fully caught up.
+
+The metric is absent for a subscription whose oldest unprocessed event no longer exists, which happens when that
+event or its stream was deleted. Reporting `0` there would read as "caught up", so nothing is reported instead and
+`lag_events` remains the source of truth for the backlog.
+
+`pg_eventstore_store_frontier_position` (gauge)
+
+Latest position assigned to an event, which is what subscription checkpoints are measured against. It only advances
+while at least one subscriptions process is running; when they are all down, lag stops growing - that situation shows
+up in the heartbeat metric below, not in the lag metrics.
+
+`pg_eventstore_store_head_global_position` (gauge)
+
+Global position of the newest event in the store. Contains gaps; do not compare subscription checkpoints against it.
+
+### Health
+
+`pg_eventstore_subscription_state` (gauge, extra `state` label, value is always 1)
+
+Last *recorded* state. A subscription killed without a graceful shutdown keeps `state="running"` and its lock
+forever - correlate with the heartbeat age below.
+
+`pg_eventstore_subscription_locked` (gauge, 0/1)
+
+Whether the subscription is currently locked by a subscriptions set.
+
+`pg_eventstore_subscription_heartbeat_age_seconds` (gauge)
+
+Seconds since the subscription row was last touched by its runner. Alive subscriptions update it about every 10
+seconds. **A locked subscription with a stale heartbeat is a dead process** - this is the signal to alert on for
+process death, since neither `state` nor the lock can be trusted for that.
+
+`pg_eventstore_subscription_restarts_total` (counter)
+
+Times the subscription was restarted after a failure.
+
+`pg_eventstore_subscription_last_error_age_seconds` (gauge)
+
+Seconds since the last error. Absent when the subscription never failed.
+
+### Throughput
+
+`pg_eventstore_subscription_processed_events_total` (counter)
+
+Total number of events processed. Use `rate()` over it for the actual current throughput - it correctly drops to 0
+when no matching events arrive.
+
+`pg_eventstore_subscription_capacity_events_per_second` (gauge)
+
+Derived from the average handler execution time of the last few processed events, *whenever they happened*. It
+answers "how fast can this handler go when it is fed" and is sticky while the subscription is idle - do not read it
+as current throughput. The ratio `rate(processed_events_total) / capacity` is a useful saturation signal: a
+subscription running close to its capacity has no headroom left, and a traffic spike will turn directly into lag.
+
+## Alerting suggestions
+
+- Lagging read models: `pg_eventstore_subscription_lag_seconds > 300 for 10m`
+- Dead subscription process: `pg_eventstore_subscription_locked == 1 and pg_eventstore_subscription_heartbeat_age_seconds > 60 for 10m`
+- No headroom: `rate(pg_eventstore_subscription_processed_events_total[5m]) / pg_eventstore_subscription_capacity_events_per_second > 0.8 for 15m`

data/lib/pg_eventstore/chunks/subscription_events_index_chunk.rb

@@ -85,9 +85,7 @@ module PgEventstore
       rescue => exception
         @indexes.unshift(*indexes_to_resolve)
         @resolved = false
-        raise Utils.wrap_exception(
-          exception, global_positions: indexes_to_resolve.map(&:global_position)
-        )
+        raise exception
       end
 
       # @return [PgEventstore::EventsGlobalIndexQueries]

data/lib/pg_eventstore/queries/replica_queries.rb

@@ -27,7 +27,10 @@ module PgEventstore
       return [] unless exists
 
       @query_strategy.exec_params(<<~SQL, [indexes.map(&:subscription_position)]).map { _1['subscription_position'] }
-        select subscription_position from event_subscription_positions where subscription_position = any($1::bigint[])
+        select subscription_position
+        from event_subscription_positions
+        where subscription_position = any($1::bigint[])
+        order by subscription_position
       SQL
     end
 
@@ -50,7 +53,7 @@ module PgEventstore
     # @return [Array<PgEventstore::EventGlobalIndex>]
     def load_events_global_index(indexes)
       result = @query_strategy.exec_params(<<~SQL, [indexes.map(&:global_position)])
-        select * from events_global_index where global_position = any($1::bigint[])
+        select * from events_global_index where global_position = any($1::bigint[]) order by global_position
       SQL
       result.map { EventGlobalIndex.new(**_1.transform_keys(&:to_sym)) }
     end
@@ -59,7 +62,7 @@ module PgEventstore
     # @return [Array<PgEventstore::StreamGlobalIndex>]
     def load_streams_global_index(indexes)
       result = @query_strategy.exec_params(<<~SQL, [indexes.map(&:streams_global_index_id)])
-        select * from streams_global_index where id = any($1::bigint[])
+        select * from streams_global_index where id = any($1::bigint[]) order by id
       SQL
       stream_revisions_map = indexes.group_by(&:streams_global_index_id).to_h do |stream_id, events_idx|
         [stream_id, events_idx.max_by(&:stream_revision).stream_revision]
@@ -75,7 +78,7 @@ module PgEventstore
     # @return [Array<PgEventstore::EventMarkerIndex>]
     def load_event_markers_index(indexes)
       result = @query_strategy.exec_params(<<~SQL, [indexes.map(&:global_position)])
-        select * from event_markers_index where global_position = any($1::bigint[])
+        select * from event_markers_index where global_position = any($1::bigint[]) order by global_position
       SQL
       result.map { EventMarkerIndex.new(**_1.transform_keys(&:to_sym)) }
     end
@@ -84,7 +87,7 @@ module PgEventstore
     # @return [Array<PgEventstore::EventMarker>]
     def load_markers(indexes)
       result = @query_strategy.exec_params(<<~SQL, [indexes.map(&:marker_id).uniq])
-        select * from event_markers where id = any($1::bigint[])
+        select * from event_markers where id = any($1::bigint[]) order by id
       SQL
       result.map { EventMarker.new(**_1.transform_keys(&:to_sym)) }
     end

data/lib/pg_eventstore/sql_builder.rb

@@ -215,7 +215,7 @@ module PgEventstore
 
     # @return [String]
     def from_sql
-      return @from_value if @from_value.is_a?(String)
+      return "#{@from_value} #{@table_alias if @table_alias != @from_value}" if @from_value.is_a?(String)
 
       sql = merge(@from_value)
       "(#{sql}) #{@table_alias}"

data/lib/pg_eventstore/subscriptions/callback_handlers/subscription_runner_handlers.rb

@@ -29,7 +29,7 @@ module PgEventstore
       end
 
       # @param subscription [PgEventstore::Subscription]
-      # @param error [PgEventstore::WrappedException]
+      # @param error [StandardError]
       # @return [void]
       def update_subscription_error(subscription, error)
         subscription.update(last_error: Utils.error_info(error), last_error_occurred_at: Time.now.utc)

data/lib/pg_eventstore/subscriptions/runner_recovery_strategies/report_subscription_unrecoverable_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module RunnerRecoveryStrategies
+    # Reports a subscription death that no other strategy handles, then leaves it dead.
+    # @!visibility private
+    class ReportSubscriptionUnrecoverableError
+      include RunnerRecoveryStrategy
+
+      # @param subscription [PgEventstore::Subscription]
+      # @param failed_subscription_notifier [#call, nil]
+      def initialize(subscription:, failed_subscription_notifier:)
+        @subscription = subscription
+        @failed_subscription_notifier = failed_subscription_notifier
+      end
+
+      # @param _error [StandardError]
+      # @return [true]
+      def recovers?(_error)
+        true
+      end
+
+      # @param error [StandardError]
+      # @return [false] the subscription stays dead - this strategy reports, it does not recover
+      def recover(error)
+        @failed_subscription_notifier&.call(@subscription.dup, error)
+        false
+      end
+    end
+  end
+end

data/lib/pg_eventstore/subscriptions/runner_recovery_strategies.rb

@@ -3,3 +3,4 @@
 require_relative 'runner_recovery_strategies/restore_connection'
 require_relative 'runner_recovery_strategies/restore_subscription_runner'
 require_relative 'runner_recovery_strategies/restore_subscription_feeder'
+require_relative 'runner_recovery_strategies/report_subscription_unrecoverable_error'

data/lib/pg_eventstore/subscriptions/subscriptions_manager.rb

@@ -245,6 +245,11 @@ module PgEventstore
           restart_terminator:,
           failed_subscription_notifier:
         ),
+        # Catch-all recovery strategy that only reports an error. It is only invoked in case previous strategies
+        # rejected to recover an error. Must be stayed last.
+        RunnerRecoveryStrategies::ReportSubscriptionUnrecoverableError.new(
+          subscription:, failed_subscription_notifier:
+        ),
       ]
     end
 

data/lib/pg_eventstore/utils.rb

@@ -110,6 +110,8 @@ module PgEventstore
       end
       # rubocop:enable Lint/SuppressedException
 
+      # Wraps subscription handler exception to correctly differentiate it from other errors that may happen inside
+      # the implementation. This is needed to correctly handle subscription handler errors vs internal errors.
       # @param exception [StandardError]
       # @param extra [Hash] additional exception info
       # @return [PgEventstore::WrappedException]

data/lib/pg_eventstore/version.rb

@@ -2,5 +2,5 @@
 
 module PgEventstore
   # @return [String]
-  VERSION = '3.0.1'
+  VERSION = '3.1.1'
 end

data/lib/pg_eventstore/web/application.rb

@@ -176,6 +176,13 @@ module PgEventstore
           streams || []
         end
 
+        # Only maintainable roles can delete a stream or an event. This helper only supposes to hide delete buttons -
+        # backend has its own checks.
+        # @return [Boolean]
+        def can_delete?
+          PgEventstore::Config::NodeRole.maintainable.include?(PgEventstore.config(current_config).eventstore_role)
+        end
+
         private
 
         # @param hash [Hash]

data/lib/pg_eventstore/web/metrics/application.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Web
+    module Metrics
+      # Standalone rack application serving subscription metrics in the Prometheus text exposition format.
+      #
+      # It ships without any authentication - how the endpoint is protected is up to the application mounting it,
+      # the same way it is for the Admin UI (see docs/admin_ui.md#authorization).
+      #
+      # Which pg_eventstore database is queried is chosen per request with the "config" query param, so one mounted
+      # app can serve metrics of every configured store:
+      #
+      #   GET /subscriptions/latency?config=db1
+      #
+      # An absent config means the default one; an unknown config is answered with 404 rather than silently served from
+      # the default store, so a misconfigured scrape shows up as a failing target instead of as wrong data. Add "set"
+      # params to report only some subscription sets - repeat the param for several: "?set=SetA&set=SetB".
+      class Application < Sinatra::Base
+        set :environment, -> { (ENV['RACK_ENV'] || ENV['RAILS_ENV'] || ENV['APP_ENV'])&.to_sym || :development }
+        set :logging, false
+        set :sessions, false
+        set :host_authorization, { allow_if: ->(_env) { true } }
+
+        helpers(Helpers) do
+          # @return [PgEventstore::Connection]
+          def metrics_connection
+            PgEventstore.connection(config_name)
+          end
+
+          # Name of the config to query: the "config" param when given, the default config otherwise. Halts with 404
+          # for a name that is not configured.
+          # @return [Symbol]
+          def config_name
+            requested = params[:config].to_s
+            return PgEventstore::DEFAULT_CONFIG if requested.empty?
+            return requested.to_sym if PgEventstore.available_configs.include?(requested.to_sym)
+
+            halt 404, { 'content-type' => 'text/plain' }, "Unknown config #{requested.inspect}"
+          end
+        end
+
+        get('/subscriptions') do
+          metrics_response(
+            [Collectors::SubscriptionsLatency, Collectors::SubscriptionsHealth, Collectors::SubscriptionsThroughput]
+          )
+        end
+
+        # The only route querying event positions - one index range scan per subscription.
+        get('/subscriptions/latency') do
+          metrics_response([Collectors::SubscriptionsLatency])
+        end
+
+        get('/subscriptions/health') do
+          metrics_response([Collectors::SubscriptionsHealth])
+        end
+
+        get('/subscriptions/throughput') do
+          metrics_response([Collectors::SubscriptionsThroughput])
+        end
+      end
+    end
+  end
+end

data/lib/pg_eventstore/web/metrics/collectors/base.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Web
+    module Metrics
+      module Collectors
+        # Base class for metric collectors. A collector runs read-only queries and returns an array of
+        # {MetricFamily} objects.
+        class Base
+          # Milliseconds. Guards the store from a metrics query that got stuck - a scrape then fails visibly instead
+          # of piling up on the database.
+          # @return [Integer]
+          STATEMENT_TIMEOUT = 5_000
+
+          # @!attribute connection
+          #   @return [PgEventstore::Connection]
+          attr_reader :connection
+          # @!attribute sets
+          #   @return [Array<String>]
+          attr_reader :sets
+          private :connection, :sets
+
+          # @param connection [PgEventstore::Connection]
+          # @param sets [Array<String>] subscription sets to report on; an empty array means all of them
+          def initialize(connection, sets: [])
+            @connection = connection
+            @sets = sets
+          end
+
+          # @return [Array<PgEventstore::Web::Metrics::MetricFamily>]
+          def call
+            raise NotImplementedError, "#{self.class} must implement #call"
+          end
+
+          private
+
+          # @return [PgEventstore::SQLBuilder]
+          def subscriptions_sql_builder
+            sql_builder = SQLBuilder.new.from('subscriptions', table_alias: 's')
+            sql_builder.order('s.set, s.name')
+            sql_builder.where('s.set = any(?::varchar[])', sets) if sets.any?
+            sql_builder
+          end
+
+          # @return [Array<Hash>]
+          def with_safe_conn
+            transaction_queries.transaction(:read_committed, read_only: true) do
+              connection.with do |conn|
+                conn.exec("set local statement_timeout to #{STATEMENT_TIMEOUT}")
+                yield conn
+              end
+            end.to_a
+          end
+
+          # @param row [Hash]
+          # @return [Hash<Symbol => String>]
+          def subscription_labels(row)
+            { set: row['set'], name: row['name'] }
+          end
+
+          # @return [PgEventstore::TransactionQueries]
+          def transaction_queries
+            TransactionQueries.new(connection)
+          end
+        end
+      end
+    end
+  end
+end