atlas_rb 1.27.1 → 1.27.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c1b0723d54145c8be9868a1849502cf80adbc1a30b2f7b1ee39aadbfa1a2f3b
-  data.tar.gz: 7ab2bb5a662b02dd48275e645f9c6b3c1226d6bc995231766bd5a4252f17b25a
+  metadata.gz: 57da54874f04fe2d2b07757c8c062fe5a4e95aae8d843de69ed7bd53158b8122
+  data.tar.gz: af25098d8000917fac7e65121fc575dd38460ed23c2515e6309d2d230c9389ce
 SHA512:
-  metadata.gz: 64f43d675ad66dac85657c0460702f53f95c99760e7a44ce6f0dec019e375f41b197c214ca3dc4d89a94a1e0b829fa9d377fd4dd9432fe68cdc53d9aa490e38e
-  data.tar.gz: dfc0ade69d92b8b100698091f6ec22d90eb428769bb61aebdc79a9e842840036bc45875bc330531be335d5a11459c823ff13a1ccd78e1b143b11009f083ca54b
+  metadata.gz: 228ce5a5c9c2746628bea89760fd5b623d017a3511e2d8f59ce22401aa58499a2e82500da0fd76ba12dacd5e3d5fd772694f717b7312e98b0c2b8fec43c94ca2
+  data.tar.gz: 3b92e9cf2b59e766276a7654fa2769d5339b9b511f146aa429692b8f7d84dfa3a96b5575659b6ee923d64bc3b08bc1291f8245de75922b419ba9b276629a7043

data/.version

@@ -1 +1 @@
-1.27.1
+1.27.3

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.27.3
+
+### Changed — `Metrics.latency` documentation
+
+Atlas 0.6.227 times each request from the top of its Rack stack, the same span
+as `x-runtime`, rather than the controller action alone. The YARD and README
+now say so. No code changed; against an older Atlas the figures are still
+action-only.
+
+## 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.3)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/README.md

@@ -857,6 +857,32 @@ 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 it enters Atlas's Rack stack until the app
+returns the response, the same span as the `x-runtime` header. The figures
+include time a request waited inside Atlas behind concurrent ones. They leave
+out time queued for a Puma thread, 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,71 @@
+# 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 a request enters its Rack stack until
+    # the app returns the response — the same span as the `x-runtime` header.
+    # So it includes time a request spent waiting inside Atlas behind
+    # concurrent ones, and leaves out time queued for a Puma thread, 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.3
 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