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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 040d3074f1223a81e28989c5d0a2b7825e84806ea0b088894fc1ea0daaf68312
-  data.tar.gz: e5bbfe7ce9446bd67d7b01666e555255a6ab39687c2c7415080789ddb8a934ac
+  metadata.gz: 8839af0acc8f206000a1348bbba21b4ea1d06784bf7d677c0244f0c630863c00
+  data.tar.gz: 77f8ffb6fc607c81fcbb614a6238aa9c21770616a525aeda1df4a007247c0d59
 SHA512:
-  metadata.gz: 0f56d84b4f68c1619f480040e659513872e4c6d9f93358eff375b400b7e5b22eb9c2c29080c5433cc24ae9ab33cb8467f735c151e36c6634fea094fa2e04a5de
-  data.tar.gz: cc1c7b5b6ed393b91c6ed3a866a0172ddb085b297e4c7914ec4a3de56f32163734449d68a2d28e40192bc147c3b797cc16222ff4e7d2b943fbb97a84ac498847
+  metadata.gz: fc0f00f2deb17dcbb647ca2ff60d0da513e77987fc9d4206cf1c4f723412284d44f337120dc1c667a7d6149a07f144d97825a6f9cf473d2f1c3f18630e5c1e00
+  data.tar.gz: 8c00d355d02a8437815fedfa97e519c4ce2fe576e46a4614c273bd1c290c89729bc1f83e1c0176b315f5a26a1566ab74a01b5453b59f25a411308e415c93674e

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/ext/trellis_ruby/Cargo.lock

@@ -1729,8 +1729,8 @@ dependencies = [
 
 [[package]]
 name = "trellis"
-version = "0.1.0-beta"
-source = "git+https://github.com/salesforce-misc/trellis?rev=1820fd7db091e540990d1efe190a687fb4dfeb59#1820fd7db091e540990d1efe190a687fb4dfeb59"
+version = "0.1.0-gamma"
+source = "git+https://github.com/salesforce-misc/trellis?rev=c271ef149159d9309174ca476d792c89128bce99#c271ef149159d9309174ca476d792c89128bce99"
 dependencies = [
  "deadpool",
  "deadpool-postgres",
@@ -1752,8 +1752,8 @@ dependencies = [
 
 [[package]]
 name = "trellis-embed"
-version = "0.1.0-beta"
-source = "git+https://github.com/salesforce-misc/trellis?rev=1820fd7db091e540990d1efe190a687fb4dfeb59#1820fd7db091e540990d1efe190a687fb4dfeb59"
+version = "0.1.0-gamma"
+source = "git+https://github.com/salesforce-misc/trellis?rev=c271ef149159d9309174ca476d792c89128bce99#c271ef149159d9309174ca476d792c89128bce99"
 dependencies = [
  "tracing",
  "trellis",
@@ -1761,7 +1761,7 @@ dependencies = [
 
 [[package]]
 name = "trellis_ruby"
-version = "0.1.0-beta"
+version = "0.1.0-gamma"
 dependencies = [
  "magnus",
  "rb-sys",

data/ext/trellis_ruby/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "trellis_ruby"
-version = "0.1.0-beta"
+version = "0.1.0-gamma"
 edition = "2024"
 publish = false
 
@@ -28,8 +28,8 @@ doctest = false
 ruby = ["dep:magnus", "dep:rb-sys"]
 
 [dependencies]
-trellis = { git = "https://github.com/salesforce-misc/trellis", rev = "1820fd7db091e540990d1efe190a687fb4dfeb59" }
-trellis-embed = { git = "https://github.com/salesforce-misc/trellis", rev = "1820fd7db091e540990d1efe190a687fb4dfeb59" }
+trellis = { git = "https://github.com/salesforce-misc/trellis", rev = "c271ef149159d9309174ca476d792c89128bce99" }
+trellis-embed = { git = "https://github.com/salesforce-misc/trellis", rev = "c271ef149159d9309174ca476d792c89128bce99" }
 magnus = { version = "0.9", optional = true, default-features = false, features = ["rb-sys"] }
 rb-sys = { version = "0.9", optional = true }
 

data/ext/trellis_ruby/src/lib.rs

@@ -1231,6 +1231,20 @@ fn statement_kinds() -> Vec<&'static str> {
         .collect()
 }
 
+/// The process-wide metrics registry in Prometheus text exposition format:
+/// `trellis::Metrics::render_prometheus`, the series of every handle in this
+/// process. It needs no handle.
+///
+/// The registry sits behind a lock the engine's threads take, so a process
+/// forked while its parent had an engine running may have inherited it held:
+/// rendering there raises `Trellis::ForkedHandleError`, as [`connect`] does,
+/// rather than risk the hang. Rendering is a short walk of the registry,
+/// so it keeps the GVL.
+fn render_prometheus(ruby: &Ruby) -> Result<String, Error> {
+    engine::check().map_err(|err| forked_handle_error(ruby, forked_while_running(&err)))?;
+    Ok(trellis::Metrics::new().render_prometheus())
+}
+
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     // Interns every symbol a result can carry up front, from the closed
@@ -1252,6 +1266,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     native.define_module_function("capture_failure_kinds", function!(capture_failure_kinds, 0))?;
     native.define_module_function("index_roles", function!(index_roles, 0))?;
     native.define_module_function("statement_kinds", function!(statement_kinds, 0))?;
+    native.define_module_function("render_prometheus", function!(render_prometheus, 0))?;
 
     let handle = native.define_class("Handle", ruby.class_object())?;
     handle.define_method("owner_pid", method!(Handle::owner_pid, 0))?;

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: ruby
 authors:
 - Salesforce
@@ -41,6 +41,7 @@ files:
 - ext/trellis_ruby/src/lib.rs
 - lib/trellis/error.rb
 - lib/trellis/instance.rb
+- lib/trellis/metrics.rb
 - lib/trellis/migration.rb
 - lib/trellis/pg.rb
 - lib/trellis/railtie.rb