psi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aac38eed9cc273f4e71ec2b49e98875f8e0a755161e6ec907881b37fb93ea2ea
+  data.tar.gz: effca4aee4a4d0b90f9069e5993acde56a7a6a1a3b19b77cee565323930da2cb
+SHA512:
+  metadata.gz: 48d898561c14f61b909e4f990ce3f54be04152394cc2d1063bec7cdc03d8707e174a1b8920d71e223001a18261b69d40b4fb57bfd9edc26866a6c276062c0c6e
+  data.tar.gz: 91af3741be9074610ddad23191362a7251cdd00813429bd9ece59ab208bea147c7e7ac8edb829e00f10cfe679652f68cc2f840c72503e11402c6168bc9b0e4e6

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+--output-dir doc
+lib/**/*.rb

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# PSI
+
+PSI is a pure Ruby interface to Linux Pressure Stall Information. It reads
+system-wide and cgroup v2 pressure metrics, calculates exact interval ratios,
+and monitors kernel PSI triggers without a C extension.
+
+## Requirements
+
+- Ruby 3.2 or later
+- Linux 4.20 or later with `CONFIG_PSI=y` for readings
+- Linux 5.2 or later and write permission on a pressure file for triggers
+
+Some distributions built with `CONFIG_PSI_DEFAULT_DISABLED=y` also require the
+`psi=1` kernel command-line option.
+
+## Installation
+
+```sh
+bundle add psi
+```
+
+## Read pressure
+
+```ruby
+require "psi"
+
+reading = PSI.read(:memory)
+reading.some.avg10  # percentage over the last 10 seconds
+reading.full.total  # cumulative stalled microseconds
+
+PSI.resources # => [:cpu, :memory, :io] plus :irq where available
+PSI.read_all   # => { cpu: PSI::Reading, ... }
+```
+
+`some` means at least one task was stalled. `full` means every non-idle task
+was stalled. System-wide CPU pressure normally has only `some`; IRQ pressure,
+available since Linux 6.1, has only `full`.
+
+For an exact interval ratio, use cumulative totals instead of rolling averages:
+
+```ruby
+sampler = PSI::Sampler.new(:memory)
+sampler.sample # => nil
+sleep 5
+sampler.sample # => #<data PSI::Delta some_ratio=..., full_ratio=..., elapsed=...>
+```
+
+`PSI::Sampler` is intentionally not thread-safe; give each sampling thread its
+own instance.
+
+## Read the current cgroup
+
+Containers should prefer cgroup values because `/proc/pressure` can expose the
+host's system-wide pressure:
+
+```ruby
+cgroup = PSI.current_cgroup
+PSI.read(:memory, cgroup: cgroup)
+```
+
+## Wait for a trigger
+
+Trigger files must be writable. `/proc/pressure/*` normally requires root;
+delegated cgroup v2 pressure files can be used without root.
+On current kernels, an unprivileged trigger's window must be a multiple of two
+seconds; privileged triggers retain the full 0.5–10 second range.
+
+```ruby
+PSI::Trigger.open(:memory, kind: :some, stall: 0.15, window: 1.0) do |trigger|
+  warn "memory pressure" if trigger.wait(timeout: 10)
+end
+```
+
+`window` must be 0.5–10 seconds and `stall` cannot exceed it. Start with a
+`some` trigger around 10–20% of the window for early warning and a higher
+`full` trigger for load shedding, then tune from measurements on the real
+workload. There is no portable 10–30 second warning threshold: reclaim,
+working-set size, and cgroup limits determine the lead time.
+
+## Monitor several triggers
+
+```ruby
+monitor = PSI::Monitor.new
+monitor.on_error { |error| warn error.full_message }
+monitor.on(:memory, stall: 0.1, window: 1.0) { |event| warn event }
+monitor.on(:io, stall: 0.3, window: 2.0) { |event| warn event }
+monitor.start
+
+# Later, during shutdown:
+monitor.stop
+```
+
+Monitor uses one thread and `IO.select`'s priority set. Callback exceptions are
+sent to `on_error` and do not stop monitoring. `stop` wakes the thread and
+closes every trigger.
+
+See `examples/load_shedding.rb` for Rack/Puma-style 503 shedding,
+`examples/prometheus_exporter.rb` for a dependency-free metrics endpoint, and
+`benchmark/monitor_idle.rb` for idle CPU measurement.
+
+## Unsupported and constrained environments
+
+Requiring the gem always succeeds; `PSI.supported?` reports whether the
+system-wide PSI directory exists, and use on an unsupported kernel raises
+`PSI::UnsupportedError`.
+
+| Environment | Limitation |
+|---|---|
+| macOS and Windows | No Linux procfs PSI interface. |
+| WSL2 with an old or PSI-disabled kernel | `/proc/pressure` is absent. |
+| Docker Desktop and other containers | `/proc/pressure` may represent the host; trigger writes are commonly denied. Prefer a delegated cgroup. |
+| GitHub-hosted runners | Readings usually work, but trigger tests require root and the host kernel cannot be changed. |
+| Linux before 4.20 | PSI is unavailable. Linux before 5.2 supports readings but not triggers. |
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test:unit
+bundle exec rbs validate
+bundle exec yard
+```
+
+Linux system tests require PSI trigger write permission:
+
+```sh
+sudo --preserve-env=PATH,GEM_HOME,GEM_PATH bundle exec rake test:system
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec) { |task| task.pattern = "spec/*_spec.rb" }
+RSpec::Core::RakeTask.new("test:system") { |task| task.pattern = "spec/system/*_spec.rb" }
+YARD::Rake::YardocTask.new
+
+namespace :test do
+  task unit: :spec
+  task :gc_stress do
+    ruby "-Ilib", "spec/gc_stress.rb"
+  end
+end
+
+task :compile
+task default: "test:unit"

data/benchmark/monitor_idle.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "psi"
+
+duration = Float(ENV.fetch("DURATION", 5))
+monitor = PSI::Monitor.new.on(:memory, stall: 1.0, window: 10.0, cgroup: ENV["CGROUP"]) {}
+cpu_started = Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID)
+wall_started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+monitor.start
+sleep duration
+monitor.stop
+cpu = Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID) - cpu_started
+wall = Process.clock_gettime(Process::CLOCK_MONOTONIC) - wall_started
+puts "idle CPU: #{(cpu / wall * 100).round(3)}% (#{wall.round(3)}s)"

data/docs/poll-investigation.md

@@ -0,0 +1,23 @@
+# PSI priority-event investigation
+
+Tested on 2026-08-23 with Ruby 3.4.10 and Linux 6.8.0-64-generic in a
+privileged Colima container.
+
+Two CPU-pressure triggers used `some 1000 500000`. Sixteen busy child
+processes generated contention. Both Ruby APIs reported the priority event:
+
+```text
+IO#wait(IO::PRIORITY, 5)          => true
+IO.select(nil, nil, [io], 5)[2]   => [io]
+```
+
+The implementation therefore uses `IO#wait` for a single trigger and the
+exception set of `IO.select` for `PSI::Monitor`. No C extension is needed.
+
+Trigger registration must terminate the single write with a newline or NUL.
+An unterminated write produced `EINVAL` for valid boundary values on this
+kernel, while the same values with a newline registered successfully.
+
+The check requires Linux with PSI trigger support and write permission for
+`/proc/pressure/cpu`. A privileged container was required; an ordinary
+container returned `EACCES`.

data/examples/load_shedding.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "psi"
+
+# Rack middleware that briefly rejects requests after a memory-pressure event.
+class PressureShedder
+  def initialize(app)
+    @app = app
+    @mutex = Mutex.new
+    @reject_until = 0
+    @monitor = PSI::Monitor.new
+    @monitor.on(:memory, stall: 0.2, window: 2.0, cgroup: ENV["CGROUP"] || PSI.current_cgroup) do |event|
+      warn event
+      @mutex.synchronize { @reject_until = monotonic + 10 }
+    end
+    @monitor.start
+  end
+
+  def call(env)
+    return [503, { "content-type" => "text/plain", "retry-after" => "10" }, ["server under pressure\n"]] if rejecting?
+
+    @app.call(env)
+  end
+
+  private
+
+  def rejecting?
+    @mutex.synchronize { monotonic < @reject_until }
+  end
+
+  def monotonic
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/examples/prometheus_exporter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "socket"
+require "psi"
+
+server = TCPServer.new("0.0.0.0", Integer(ENV.fetch("PORT", 9394)))
+cgroup = ENV["CGROUP"]
+
+loop do
+  client = server.accept
+  body = PSI.read_all(cgroup: cgroup).flat_map do |resource, reading|
+    %i[some full].filter_map do |kind|
+      metrics = reading.public_send(kind)
+      next unless metrics
+
+      [10, 60, 300].map { |seconds| "psi_avg{resource=\"#{resource}\",kind=\"#{kind}\",seconds=\"#{seconds}\"} #{metrics.avg(seconds)}" } +
+        ["psi_total_microseconds{resource=\"#{resource}\",kind=\"#{kind}\"} #{metrics.total}"]
+    end
+  end.flatten.join("\n") << "\n"
+  client.write("HTTP/1.1 200 OK\r\nContent-Type: text/plain; version=0.0.4\r\nContent-Length: #{body.bytesize}\r\nConnection: close\r\n\r\n#{body}")
+ensure
+  client&.close
+end

data/lib/psi/event.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PSI
+  # A pressure event delivered by Monitor.
+  class Event
+    attr_reader :resource, :kind, :stall, :window, :reading, :at
+
+    def initialize(trigger:, reading:, at: Time.now)
+      @resource = trigger.resource
+      @kind = trigger.kind
+      @stall = trigger.stall
+      @window = trigger.window
+      @reading = reading
+      @at = at
+    end
+
+    # Formats the pressure and threshold for logs.
+    # @return [String]
+    def to_s
+      average = reading.public_send(kind)&.avg10
+      value = average ? " avg10=#{average}%" : ""
+      "#{resource} #{kind}#{value} (threshold #{duration(stall)}/#{duration(window)})"
+    end
+
+    private
+
+    def duration(seconds)
+      value = seconds < 1 ? seconds * 1000 : seconds
+      unit = seconds < 1 ? "ms" : "s"
+      "#{value.round(3).to_s.delete_suffix(".0")}#{unit}"
+    end
+  end
+end

data/lib/psi/monitor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module PSI
+  # Multiplexes PSI triggers on one background thread.
+  class Monitor
+    def initialize
+      @entries = []
+      @wake_reader, @wake_writer = IO.pipe
+      @error_handler = ->(error) { warn "PSI monitor: #{error.message}" }
+    end
+
+    def on(resource, **options, &callback)
+      raise ArgumentError, "a callback is required" unless callback
+      raise Error, "monitor is already running" if @thread
+      raise Error, "monitor is stopped" if stopped?
+
+      @entries << [Trigger.new(resource, **options), callback]
+      self
+    end
+
+    def on_error(&handler)
+      raise ArgumentError, "an error handler is required" unless handler
+
+      @error_handler = handler
+      self
+    end
+
+    def start
+      raise Error, "monitor is stopped" if stopped?
+      return self if @thread&.alive?
+
+      @thread = Thread.new { run }
+      self
+    end
+
+    # Stops monitoring, wakes the select call, and closes every trigger.
+    # @return [Monitor]
+    def stop
+      return self if stopped?
+
+      @stop = true
+      @wake_writer.write_nonblock(".") if @thread&.alive?
+      @thread.join if @thread && @thread != Thread.current
+      close unless @thread
+      self
+    rescue Errno::EPIPE, IOError
+      self
+    end
+
+    private
+
+    def run
+      triggers = @entries.to_h { |trigger, callback| [trigger.to_io, [trigger, callback]] }
+      until @stop
+        readable, _, priority = IO.select([@wake_reader], nil, triggers.keys)
+        break if readable.include?(@wake_reader)
+
+        priority.each { |io| notify(*triggers.fetch(io)) }
+      end
+    ensure
+      close
+    end
+
+    def notify(trigger, callback)
+      callback.call(Event.new(trigger: trigger, reading: PSI.read(trigger.resource, cgroup: trigger.cgroup)))
+    rescue StandardError => e
+      report_error(e)
+    end
+
+    def report_error(error)
+      @error_handler.call(error)
+    rescue StandardError => e
+      warn "PSI monitor error handler failed: #{e.message}"
+    end
+
+    def close
+      @entries.each { |trigger, _| trigger.close }
+      @wake_reader.close unless @wake_reader.closed?
+      @wake_writer.close unless @wake_writer.closed?
+    end
+
+    def stopped?
+      @wake_reader.closed?
+    end
+  end
+end

data/lib/psi/reading.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PSI
+  # Pressure averages and the cumulative stall time for one PSI category.
+  class Metrics
+    attr_reader :total
+
+    def initialize(averages:, total:)
+      @averages = averages.freeze
+      @total = total
+    end
+
+    # Returns the rolling average for a window in seconds.
+    # @param seconds [Integer]
+    # @return [Float, nil]
+    def avg(seconds)
+      @averages[Integer(seconds)]
+    end
+
+    # @return [Float, nil] ten-second average
+    def avg10 = avg(10)
+    # @return [Float, nil] sixty-second average
+    def avg60 = avg(60)
+    # @return [Float, nil] three-hundred-second average
+    def avg300 = avg(300)
+
+    # Converts dynamic averages and total time to a hash.
+    # @return [Hash]
+    def to_h
+      @averages.sort.to_h { |seconds, value| [:"avg#{seconds}", value] }.merge(total: total)
+    end
+  end
+
+  # A snapshot read from one PSI resource.
+  class Reading
+    attr_reader :resource, :some, :full, :read_at, :metrics
+
+    # Parses the contents of a Linux pressure file.
+    # @param resource [Symbol]
+    # @param text [String]
+    # @param read_at [Time]
+    # @return [Reading]
+    def self.parse(resource, text, read_at: Time.now)
+      metrics = text.each_line.filter_map do |line|
+        kind, *fields = line.split
+        next unless kind
+
+        values = fields.filter_map { |field| field.split("=", 2) if field.include?("=") }.to_h
+        next unless %w[some full].include?(kind) || values.key?("total")
+
+        averages = values.filter_map do |key, value|
+          [Integer(key.delete_prefix("avg")), Float(value)] if key.match?(/\Aavg\d+\z/)
+        end.to_h
+        [kind.to_sym, Metrics.new(averages: averages, total: Integer(values.fetch("total")))]
+      end.to_h
+
+      new(resource: resource, some: metrics[:some], full: metrics[:full], read_at: read_at, metrics: metrics)
+    rescue ArgumentError, KeyError => e
+      raise Error, "invalid PSI data: #{e.message}"
+    end
+
+    def initialize(resource:, some:, full:, read_at:, metrics: nil)
+      @resource = resource
+      @some = some
+      @full = full
+      @read_at = read_at
+      @metrics = (metrics || { some: some, full: full }.compact).freeze
+    end
+  end
+end

data/lib/psi/sampler.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PSI
+  # Stall ratios calculated from two consecutive readings.
+  Delta = Data.define(:some_ratio, :full_ratio, :elapsed)
+
+  # Calculates exact stall ratios from cumulative PSI totals.
+  class Sampler
+    def initialize(resource, cgroup: nil)
+      @resource = resource
+      @cgroup = cgroup
+    end
+
+    # Takes a sample and returns a delta after the first call.
+    # @return [Delta, nil]
+    def sample
+      reading = PSI.read(@resource, cgroup: @cgroup)
+      sampled_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return remember(reading, sampled_at) unless @previous
+
+      elapsed = sampled_at - @sampled_at
+      previous = @previous
+      remember(reading, sampled_at)
+      Delta.new(
+        some_ratio: ratio(reading.some, previous.some, elapsed),
+        full_ratio: ratio(reading.full, previous.full, elapsed),
+        elapsed: elapsed
+      )
+    end
+
+    private
+
+    def remember(reading, sampled_at)
+      @previous = reading
+      @sampled_at = sampled_at
+      nil
+    end
+
+    def ratio(current, previous, elapsed)
+      return unless current && previous
+
+      [current.total - previous.total, 0].max / (elapsed * 1_000_000)
+    end
+  end
+end

data/lib/psi/trigger.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module PSI
+  # A kernel PSI trigger tied to an open pressure file descriptor.
+  class Trigger
+    # Triggerable pressure categories.
+    KINDS = %i[some full].freeze
+
+    attr_reader :resource, :kind, :stall, :window, :cgroup
+
+    # Opens a trigger and closes it after the optional block.
+    # @return [Trigger, Object] the trigger, or the block result
+    def self.open(...)
+      trigger = new(...)
+      return trigger unless block_given?
+
+      begin
+        yield trigger
+      ensure
+        trigger.close
+      end
+    end
+
+    def initialize(resource, kind: :some, stall:, window:, cgroup: nil)
+      @resource = resource.respond_to?(:to_sym) ? resource.to_sym : resource
+      @kind = kind.respond_to?(:to_sym) ? kind.to_sym : kind
+      @stall = Float(stall)
+      @window = Float(window)
+      @cgroup = cgroup
+      validate!
+      register
+    end
+
+    def wait(timeout: nil)
+      raise Error, "trigger is closed" if closed?
+
+      !!@io.wait(IO::PRIORITY, timeout)
+    end
+
+    # Closes the descriptor and unregisters the kernel trigger.
+    # @return [nil]
+    def close
+      @io&.close unless closed?
+      nil
+    end
+
+    def closed?
+      !@io || @io.closed?
+    end
+
+    def to_io
+      raise Error, "trigger is closed" if closed?
+
+      @io
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "kind must be :some or :full" unless KINDS.include?(kind)
+      raise ArgumentError, "stall must be greater than zero" unless stall.finite? && stall_us.positive?
+      raise ArgumentError, "window must be between 0.5 and 10.0 seconds" unless window.finite? && window.between?(0.5, 10.0)
+      raise ArgumentError, "stall must not exceed window" if stall > window
+      raise ArgumentError, "cpu has no full pressure metric" if resource == :cpu && kind == :full && !cgroup
+
+      PSI.path_for(resource, cgroup: cgroup)
+      warn "PSI: cpu full pressure may be unavailable for this cgroup" if resource == :cpu && kind == :full
+    end
+
+    def register
+      @io = File.open(PSI.path_for(resource, cgroup: cgroup), File::RDWR)
+      @io.sync = true
+      @io.write("#{kind} #{stall_us} #{window_us}\n")
+    rescue Errno::ENOENT => e
+      discard_io
+      raise UnsupportedError, e.message
+    rescue Errno::EINVAL, Errno::EBUSY, Errno::ENOMEM, Errno::EOPNOTSUPP, Errno::EACCES, Errno::EPERM => e
+      discard_io
+      raise TriggerError, "cannot register #{resource} #{kind} trigger (#{e.class.name}): #{e.message}"
+    rescue StandardError
+      discard_io
+      raise
+    end
+
+    def stall_us = (stall * 1_000_000).round
+    def window_us = (window * 1_000_000).round
+
+    def discard_io
+      @io&.close
+      @io = nil
+    end
+  end
+end

data/lib/psi/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PSI
+  # Current gem version.
+  VERSION = "1.0.0"
+end

data/lib/psi.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "psi/version"
+require_relative "psi/reading"
+require_relative "psi/sampler"
+require_relative "psi/trigger"
+require_relative "psi/event"
+require_relative "psi/monitor"
+
+# Reads Linux Pressure Stall Information (PSI).
+module PSI
+  # Resource names exposed by Linux PSI.
+  RESOURCES = %i[cpu memory io irq].freeze
+
+  # Base error for PSI-specific failures.
+  class Error < StandardError; end
+  # Raised when the running kernel does not expose the requested PSI feature.
+  class UnsupportedError < Error; end
+  # Raised when the kernel rejects trigger registration.
+  class TriggerError < Error; end
+
+  class << self
+    attr_writer :procfs_root
+
+    def procfs_root
+      @procfs_root ||= "/proc"
+    end
+
+    def supported?
+      File.directory?(File.join(procfs_root, "pressure"))
+    end
+
+    # Returns resources available under the configured procfs root.
+    # @return [Array<Symbol>]
+    def resources
+      RESOURCES.select { |resource| File.file?(path_for(resource)) }
+    end
+
+    # Reads one system-wide or cgroup pressure resource.
+    # @param resource [Symbol, String]
+    # @param cgroup [String, nil] cgroup v2 directory, or nil for procfs
+    # @return [Reading]
+    def read(resource, cgroup: nil)
+      resource = validate_resource(resource)
+      Reading.parse(resource, File.read(path_for(resource, cgroup: cgroup)))
+    rescue Errno::ENOENT, Errno::EOPNOTSUPP => e
+      raise UnsupportedError, e.message
+    end
+
+    # Reads every pressure resource available at the target location.
+    # @param cgroup [String, nil] cgroup v2 directory, or nil for procfs
+    # @return [Hash{Symbol => Reading}]
+    def read_all(cgroup: nil)
+      available = cgroup ? RESOURCES.select { |resource| File.file?(path_for(resource, cgroup: cgroup)) } : resources
+      available.to_h { |resource| [resource, read(resource, cgroup: cgroup)] }
+    end
+
+    # Resolves this process's unified cgroup v2 directory.
+    # @return [String]
+    def current_cgroup
+      entry = File.foreach(File.join(procfs_root, "self/cgroup")).find { |line| line.start_with?("0::") }
+      raise UnsupportedError, "cgroup v2 is not mounted" unless entry
+
+      File.join("/sys/fs/cgroup", entry.split("::", 2).last.strip.delete_prefix("/"))
+    rescue Errno::ENOENT => e
+      raise UnsupportedError, e.message
+    end
+
+    # Builds the backing file path for a resource.
+    # @api private
+    def path_for(resource, cgroup: nil)
+      resource = validate_resource(resource)
+      return File.join(cgroup, "#{resource}.pressure") if cgroup
+
+      File.join(procfs_root, "pressure", resource.to_s)
+    end
+
+    private
+
+    def validate_resource(resource)
+      resource = resource.to_sym if resource.respond_to?(:to_sym)
+      raise ArgumentError, "unknown resource: #{resource.inspect}" unless RESOURCES.include?(resource)
+
+      resource
+    end
+  end
+end

data/sig/psi.rbs

@@ -0,0 +1,91 @@
+module PSI
+  VERSION: String
+  RESOURCES: Array[Symbol]
+
+  class Error < StandardError
+  end
+
+  class UnsupportedError < Error
+  end
+
+  class TriggerError < Error
+  end
+
+  def self.procfs_root: () -> String
+  def self.procfs_root=: (String?) -> String?
+  def self.supported?: () -> bool
+  def self.resources: () -> Array[Symbol]
+  def self.read: (Symbol | String resource, ?cgroup: String?) -> Reading
+  def self.read_all: (?cgroup: String?) -> Hash[Symbol, Reading]
+  def self.current_cgroup: () -> String
+  def self.path_for: (Symbol | String resource, ?cgroup: String?) -> String
+
+  class Metrics
+    attr_reader total: Integer
+
+    def initialize: (averages: Hash[Integer, Float], total: Integer) -> void
+    def avg: (Integer seconds) -> Float?
+    def avg10: () -> Float?
+    def avg60: () -> Float?
+    def avg300: () -> Float?
+    def to_h: () -> Hash[Symbol, Float | Integer]
+  end
+
+  class Reading
+    attr_reader resource: Symbol
+    attr_reader some: Metrics?
+    attr_reader full: Metrics?
+    attr_reader read_at: Time
+    attr_reader metrics: Hash[Symbol, Metrics]
+
+    def self.parse: (Symbol resource, String text, ?read_at: Time) -> Reading
+    def initialize: (resource: Symbol, some: Metrics?, full: Metrics?, read_at: Time, ?metrics: Hash[Symbol, Metrics]?) -> void
+  end
+
+  class Delta
+    attr_reader some_ratio: Float?
+    attr_reader full_ratio: Float?
+    attr_reader elapsed: Float
+  end
+
+  class Sampler
+    def initialize: (Symbol | String resource, ?cgroup: String?) -> void
+    def sample: () -> Delta?
+  end
+
+  class Trigger
+    attr_reader resource: Symbol
+    attr_reader kind: Symbol
+    attr_reader stall: Float
+    attr_reader window: Float
+    attr_reader cgroup: String?
+
+    def self.open: [A] (Symbol | String resource, ?kind: Symbol | String, stall: Numeric, window: Numeric, ?cgroup: String?) { (Trigger) -> A } -> A
+                  | (Symbol | String resource, ?kind: Symbol | String, stall: Numeric, window: Numeric, ?cgroup: String?) -> Trigger
+    def initialize: (Symbol | String resource, ?kind: Symbol | String, stall: Numeric, window: Numeric, ?cgroup: String?) -> void
+    def wait: (?timeout: Numeric?) -> bool
+    def close: () -> nil
+    def closed?: () -> bool
+    def to_io: () -> IO
+  end
+
+  class Event
+    attr_reader resource: Symbol
+    attr_reader kind: Symbol
+    attr_reader stall: Float
+    attr_reader window: Float
+    attr_reader reading: Reading
+    attr_reader at: Time
+
+    def initialize: (trigger: Trigger, reading: Reading, ?at: Time) -> void
+    def to_s: () -> String
+  end
+
+  class Monitor
+    def initialize: () -> void
+    def on: (Symbol | String resource, **untyped options) { (Event) -> void } -> self
+    def on_error: () { (Exception) -> void } -> self
+    def start: () -> self
+    def stop: () -> self
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: psi
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A pure Ruby API for Linux PSI readings, triggers, and monitoring.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmark/monitor_idle.rb
+- docs/poll-investigation.md
+- examples/load_shedding.rb
+- examples/prometheus_exporter.rb
+- lib/psi.rb
+- lib/psi/event.rb
+- lib/psi/monitor.rb
+- lib/psi/reading.rb
+- lib/psi/sampler.rb
+- lib/psi/trigger.rb
+- lib/psi/version.rb
+- sig/psi.rbs
+homepage: https://github.com/ydah/psi
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ydah/psi
+  source_code_uri: https://github.com/ydah/psi
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Read and monitor Linux Pressure Stall Information
+test_files: []