trellis-pg 0.1.0.pre.beta-x86_64-linux → 0.1.0.pre.gamma-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d86a74e73faa73fa96c2670a96001a9831aafdf196b58d78d08b85a1ad52c17d
-  data.tar.gz: fffb2fad280d0fb93fe3d36796b7c159c5dc65f9d90c57723d094ad0d30712da
+  metadata.gz: e18f0e6ed130544487637158d07dde5df97b1ca71be833a2c83de5707bc57caf
+  data.tar.gz: 71362e6e792f82b2981c617a905e2902728845144cdeda6fe61db0e6456cdfec
 SHA512:
-  metadata.gz: 3d0d4197540c27b200dd4b8b1407bf5eb6ea03ccfc19a7c32356054d924ffdd84426ef933c3e7d34b053ddf4c8f650afd3c7c1506627cc945fbc7c754b902cda
-  data.tar.gz: 37298b8e67cf65434438881ef7fa2b42037713fb143b764e3242ba4655cd65afea4c9096e62002bb2cf4c8238258791ca84ad183d315325d7a4a1319e38a41a7
+  metadata.gz: 5caa307be2a264f46ea22831af13a4f8b13ce7884fb85e5f212d021842f699087a30ce3885d8d28810df710961efbfb2203ae86493c4da5b422ed54e487b1a85
+  data.tar.gz: 3af1b8ff7efea4b7d51506a49a99d312344c8469006704edb501ecb02838f28bf5ee8dcba45d12c768436f8658f00dfd10e58039e7c28c70bc2b87f6878c8030

data/README.md

@@ -103,6 +103,9 @@ Nothing in the binding uses it.
   and `self_check_job` returns `nil` for the replaced job or one whose
   transform was dropped. With no drain worker anywhere in the fleet a job
   stays `:queued`.
+- `Trellis::Metrics.render_prometheus`: the process-wide metrics registry as
+  Prometheus text, for a `/metrics` route the app already serves (the
+  binding opens no port; see [Metrics](#metrics)). It needs no handle.
 
 ```ruby
 require "trellis/pg"
@@ -172,6 +175,32 @@ Every handle (each `Trellis::Instance` too) costs this again. The full
 accounting is in
 [`docs/embedding.md`](../../docs/embedding.md#what-a-handle-uses).
 
+### Metrics
+
+The engine's metrics live in one registry per process, holding the series of
+every handle in it; `Trellis::Metrics.render_prometheus` renders them in
+Prometheus's text format. Every series carries a `trellis_instance` label
+(`<database>/<catalog schema>`), so instances in one process stay apart, and
+`trellis_instance_up` is 1 while an instance's handle runs and 0 after it
+shuts down. The metrics themselves are listed in
+[`docs/observability.md`](../../docs/observability.md).
+
+The binding opens no port, so serve the text from a route of the app's own:
+
+```ruby
+# config/routes.rb
+get "/metrics", to: proc {
+  [200, { "content-type" => "text/plain; version=0.0.4" }, [Trellis::Metrics.render_prometheus]]
+}
+```
+
+Under a forking server each worker process has its own registry, holding
+only its own handles' series, so Prometheus scrapes each worker (or the
+worker handle, `staging: true`, runs in a process of its own that it
+scrapes). A process forked while its parent had a handle running can't
+render the registry, as it can't connect: it raises
+`Trellis::ForkedHandleError` (see [Forking servers](#forking-servers)).
+
 ### Several instances
 
 A process can hold several Trellis instances, for different catalog schemas
@@ -524,6 +553,7 @@ source rows; a test database has none, so that is immediate. Runtime state
 ## Layout
 
 - `lib/`: the `Trellis` module and `Trellis::Instance`, its error classes and its `Data` values,
+  `Trellis::Metrics`,
   the Rails integration (`trellis/railtie.rb`, `trellis/migration.rb`),
   loaded only in an app that has Rails, and the test helpers
   (`trellis/test_support.rb`), loaded only when required.

data/lib/trellis/metrics.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Trellis
+  # The engine's metrics, in Prometheus text exposition format: the Rust
+  # crate's trellis::Metrics#render_prometheus
+  # (docs/decisions/0009-observability-decisions.md).
+  #
+  # The registry is process-wide: one body holds the series of every Trellis
+  # handle in this process, so it needs no handle and works before
+  # Trellis.connect and after Trellis.shutdown. Every series carries a
+  # trellis_instance="<database>/<catalog schema>" label, so instances in one
+  # process stay apart. trellis_instance_up is 1 while an instance has a
+  # running handle and 0 after its last one shuts down; the other gauges of a
+  # stopped instance disappear after 60 seconds. See docs/observability.md.
+  #
+  # The binding opens no port. Serve the text from a route the app already
+  # has, for example in Rails:
+  #
+  #   # config/routes.rb
+  #   get "/metrics", to: proc {
+  #     [200, { "content-type" => "text/plain; version=0.0.4" }, [Trellis::Metrics.render_prometheus]]
+  #   }
+  #
+  # In a forking server each worker process has its own registry, holding
+  # only its own handles' series, so scrape every worker (or run the worker
+  # handle, staging: true, in a process of its own and scrape that).
+  #
+  # A process forked while its parent had an engine running may have
+  # inherited the registry's lock held, so rendering there raises
+  # Trellis::ForkedHandleError, as Trellis.connect does.
+  module Metrics
+    # Renders the registry's current contents: # HELP and # TYPE lines, then
+    # each series' samples.
+    def self.render_prometheus
+      Native.render_prometheus
+    end
+  end
+end

data/lib/trellis/pg.rb

@@ -24,6 +24,7 @@ else
 end
 
 require_relative "instance"
+require_relative "metrics"
 
 # Embedded Trellis for Ruby apps: a native extension over the `trellis`
 # crate's BlockingTrellis, so a Rails app can define and run streaming
@@ -48,6 +49,7 @@ require_relative "instance"
 # - Operations: request_backfill, detect_capture_disruptions, has_live_drain_workers?,
 #   has_live_staging_worker?, watermark_token, await_converged, self_check,
 #   self_check_job.
+# - Metrics: Trellis::Metrics.render_prometheus, which needs no handle.
 #
 #   # A deploy's migration step: the defaults run nothing in the background.
 #   Trellis.connect(url: "host=localhost dbname=app")

data/lib/trellis/version.rb

@@ -3,5 +3,5 @@
 module Trellis
   # The trellis-pg gem's version: the Trellis release's, which a
   # `v<VERSION>` tag releases (docs/releasing.md).
-  VERSION = "0.1.0-beta"
+  VERSION = "0.1.0-gamma"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trellis-pg
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.beta
+  version: 0.1.0.pre.gamma
 platform: x86_64-linux
 authors:
 - Salesforce
@@ -25,6 +25,7 @@ files:
 - lib/trellis/4.0/trellis_ruby.so
 - lib/trellis/error.rb
 - lib/trellis/instance.rb
+- lib/trellis/metrics.rb
 - lib/trellis/migration.rb
 - lib/trellis/pg.rb
 - lib/trellis/railtie.rb