toggly 1.4.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d58d487720427aea654a419504c20f753656ac862aa355bf25532a97446be208
-  data.tar.gz: 60ff9681f37a920b85e25e316ffda754fb8bfe018fef1e53ea34ebbc144f437a
+  metadata.gz: 6b31072062bc817895a0fb20a5f6a46e4421af0a50ba2273822f5d0a20a16a26
+  data.tar.gz: acc89c1befd7029131935a30e4cb134481b636797d82bc0c2e8f96081ca69bf9
 SHA512:
-  metadata.gz: 2dc9099207126915eb954e3f6f8f6ce6a9d502da83e88cf9bfcd54c2574f2f4310b03b69627334d33110e5d0ff940ea0e25d33ac34c62b5cd479713b3fc6f415
-  data.tar.gz: c308b2523eea162fd10680541b103650eb07a92b7e952ad90d60e27b80fcefcc85dd7f1a27c520f03eff64681f1db69c9caf950cb383dbf824455ecce3ee4a1f
+  metadata.gz: c6d0aef5c1b1e477a2b706dd9ee29453ce87ac55fa4a39175b3be60c8a7b23c6d34d8e67eacb000aee1d5eb6f0bc4f0c0c7c9943a9d7fecc323677d3e9bccd2d
+  data.tar.gz: e6766738d5fe5eaf5b809bbf8347dfa88e8d114bcdad1eacb09cafbab579986a571417788b2472cc2ba6ded7d6abcff32695344b3ff1cff00530a72da0ac3527

data/CHANGELOG.md

@@ -5,8 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.4.2] - 2026-10-16
+## [2.0.0] - 2026-10-25
+
+### Changed
+
+- Require Ruby 3.3 or newer. Ruby 3.2 reached end of life on April 1, 2026.
 
+## [1.4.3] - 2026-10-23
+### Fixed
+- Sole-filter flags no longer default to enabled when evaluators return `nil`
+  (e.g. Targeting with a non-listed user and 0% default rollout). Sequential
+  multi-rule chains still fall through on `nil` [OPS-2011].
+- `Targeting` default rollout now matches .NET / toggly-eval / Go: `>= 100%`
+  enables without identity; `<= 0%` and partial rollout without identity fail
+  closed [OPS-2011].
+
+## [1.4.2] - 2026-10-16
+### Added
+- Opt-in `system_metrics: true` on `Toggly::Config` samples `CpuUsage`,
+  `MemoryWorkingSet`, and `ExceptionCount` every 10s when `enable_metrics` is
+  on (Fiddle `getrusage` + Linux `/proc/self/statm`) [OPS-1765].
 ### Fixed
 - Usage scopes that raise `Exception` (not only `StandardError`) record an
   error outcome instead of treating the attempt as success [OPS-1758].
@@ -14,20 +32,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   exception from `$!` and records a failure [OPS-1758].
 - `Interrupt`, `SystemExit`, and `SignalException` are attempt-only (no
   error or duration), matching the Python usage-scope contract [OPS-1758].
-
 ## [1.4.1] - 2026-10-15
-
-### Fixed
 - `UsageScopeRunner` uses `ensure` so non-local exits still record success or
   failure duration after the attempt [OPS-1758].
-
 ## [1.4.0] - 2026-10-11
-
-### Added
 - `Client#use` usage scope (attempt + duration + errors) and `VariantStats`
   wire fields `errorCount`, `durationSumMs`, `errorDurationSumMs` [OPS-1758].
-
-### Fixed
 - `Client#use` and `UsageScopeRunner.run` return the block's value [OPS-1758].
 
 ## [1.3.0] - 2026-10-04

data/README.md

@@ -87,6 +87,10 @@ gRPC metadata includes `ua` = `toggly-ruby/{VERSION}` against
 `metrics_base_url` (default `https://app.toggly.io/`). Without the optional
 `grpc` gem, evaluation still works; send is a no-op with a warning.
 
+Set `system_metrics: true` (default `false`) to sample `CpuUsage`,
+`MemoryWorkingSet`, and `ExceptionCount` every 10s when `enable_metrics` is on
+(stdlib Fiddle `getrusage` + Linux `/proc/self/statm`).
+
 ## Documentation
 
 See the [main README](../README.md) for full documentation.

data/lib/toggly/client.rb

@@ -536,6 +536,7 @@ module Toggly
         metrics_client: @config.metrics_client,
         usage_client_provided: usage_provided,
         metrics_client_provided: metrics_provided,
+        system_metrics: @config.system_metrics,
         logger: @config.logger
       )
       @telemetry.start

data/lib/toggly/config.rb

@@ -75,6 +75,9 @@ module Toggly
     # @return [Boolean] Enable business metrics (Metrics.SendMetrics)
     attr_reader :enable_metrics
 
+    # @return [Boolean] Opt-in process metrics every 10s (requires enable_metrics)
+    attr_reader :system_metrics
+
     # @return [String] Base URL for usage/metrics gRPC (default app.toggly.io)
     attr_accessor :metrics_base_url
 
@@ -120,8 +123,10 @@ module Toggly
 
       @usage_tracking_explicit = options.key?(:enable_usage_tracking)
       @metrics_explicit = options.key?(:enable_metrics)
+      @system_metrics_explicit = options.key?(:system_metrics)
       @enable_usage_tracking = options[:enable_usage_tracking] if @usage_tracking_explicit
       @enable_metrics = options[:enable_metrics] if @metrics_explicit
+      @system_metrics = options.fetch(:system_metrics, false)
       apply_telemetry_defaults!
       @metrics_base_url = normalize_url(options[:metrics_base_url] || DEFAULT_METRICS_BASE_URL)
       @usage_flush_interval = options.fetch(:usage_flush_interval, DEFAULT_TELEMETRY_FLUSH_SECONDS)
@@ -164,6 +169,11 @@ module Toggly
       @enable_metrics = value
     end
 
+    def system_metrics=(value)
+      @system_metrics_explicit = true
+      @system_metrics = value ? true : false
+    end
+
     # Apply usage/metrics defaults from the current +app_key+ and
     # +TOGGLY_DISABLE_TELEMETRY+. Explicit +enable_usage_tracking+ /
     # +enable_metrics+ assignments still win. Call after a configure block
@@ -214,6 +224,7 @@ module Toggly
         use_signed_definitions: @use_signed_definitions,
         enable_usage_tracking: @enable_usage_tracking,
         enable_metrics: @enable_metrics,
+        system_metrics: @system_metrics,
         metrics_base_url: @metrics_base_url,
         usage_flush_interval: @usage_flush_interval,
         metrics_flush_interval: @metrics_flush_interval

data/lib/toggly/evaluation_engine.rb

@@ -82,7 +82,8 @@ module Toggly
         return evaluate_filter_group(user_rules, definition.requirement_type, context, definition.feature_key, result)
       end
 
-      sequential_rules(user_rules.empty? ? definition.rules : user_rules, definition, context, result)
+      rules = user_rules.empty? ? definition.rules : user_rules
+      evaluate_filter_group(rules, definition.requirement_type, context, definition.feature_key, result)
     end
 
     def evaluate_entity_group(definition, rules, context)
@@ -96,54 +97,71 @@ module Toggly
 
     def evaluate_filter_group(rules, requirement_type, context, feature_key, result)
       req = (requirement_type || "Any").to_s
-      evaluations = rules.map do |rule|
-        rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "AlwaysOn"
-        evaluator = @registry.get(rule_type)
-        next false unless evaluator
-
-        begin
-          value = evaluator.evaluate(rule, context, feature_key: feature_key)
-          value == true
-        rescue StandardError
-          false
-        end
-      end
-      passed = req.casecmp?("All") ? evaluations.all? : evaluations.any?
-      result&.reason = passed ? "rule_matched" : "no_match" if result
-      passed
-    end
+      all_mode = req.casecmp?("All")
+      matched = false
+      matched_rule = nil
+      matched_rule_index = nil
 
-    def sequential_rules(rules, definition, context, result)
       rules.each_with_index do |rule, index|
-        rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "AlwaysOn"
-        evaluator = @registry.get(rule_type)
+        rule_passed, unknown = evaluate_filter_rule(rule, index, context, feature_key)
+        if unknown
+          if all_mode
+            result&.reason = "unknown_filter"
+            return false
+          end
+          next
+        end
 
-        unless evaluator
-          log_warn("Unknown evaluator type: #{rule_type} for feature #{definition.feature_key}")
-          result&.reason = "unknown_filter"
-          return false
+        if all_mode
+          unless rule_passed
+            result&.reason = "no_match" if result
+            return false
+          end
+          matched = true
+          matched_rule = rule
+          matched_rule_index = index
+          next
         end
 
-        begin
-          evaluation = evaluator.evaluate(rule, context, feature_key: definition.feature_key)
+        next unless rule_passed
 
-          next if evaluation.nil?
+        matched = true
+        matched_rule = rule
+        matched_rule_index = index
+        break
+      end
 
-          if result
-            result.matched_rule = rule
-            result.matched_rule_index = index
-            result.reason = "rule_matched"
-          end
+      record_filter_group_result(result, matched, matched_rule, matched_rule_index)
+      matched
+    end
 
-          return evaluation
-        rescue StandardError => e
-          log_error("Error evaluating rule #{index} for #{definition.feature_key}: #{e.message}")
-          next
-        end
+    def evaluate_filter_rule(rule, index, context, feature_key)
+      rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "AlwaysOn"
+      evaluator = @registry.get(rule_type)
+      unless evaluator
+        log_warn("Unknown evaluator type: #{rule_type} for feature #{feature_key}")
+        return [false, true]
       end
 
-      result&.reason = "default_enabled"
-      true
+      begin
+        value = evaluator.evaluate(rule, context, feature_key: feature_key)
+        [value == true, false]
+      rescue StandardError => e
+        log_error("Error evaluating filter #{index} for #{feature_key}: #{e.message}")
+        [false, false]
+      end
+    end
+
+    def record_filter_group_result(result, matched, matched_rule, matched_rule_index)
+      return unless result
+
+      if matched
+        result.matched_rule = matched_rule
+        result.matched_rule_index = matched_rule_index
+        result.reason = "rule_matched"
+      else
+        result.reason = "no_match"
+      end
     end
 
     def log_warn(message)

data/lib/toggly/evaluators/targeting.rb

@@ -22,23 +22,23 @@ module Toggly
       # @param rule [Hash] Rule with users/groups or Audience.* params
       # @param context [Context] Evaluation context
       # @param feature_key [String] The feature key
-      # @return [Boolean, nil] True if matched, false if excluded, nil to continue
+      # @return [Boolean] True if matched, false if excluded or rollout does not apply
       def evaluate(rule, context, feature_key: nil)
-        return nil unless context
+        ctx = context || Context.anonymous
 
         users = collect_users(rule)
         excluded_users = Array(rule_value(rule, "excludedUsers") || rule_value(rule, "excluded_users"))
 
-        if context.identity?
-          return false if excluded_users.any? { |u| u.to_s == context.identity }
-          return true if users.include?(context.identity)
+        if ctx.identity?
+          return false if excluded_users.any? { |u| u.to_s == ctx.identity }
+          return true if users.include?(ctx.identity)
         end
 
         groups = collect_groups(rule)
         excluded_groups = Array(rule_value(rule, "excludedGroups") || rule_value(rule, "excluded_groups"))
 
-        return false if excluded_groups.any? { |g| context.in_group?(g) }
-        return true if groups.any? { |g| context.in_group?(g) }
+        return false if excluded_groups.any? { |g| ctx.in_group?(g) }
+        return true if groups.any? { |g| ctx.in_group?(g) }
 
         default_percentage = SegmentHelpers.as_float(
           rule,
@@ -48,10 +48,11 @@ module Toggly
           "default_percentage",
           "Percentage"
         )
-        return StickyHash.compute_percentile(context.identity, feature_key.to_s) < default_percentage if default_percentage&.positive? && context.identity?
+        return false if default_percentage.nil? || default_percentage <= 0
+        return true if default_percentage >= 100
+        return false unless ctx.identity?
 
-        # No match — continue evaluation for legacy sequential rules
-        nil
+        StickyHash.compute_percentile(ctx.identity, feature_key.to_s) < default_percentage
       end
 
       private

data/lib/toggly/telemetry/runtime.rb

@@ -25,6 +25,9 @@ module Toggly
         metrics_client: nil,
         usage_client_provided: false,
         metrics_client_provided: false,
+        system_metrics: false,
+        system_metrics_sampler: nil,
+        system_metrics_interval: nil,
         logger: nil
       )
         # rubocop:enable Metrics/ParameterLists
@@ -62,6 +65,10 @@ module Toggly
         @process_start_time = Time.now.utc
         @atexit_registered = false
         @warned_missing_grpc = false
+        @system_metrics = system_metrics ? true : false
+        @system_metrics_sampler = system_metrics_sampler
+        @system_metrics_interval = system_metrics_interval
+        @system_metrics_collector = nil
       end
 
       def usage_enabled?
@@ -102,6 +109,8 @@ module Toggly
           schedule_metrics_flush if @metrics_flush_interval.positive?
         end
 
+        start_system_metrics if @enable_metrics && @system_metrics
+
         attach_exit_handlers
       end
 
@@ -173,6 +182,8 @@ module Toggly
         # Wait for flush loops (including in-flight sends) — do not Thread#kill.
         timers.each { |thread| join_timer(thread) }
 
+        stop_system_metrics
+
         begin
           flush_all
         ensure
@@ -270,6 +281,23 @@ module Toggly
       def log_error(message)
         @logger&.error("[Toggly] #{message}")
       end
+
+      def start_system_metrics
+        require_relative "system_metrics"
+        interval = @system_metrics_interval || SystemMetrics::INTERVAL_SECONDS
+        @system_metrics_collector = SystemMetrics::Collector.new(
+          observe: method(:observe),
+          sampler: @system_metrics_sampler,
+          interval: interval
+        )
+        @system_metrics_collector.start
+      end
+
+      def stop_system_metrics
+        collector = @system_metrics_collector
+        @system_metrics_collector = nil
+        collector&.stop
+      end
     end
   end
 end

data/lib/toggly/telemetry/system_metrics.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "etc"
+
+begin
+  require "fiddle"
+rescue LoadError
+  # Optional: getrusage sampling is skipped when fiddle is unavailable.
+end
+
+module Toggly
+  module Telemetry
+    # Opt-in process metrics (CpuUsage, MemoryWorkingSet, ExceptionCount).
+    module SystemMetrics
+      INTERVAL_SECONDS = 10.0
+
+      # FFI helpers for getrusage-based CPU and RSS samples.
+      module RusageFFI
+        module_function
+
+        def read_rusage
+          return nil unless defined?(@getrusage) && @getrusage
+
+          # RUBY_FREE auto-releases when the pointer is GC'd / goes out of scope.
+          freer = defined?(Fiddle::RUBY_FREE) ? Fiddle::RUBY_FREE : nil
+          ptr = if freer
+                  Fiddle::Pointer.malloc(Fiddle::SIZEOF_LONG * 18, freer)
+                else
+                  Fiddle::Pointer.malloc(Fiddle::SIZEOF_LONG * 18)
+                end
+          begin
+            return nil if @getrusage.call(RUSAGE_SELF, ptr) != 0
+
+            utime_sec = ptr[0, Fiddle::SIZEOF_LONG].unpack1("l!")
+            utime_usec = ptr[Fiddle::SIZEOF_LONG, Fiddle::SIZEOF_LONG].unpack1("l!")
+            stime_sec = ptr[2 * Fiddle::SIZEOF_LONG, Fiddle::SIZEOF_LONG].unpack1("l!")
+            stime_usec = ptr[3 * Fiddle::SIZEOF_LONG, Fiddle::SIZEOF_LONG].unpack1("l!")
+            maxrss = ptr[4 * Fiddle::SIZEOF_LONG, Fiddle::SIZEOF_LONG].unpack1("l!")
+            {
+              user_us: (utime_sec * 1_000_000) + utime_usec,
+              sys_us: (stime_sec * 1_000_000) + stime_usec,
+              maxrss: maxrss
+            }
+          ensure
+            if freer.nil? && ptr
+              if ptr.respond_to?(:call_free)
+                ptr.call_free
+              elsif ptr.respond_to?(:free) && ptr.free.respond_to?(:call)
+                ptr.free.call(ptr)
+              end
+            end
+          end
+        rescue StandardError
+          nil
+        end
+
+        RUSAGE_SELF = 0
+        begin
+          libc = Fiddle.dlopen(nil)
+          @getrusage = Fiddle::Function.new(
+            libc["getrusage"],
+            [Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          )
+        rescue StandardError
+          @getrusage = nil
+        end
+      end
+
+      # Periodic sampler that posts gauges through the provided observe callback.
+      class Collector
+        def initialize(observe:, sampler: nil, interval: INTERVAL_SECONDS)
+          @observe = observe
+          @sampler = sampler
+          @interval = interval.to_f
+          @mutex = Mutex.new
+          @exception_count = 0
+          @last_cpu = nil
+          @thread = nil
+          @closed = false
+          @trace = nil
+          @ended_threads = []
+          install_exception_handler
+        end
+
+        def start
+          return if @thread&.alive?
+
+          @closed = false
+          @thread = Thread.new { run_loop }
+          @thread.abort_on_exception = false
+        end
+
+        def stop
+          @mutex.synchronize { @closed = true }
+          @thread&.wakeup if @thread&.alive?
+          @thread&.join(2.0) if @thread&.alive?
+          @thread = nil
+          disable_exception_handler
+        end
+
+        def tick
+          return if @closed
+
+          drain_ended_threads
+          samples = @sampler ? @sampler.call : default_sample
+          samples.each do |metric, value|
+            next unless value.is_a?(Numeric) && value.finite? && value >= 0
+
+            @observe.call(metric, value.to_f)
+          end
+          exceptions = @mutex.synchronize do
+            count = @exception_count
+            @exception_count = 0
+            count
+          end
+          @observe.call("ExceptionCount", exceptions.to_f) if exceptions.positive?
+        rescue StandardError
+          # Never disrupt the host process.
+        end
+
+        private
+
+        def run_loop
+          loop do
+            sleep(@interval)
+            break if @mutex.synchronize { @closed }
+
+            tick
+          end
+        end
+
+        def default_sample
+          out = []
+          cpu = sample_cpu
+          out << ["CpuUsage", cpu] if cpu
+          mem = sample_memory_working_set
+          out << ["MemoryWorkingSet", mem] if mem
+          out
+        end
+
+        def sample_cpu
+          ru = RusageFFI.read_rusage
+          return nil unless ru
+
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          user_us = ru[:user_us]
+          sys_us = ru[:sys_us]
+          prev = @mutex.synchronize do
+            p = @last_cpu
+            @last_cpu = { user_us: user_us, sys_us: sys_us, at: now }
+            p
+          end
+          return nil unless prev
+
+          wall_us = [(now - prev[:at]) * 1_000_000, 1].max
+          cpu_us = (user_us - prev[:user_us]) + (sys_us - prev[:sys_us])
+          return nil if cpu_us.negative?
+
+          n_cpu = [Etc.nprocessors, 1].max
+          pct = (cpu_us.to_f / wall_us / n_cpu) * 100.0
+          return nil unless pct.finite? && pct >= 0
+
+          [pct, 100.0].min
+        end
+
+        def sample_memory_working_set
+          if (rss = read_linux_statm_rss)
+            return rss.to_f
+          end
+
+          ru = RusageFFI.read_rusage
+          return nil unless ru && ru[:maxrss].to_i.positive?
+
+          rss = ru[:maxrss]
+          rss *= 1024 if RUBY_PLATFORM.include?("linux")
+          rss.to_f
+        end
+
+        def read_linux_statm_rss
+          return nil unless RUBY_PLATFORM.include?("linux")
+
+          line = File.read("/proc/self/statm").split
+          pages = line[1].to_i
+          page_size = begin
+            if Process.respond_to?(:getpagesize)
+              Process.getpagesize
+            elsif defined?(Etc::SC_PAGESIZE)
+              Etc.sysconf(Etc::SC_PAGESIZE)
+            elsif defined?(Etc::SC_PAGE_SIZE)
+              Etc.sysconf(Etc::SC_PAGE_SIZE)
+            else
+              Integer(ENV.fetch("PAGESIZE", 4096))
+            end
+          rescue StandardError
+            4096
+          end
+          pages * page_size
+        rescue StandardError
+          nil
+        end
+
+        def install_exception_handler
+          return if @trace
+
+          # Do not call Thread#join/#value inside TracePoint — that raises
+          # ThreadError for normal exits. Queue ended threads and inspect on tick.
+          @trace = TracePoint.new(:thread_end) do |tp|
+            thread = tp.self
+            next if thread == Thread.main
+            next if thread.status == "aborting"
+
+            @mutex.synchronize { @ended_threads << thread }
+          end
+          @trace.enable
+        end
+
+        def drain_ended_threads
+          ended = @mutex.synchronize do
+            list = @ended_threads
+            @ended_threads = []
+            list
+          end
+          ended.each do |thread|
+            thread.value
+          rescue StandardError, ScriptError
+            @mutex.synchronize { @exception_count += 1 }
+          rescue Exception # rubocop:disable Lint/RescueException
+            nil
+          end
+        end
+
+        def disable_exception_handler
+          return unless @trace
+
+          @trace.disable
+          @trace = nil
+          drain_ended_threads
+        end
+      end
+    end
+  end
+end

data/lib/toggly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toggly
-  VERSION = "1.4.2"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby SDK for Toggly feature flag management. Works with
   or without Toggly.io.
@@ -66,6 +66,7 @@ files:
 - lib/toggly/telemetry/pb/usage_services_pb.rb
 - lib/toggly/telemetry/runtime.rb
 - lib/toggly/telemetry/runtime_flush.rb
+- lib/toggly/telemetry/system_metrics.rb
 - lib/toggly/telemetry/usage_batcher.rb
 - lib/toggly/telemetry/usage_scope.rb
 - lib/toggly/user_agent_parser.rb
@@ -92,7 +93,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="