visionary-sdk 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d9bc46402d28b75e7053fcfa03ac8161a77701c23ba450641dda44385a4e9c9
-  data.tar.gz: f516ea1508f97c1ad0d7729013fcd400f8de25768338438d658d7c7d01dde94e
+  metadata.gz: d5db5f7ee39c2f5a3f6bb1e45851b7add7033d3eecbc6cbcf514dd800f747bc1
+  data.tar.gz: f9e1c6ef1391e5780d3d3a0419c375b5c014ce2a3281cdfc71ba76582a258797
 SHA512:
-  metadata.gz: 86c78e45acd34ee3c5fd8bb0733618a7eb9957bc1b1a2cb9ad18c0160504bcbbddf0f49873acd8a16509aaa0062e144f8273b13196d9f6267696ff772256b4ac
-  data.tar.gz: 2f750c54be572e26ec4ebcdfc670d69de77a172003bbdf5613e0935514b9f46cdcea91ca327ca7d8dbe24c80e981348e01a7940ef7610e6bb68822c3c5361dd2
+  metadata.gz: 1d651e697211f0989b533ab906304c339de432252ff60080bd9f626215f533611ea95f8197438bb507ffc688fe16cecb0ac8450ab79ff7c672570609e22c407b
+  data.tar.gz: 85a4320df09ff95498f6e8c06a6ab26bcce6adc1a9941169d0b52af5222501be5fcd3f60f6affa8b5c25b8914c8abce02e89ad38ed898310201ca32b0fdb9364

data/README.md

@@ -169,6 +169,9 @@ from `GC.stat`, heap from `GC.stat` slot and page counts, threads from
 `/proc/self/status` (else `Thread.list`). Pool columns come from the
 ActiveRecord pool when it exists, or from `c.db_stats = -> { { total:, idle:,
 in_use:, max: } }`. On macOS and Windows most host columns are NULL.
+In a container (or a cgroup with a CPU or memory limit) the `container_*`
+columns come from the process's own cgroup, v2 or v1: CPU used, limit and
+throttling, memory used (without inactive page cache) and limit, OOM kills.
 
 ## Configuration
 

data/lib/visionary/schema/mysql/system.sql

@@ -66,11 +66,17 @@ CREATE TABLE IF NOT EXISTS system_metrics (
     ctx_switches_ps    DOUBLE,
     proc_read_kbps     DOUBLE,
     proc_write_kbps    DOUBLE,
-    proc_max_fds       BIGINT
-    service            VARCHAR(255),
-    version            VARCHAR(255),
-    sdk                VARCHAR(255),
-    runtime            VARCHAR(255)
+    proc_max_fds       BIGINT
+    service            VARCHAR(255),
+    version            VARCHAR(255),
+    sdk                VARCHAR(255),
+    runtime            VARCHAR(255),
+    container_cpu_cores DOUBLE,
+    container_cpu_limit DOUBLE,
+    container_cpu_throttled_percent DOUBLE,
+    container_mem_used_mb DOUBLE,
+    container_mem_limit_mb DOUBLE,
+    container_oom_kills BIGINT
 ) CHARACTER SET utf8mb4;
 CREATE INDEX idx_system_metrics_created_at ON system_metrics (created_at);
 CREATE INDEX idx_system_metrics_instance_created ON system_metrics (instance, created_at);

data/lib/visionary/schema/postgres/system.sql

@@ -66,11 +66,17 @@ CREATE TABLE IF NOT EXISTS system_metrics (
     ctx_switches_ps    DOUBLE PRECISION,
     proc_read_kbps     DOUBLE PRECISION,
     proc_write_kbps    DOUBLE PRECISION,
-    proc_max_fds       BIGINT
-    service            TEXT,
-    version            TEXT,
-    sdk                TEXT,
-    runtime            TEXT
+    proc_max_fds       BIGINT
+    service            TEXT,
+    version            TEXT,
+    sdk                TEXT,
+    runtime            TEXT,
+    container_cpu_cores DOUBLE PRECISION,
+    container_cpu_limit DOUBLE PRECISION,
+    container_cpu_throttled_percent DOUBLE PRECISION,
+    container_mem_used_mb DOUBLE PRECISION,
+    container_mem_limit_mb DOUBLE PRECISION,
+    container_oom_kills BIGINT
 );
 CREATE INDEX IF NOT EXISTS idx_system_metrics_created_at ON system_metrics (created_at);
 CREATE INDEX IF NOT EXISTS idx_system_metrics_instance_created ON system_metrics (instance, created_at);

data/lib/visionary/schema/sqlite/system.sql

@@ -66,11 +66,17 @@ CREATE TABLE IF NOT EXISTS system_metrics (
     ctx_switches_ps    REAL,
     proc_read_kbps     REAL,
     proc_write_kbps    REAL,
-    proc_max_fds       INTEGER
-    service            TEXT,
-    version            TEXT,
-    sdk                TEXT,
-    runtime            TEXT
+    proc_max_fds       INTEGER
+    service            TEXT,
+    version            TEXT,
+    sdk                TEXT,
+    runtime            TEXT,
+    container_cpu_cores REAL,
+    container_cpu_limit REAL,
+    container_cpu_throttled_percent REAL,
+    container_mem_used_mb REAL,
+    container_mem_limit_mb REAL,
+    container_oom_kills INTEGER
 );
 CREATE INDEX IF NOT EXISTS idx_system_metrics_created_at ON system_metrics (created_at);
 CREATE INDEX IF NOT EXISTS idx_system_metrics_instance_created ON system_metrics (instance, created_at);

data/lib/visionary/schema.rb

@@ -47,7 +47,10 @@ module Visionary
       %w[host_procs int], %w[procs_running int], %w[procs_blocked int],
       %w[ctx_switches_ps real], %w[proc_read_kbps real], %w[proc_write_kbps real],
       %w[proc_max_fds int], %w[service text], %w[version text],
-      %w[sdk text], %w[runtime text]
+      %w[sdk text], %w[runtime text],
+      %w[container_cpu_cores real], %w[container_cpu_limit real],
+      %w[container_cpu_throttled_percent real], %w[container_mem_used_mb real],
+      %w[container_mem_limit_mb real], %w[container_oom_kills int]
     ].freeze
 
     SPAN_COLUMNS = %w[

data/lib/visionary/system/cgroup.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Visionary
+  module System
+    # Reads the CPU and memory limits and use of the process's own cgroup
+    # (Linux, v2 or v1): in a container these are the numbers that matter,
+    # since the host columns describe the whole machine underneath. The
+    # container_* columns are filled only in a container, or when the cgroup
+    # sets a CPU or memory limit (a systemd unit with MemoryMax=, say).
+    class Cgroup
+      MB = 1024.0 * 1024
+      MARKERS = %w[docker kubepods containerd libpod lxc].freeze
+      # Variables container platforms set in every container: Kubernetes,
+      # Railway, Render, Heroku, Cloud Run, ECS/Fargate and Azure Container Apps.
+      CONTAINER_ENV = %w[KUBERNETES_SERVICE_HOST RAILWAY_SERVICE_ID RENDER_SERVICE_ID DYNO K_SERVICE ECS_CONTAINER_METADATA_URI_V4 CONTAINER_APP_NAME].freeze
+
+      # The process's cgroup; nil off Linux or when there is none to read.
+      # root and env are for tests.
+      def self.detect(root: "/", env: ENV)
+        return nil unless Sources::LINUX || root != "/"
+        text = Sources.read(File.join(root, "proc/self/cgroup")) or return nil
+        c = new(root, text, env)
+        c.cpu_dir || c.mem_dir ? c : nil
+      end
+
+      attr_reader :cpu_dir, :mem_dir
+
+      def initialize(root, text, env)
+        @root = root
+        @in_ctr = in_container?(text, env)
+        @v2 = false
+        @cpu_dir = @cpu_acct = @mem_dir = nil
+        text.strip.each_line do |line|
+          id, ctrls, path = line.chomp.split(":", 3)
+          next if path.nil?
+          list = ctrls.split(",")
+          if id == "0" && ctrls.empty?
+            dir = dir_for("sys/fs/cgroup", path)
+            if File.exist?(File.join(dir, "cpu.stat"))
+              @v2 = true
+              @cpu_dir = @mem_dir = dir
+              break
+            end
+          elsif list.include?("memory")
+            @mem_dir = dir_for("sys/fs/cgroup/memory", path)
+          elsif list.include?("cpu") || list.include?("cpuacct")
+            dir = dir_for("sys/fs/cgroup/#{ctrls}", path)
+            @cpu_dir = dir if list.include?("cpu")
+            @cpu_acct = dir if list.include?("cpuacct")
+          end
+        end
+        @primed = false
+      end
+
+      # The baseline the first sample's deltas start from.
+      def prime
+        @usage, @periods, @throttled, @ooms = counters
+        @last = mono
+        @primed = true
+      end
+
+      # Fills the container_* columns of v.
+      def sample(v)
+        cpus, mem_limit = limits
+        return if !@in_ctr && cpus.zero? && mem_limit.zero?
+        now = mono
+        usage, periods, throttled, ooms = counters
+        secs = @primed ? now - @last : 0
+        if secs.positive? && usage >= @usage
+          v["container_cpu_cores"] = ((usage - @usage) / 1e9 / secs).round(3)
+          if periods > @periods && throttled >= @throttled
+            v["container_cpu_throttled_percent"] = (100.0 * (throttled - @throttled) / (periods - @periods)).round(1)
+          elsif cpus.positive?
+            v["container_cpu_throttled_percent"] = 0.0
+          end
+          v["container_oom_kills"] = ooms - @ooms if ooms && @ooms && ooms >= @ooms
+        end
+        @usage, @periods, @throttled, @ooms = usage, periods, throttled, ooms
+        @last = now
+        @primed = true
+        v["container_cpu_limit"] = cpus.round(2) if cpus.positive?
+        if (used = mem_used)
+          v["container_mem_used_mb"] = (used / MB).round(1)
+        end
+        v["container_mem_limit_mb"] = (mem_limit / MB).round(1) if mem_limit.positive?
+      end
+
+      private
+
+      def mono = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def path(*parts) = File.join(@root, *parts)
+
+      # The cgroup's directory under a controller's mount. Inside a
+      # container's cgroup namespace the path is "/", and with a private mount
+      # the host path does not exist below it, so the mount itself is the
+      # cgroup.
+      def dir_for(mount, cgroup_path)
+        dir = File.join(@root, mount, cgroup_path)
+        File.directory?(dir) ? dir : File.join(@root, mount)
+      end
+
+      # Tells a container from a process on the host by the runtimes' marker
+      # files, the platforms' variables and the cgroup path.
+      def in_container?(text, env)
+        File.exist?(path(".dockerenv")) || File.exist?(path("run/.containerenv")) ||
+          CONTAINER_ENV.any? { |k| !env[k].to_s.empty? } || MARKERS.any? { |k| text.include?(k) }
+      end
+
+      def read_int(file)
+        s = Sources.read(file)&.strip
+        s&.match?(/\A\d+\z/) ? s.to_i : nil
+      end
+
+      # "key value" lines (cpu.stat, memory.stat, memory.events).
+      def read_kv(file)
+        out = {}
+        Sources.read(file)&.each_line do |line|
+          k, n, extra = line.split
+          out[k] = n.to_i if extra.nil? && n&.match?(/\A\d+\z/)
+        end
+        out
+      end
+
+      # The CPU limit in cores and the memory limit in bytes, 0 when
+      # unlimited.
+      def limits
+        cpus = 0.0
+        mem = 0
+        if @v2
+          q, p = Sources.read(File.join(@cpu_dir, "cpu.max"))&.split
+          cpus = q.to_f / p.to_f if q && q != "max" && p.to_f.positive?
+          mem = read_int(File.join(@mem_dir, "memory.max")) || 0 # "max": 0
+          return [cpus, mem]
+        end
+        if @cpu_dir
+          q = Sources.read(File.join(@cpu_dir, "cpu.cfs_quota_us")).to_s.strip.to_i
+          p = read_int(File.join(@cpu_dir, "cpu.cfs_period_us"))
+          cpus = q.to_f / p if q.positive? && p&.positive?
+        end
+        if @mem_dir
+          # v1 writes a page-rounded maximum int64 for no limit.
+          m = read_int(File.join(@mem_dir, "memory.limit_in_bytes"))
+          mem = m if m && m < 2**62
+        end
+        [cpus, mem]
+      end
+
+      # The cumulative CPU time (ns), CFS periods, throttled periods and OOM
+      # kills (nil where the kernel doesn't count them).
+      def counters
+        if @v2
+          st = read_kv(File.join(@cpu_dir, "cpu.stat"))
+          ev = read_kv(File.join(@mem_dir, "memory.events"))
+          return [st["usage_usec"].to_i * 1000, st["nr_periods"].to_i, st["nr_throttled"].to_i, ev["oom_kill"]]
+        end
+        usage = @cpu_acct ? read_int(File.join(@cpu_acct, "cpuacct.usage")).to_i : 0
+        st = @cpu_dir ? read_kv(File.join(@cpu_dir, "cpu.stat")) : {}
+        ooms = @mem_dir ? read_kv(File.join(@mem_dir, "memory.oom_control"))["oom_kill"] : nil
+        [usage, st["nr_periods"].to_i, st["nr_throttled"].to_i, ooms]
+      end
+
+      # Memory in use without the inactive page cache, as docker stats
+      # counts it.
+      def mem_used
+        return nil unless @mem_dir
+        file, key = @v2 ? %w[memory.current inactive_file] : %w[memory.usage_in_bytes total_inactive_file]
+        used = read_int(File.join(@mem_dir, file)) or return nil
+        inactive = read_kv(File.join(@mem_dir, "memory.stat"))[key]
+        inactive && inactive < used ? used - inactive : used
+      end
+    end
+  end
+end

data/lib/visionary/system/recorder.rb

@@ -90,6 +90,7 @@ module Visionary
         v["version"] = @cfg.version
         v["sdk"] = "ruby"
         v["runtime"] = Telemetry.runtime
+        @cgroup&.sample(v)
         Schema::TABLES["system_metrics"].map { |c| v[c] }
       end
 
@@ -119,6 +120,8 @@ module Visionary
         @gc_ms_prev = heap[:gc_ms]
         @db_prev = db_stats || {}
         @prev = read_counters(stat, Sources::LINUX ? Sources.tcp : {})
+        @cgroup = Cgroup.detect # nil off Linux
+        @cgroup&.prime
       end
 
       def run

data/lib/visionary/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Visionary
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/visionary.rb

@@ -11,6 +11,7 @@ require_relative "visionary/queue"
 require_relative "visionary/writer"
 require_relative "visionary/retention"
 require_relative "visionary/system/sources"
+require_relative "visionary/system/cgroup"
 require_relative "visionary/system/recorder"
 require_relative "visionary/telemetry"
 require_relative "visionary/telemetry/hooks"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: visionary-sdk
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - styropyr0
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies: []
 description: |
   The Ruby collector for Visionary. A Rack middleware (with a Railtie for Rails)
@@ -49,6 +49,7 @@ files:
 - lib/visionary/store/active_record.rb
 - lib/visionary/store/d1.rb
 - lib/visionary/store/sql.rb
+- lib/visionary/system/cgroup.rb
 - lib/visionary/system/recorder.rb
 - lib/visionary/system/sources.rb
 - lib/visionary/telemetry.rb