atlas_rb 1.27.1 → 1.27.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c1b0723d54145c8be9868a1849502cf80adbc1a30b2f7b1ee39aadbfa1a2f3b
-  data.tar.gz: 7ab2bb5a662b02dd48275e645f9c6b3c1226d6bc995231766bd5a4252f17b25a
+  metadata.gz: 3bf07fbfa75e57be6651cc352fc2216f8c5e4029a68393018fa14b8e6a34e6aa
+  data.tar.gz: 63d66617e658bc0693c7a07afdf0b38cac2067f464b3ba1e0466b3a8d7d1860e
 SHA512:
-  metadata.gz: 64f43d675ad66dac85657c0460702f53f95c99760e7a44ce6f0dec019e375f41b197c214ca3dc4d89a94a1e0b829fa9d377fd4dd9432fe68cdc53d9aa490e38e
-  data.tar.gz: dfc0ade69d92b8b100698091f6ec22d90eb428769bb61aebdc79a9e842840036bc45875bc330531be335d5a11459c823ff13a1ccd78e1b143b11009f083ca54b
+  metadata.gz: 2071b3face694f62a03db93362462bf77381cfdcee77c138ff5a2baabe47f000d94ede673ca1d28f160d0348506a844346f920b71457669bae326769aa9286e3
+  data.tar.gz: 823ca671c648afad8c4a82111d658a691c6bf757e02cb942594c0a1c6afec2a1b6fda628c954ca909497c7168a6384f845fcf4ed229a1f470d5fabb1bac212c8

data/.version

@@ -1 +1 @@
-1.27.1
+1.27.2

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.27.2
+
+Requires an Atlas that serves `GET /metrics/latency`.
+
+### Added — `AtlasRb::Metrics.latency`
+
+Reads Atlas's own request latency for a window of up to 120 minutes: calls,
+5xx count, mean and approximate p50/p95/p99, and the slowest actions. Sent
+with the acting NUID's signed assertion, which must name an admin. A
+5-second deadline, no retry and a fresh socket per call. Raises
+`BackendUnavailableError` when Atlas's Redis is down and `ResourceError` on
+any other non-200.
+
 ## 1.27.1
 
 Requires an Atlas that serves `GET /health` and the `backend_unavailable`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.27.1)
+    atlas_rb (1.27.2)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/README.md

@@ -857,6 +857,30 @@ It is not a `ResourceError`, which hosts treat as a refusal of the request.
 A streaming download (`Blob.content`, `Blob.version_content`) cannot raise
 this: its body has already gone to your block. Check the returned `status`.
 
+### Atlas's own latency
+
+`AtlasRb::Metrics.latency` reports how long Atlas took to serve its own
+requests over a recent window. Atlas gates it to admins and `:system`, so
+`nuid` must name an admin:
+
+```ruby
+latency = AtlasRb::Metrics.latency(minutes: 60, nuid: current_user.nuid)
+latency["calls"]          # => 18402
+latency["server_errors"]  # => 3
+latency["p95_ms"]         # => 98
+latency["slowest_actions"].first  # => { "action" => "works#mods", "calls" => 912, "p95_ms" => 188 }
+```
+
+Atlas times each request from when Rails dispatches it until it returns, so
+the figures leave out the network and your own waiting. If you also time your
+Atlas calls, the difference is time spent on your side. The percentiles are
+interpolated from histogram buckets, so they are approximate.
+
+Like `Health.read`, it has a 5-second deadline and no retry. It raises
+`BackendUnavailableError` (with `dependency == "cache"`) when Atlas's Redis is
+down, `ResourceError` on any other non-200 such as a `403`, and `Faraday`
+errors when nothing answers.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/metrics.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Atlas's own operational figures. Admin- or `:system`-gated in Atlas.
+  class Metrics
+    extend AtlasRb::FaradayHelper
+
+    # Seconds to wait for a socket to open.
+    OPEN_TIMEOUT = 2
+
+    # Seconds to wait for the report. It reads at most 120 small Redis hashes,
+    # so a slower answer means Atlas is struggling, and an admin page should
+    # not wait on it.
+    READ_TIMEOUT = 5
+
+    # How long Atlas took to serve its own requests (`GET /metrics/latency`).
+    #
+    # Measured inside Atlas, from when Rails dispatches the action until it
+    # returns, so it leaves out the network and the caller's own waiting. A
+    # caller that also times its Atlas calls can subtract to see how much of
+    # its wait was its own. The percentiles are interpolated from histogram
+    # buckets, so they are approximate.
+    #
+    # No retry, and a fresh socket per call: like {AtlasRb::Health.read}, it is
+    # polled rarely and should fail fast rather than hide a struggling Atlas.
+    #
+    # @param minutes [Integer] the window, 1 to 120. Atlas clamps it.
+    # @param nuid [String, nil] the acting NUID, signed into the assertion
+    #   `sub`. It must name an admin; falls through to
+    #   {AtlasRb.config#default_nuid}.
+    # @param on_behalf_of [String, nil] optional NUID carried as a signed `obo`
+    #   claim.
+    # @return [AtlasRb::Mash] `window_minutes`, `calls`, `server_errors`,
+    #   `mean_ms`, `p50_ms`, `p95_ms`, `p99_ms` (Integer, or nil with no calls),
+    #   and `slowest_actions`, an Array of `action` / `calls` / `p95_ms`.
+    # @raise [AtlasRb::BackendUnavailableError] when Atlas answers that Redis,
+    #   which holds the figures, is down (`dependency == "cache"`).
+    # @raise [AtlasRb::ResourceError] on any other non-200, notably a `403`
+    #   for a caller who is not an admin.
+    # @raise [Faraday::ConnectionFailed, Faraday::TimeoutError] when Atlas does
+    #   not answer at all.
+    #
+    # @example
+    #   latency = AtlasRb::Metrics.latency(minutes: 15, nuid: current_user.nuid)
+    #   latency.p95_ms  # => 98
+    def self.latency(minutes: 60, nuid: nil, on_behalf_of: nil)
+      resp = metrics_connection(nuid, on_behalf_of).get("/metrics/latency", minutes: minutes)
+      return AtlasRb::Mash.new(JSON.parse(resp.body)) if resp.status == 200
+
+      raise AtlasRb::ResourceError.new("#{request_target(resp)} → #{resp.status}: #{resp.body}", response: resp)
+    end
+
+    class << self
+      private
+
+      def metrics_connection(nuid, on_behalf_of)
+        headers = auth_headers(nuid, on_behalf_of).merge("Content-Type" => "application/json")
+        Faraday.new(url: ENV.fetch("ATLAS_URL", nil), headers: headers) do |f|
+          f.options.open_timeout = OPEN_TIMEOUT
+          f.options.timeout      = READ_TIMEOUT
+          instrument(f)
+          f.use AtlasRb::Middleware::RaiseOnBackendUnavailable
+          f.adapter :net_http
+        end
+      end
+    end
+  end
+end

data/lib/atlas_rb.rb

@@ -48,6 +48,7 @@ require_relative "atlas_rb/system/work"
 require_relative "atlas_rb/audit_event"
 require_relative "atlas_rb/maintenance"
 require_relative "atlas_rb/health"
+require_relative "atlas_rb/metrics"
 
 # Ruby client for the Atlas API — Northeastern University's institutional
 # digital repository.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.27.1
+  version: 1.27.2
 platform: ruby
 authors:
 - David Cliff
@@ -173,6 +173,7 @@ files:
 - lib/atlas_rb/health.rb
 - lib/atlas_rb/maintenance.rb
 - lib/atlas_rb/mash.rb
+- lib/atlas_rb/metrics.rb
 - lib/atlas_rb/middleware/raise_on_backend_unavailable.rb
 - lib/atlas_rb/middleware/raise_on_read_error.rb
 - lib/atlas_rb/middleware/raise_on_read_only_mode.rb