toggly 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e7e0a87a56b437ad26a416ec236125cdffab5f1ed3ac0a65260da717c58c04d
-  data.tar.gz: 4e3a36875f88ee85dbe81ae51cb72226b97cd3951d8034ddf600d2f8a5ce8da6
+  metadata.gz: 6b31072062bc817895a0fb20a5f6a46e4421af0a50ba2273822f5d0a20a16a26
+  data.tar.gz: acc89c1befd7029131935a30e4cb134481b636797d82bc0c2e8f96081ca69bf9
 SHA512:
-  metadata.gz: 0e8ddc1874675e6536462478a8245f964470951cede5dae334c13383cd34af96627a6be8a1f8778eb0b2941dc74433714113b85167f88a472ff88d7e1b763094
-  data.tar.gz: d743ba544845147aff474191418ab201a3945c3e8edad5ccb78d34364d175a8a8aa1b0cf38ac5c3122f95517670b75416261821b5dd75d214fe0d3483b789a72
+  metadata.gz: c6d0aef5c1b1e477a2b706dd9ee29453ce87ac55fa4a39175b3be60c8a7b23c6d34d8e67eacb000aee1d5eb6f0bc4f0c0c7c9943a9d7fecc323677d3e9bccd2d
+  data.tar.gz: e6766738d5fe5eaf5b809bbf8347dfa88e8d114bcdad1eacb09cafbab579986a571417788b2472cc2ba6ded7d6abcff32695344b3ff1cff00530a72da0ac3527

data/CHANGELOG.md

@@ -5,6 +5,41 @@ 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).
 
+## [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].
+- A clean usage scope nested in an outer `rescue` no longer inherits that
+  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
+- `UsageScopeRunner` uses `ensure` so non-local exits still record success or
+  failure duration after the attempt [OPS-1758].
+## [1.4.0] - 2026-10-11
+- `Client#use` usage scope (attempt + duration + errors) and `VariantStats`
+  wire fields `errorCount`, `durationSumMs`, `errorDurationSumMs` [OPS-1758].
+- `Client#use` and `UsageScopeRunner.run` return the block's value [OPS-1758].
+
 ## [1.3.0] - 2026-10-04
 
 ### Added

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

@@ -273,6 +273,24 @@ module Toggly
       @telemetry.record_usage(feature_key.to_s, identity, variant: variant)
     end
 
+    # Run a block inside a usage scope (attempt + duration + errors). Does not evaluate the flag.
+    #
+    # @yieldparam scope [Telemetry::FeatureUsageScope]
+    def use(feature_key, identity: nil, variant: "enabled", &)
+      key = feature_key.to_s
+      resolved_identity = identity.nil? ? variant_user_id(nil) : identity
+      handlers = [
+        -> { @telemetry&.record_usage(key, resolved_identity, variant: variant) },
+        ->(ms) { @telemetry&.record_usage_scope_success(key, ms, variant: variant) },
+        ->(ms) { @telemetry&.record_usage_scope_failure(key, ms, variant: variant) }
+      ]
+      if @telemetry.nil? || !@telemetry.usage_enabled?
+        scope = Telemetry::FeatureUsageScope.new
+        return yield scope
+      end
+      Telemetry::UsageScopeRunner.run(handlers, &)
+    end
+
     # Record a feature viewed/rendered event
     #
     # @param feature_key [String, Symbol]
@@ -518,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/grpc_clients.rb

@@ -231,7 +231,10 @@ module Toggly
               checkCount: vs[:checkCount].to_i,
               requestCount: vs[:requestCount].to_i,
               usedCount: vs[:usedCount].to_i,
-              viewedCount: vs[:viewedCount].to_i
+              viewedCount: vs[:viewedCount].to_i,
+              errorCount: vs[:errorCount].to_i,
+              durationSumMs: vs[:durationSumMs].to_i,
+              errorDurationSumMs: vs[:errorDurationSumMs].to_i
             )
           end
           sm

data/lib/toggly/telemetry/pb/usage_pb.rb

@@ -8,7 +8,7 @@
 require "google/protobuf"
 require "google/protobuf/timestamp_pb"
 
-descriptor_data = "\n\x0busage.proto\x12\x05Usage\x1a\x1fgoogle/protobuf/timestamp.proto\"\xcf\x03\n\x0b\x46\x65\x61tureStat\x12\x0e\n\x06\x61ppKey\x18\x01 \x01(\t\x12\x13\n\x0b\x65nvironment\x18\x02 \x01(\t\x12(\n\x04time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12!\n\x05stats\x18\x04 \x03(\x0b\x32\x12.Usage.StatMessage\x12\x18\n\x10totalUniqueUsers\x18\x05 \x01(\x05\x12\x19\n\x0cinstanceName\x18\x06 \x01(\tH\x00\x88\x01\x01\x12\x39\n\x10processStartTime\x18\x07 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x01\x88\x01\x01\x12\x17\n\nappVersion\x18\x08 \x01(\tH\x02\x88\x01\x01\x12\x18\n\x10uniqueUserHashes\x18\t \x03(\x05\x12 \n\x13\x64\x65\x66initionCacheHits\x18\n \x01(\x05H\x03\x88\x01\x01\x12\"\n\x15\x64\x65\x66initionCacheMisses\x18\x0b \x01(\x05H\x04\x88\x01\x01\x42\x0f\n\r_instanceNameB\x13\n\x11_processStartTimeB\r\n\x0b_appVersionB\x16\n\x14_definitionCacheHitsB\x18\n\x16_definitionCacheMisses\"\xf2\x03\n\x0bStatMessage\x12\x0f\n\x07\x66\x65\x61ture\x18\x01 \x01(\t\x12\x18\n\x0c\x65nabledCount\x18\x02 \x01(\x05\x42\x02\x18\x01\x12\x19\n\rdisabledCount\x18\x03 \x01(\x05\x42\x02\x18\x01\x12+\n#uniqueContextIdentifierEnabledCount\x18\x04 \x01(\x05\x12,\n$uniqueContextIdentifierDisabledCount\x18\x05 \x01(\x05\x12%\n\x19uniqueRequestEnabledCount\x18\x06 \x01(\x05\x42\x02\x18\x01\x12&\n\x1auniqueRequestDisabledCount\x18\x07 \x01(\x05\x42\x02\x18\x01\x12\x15\n\tusedCount\x18\x08 \x01(\x05\x42\x02\x18\x01\x12\x1c\n\x14uniqueUsersUsedCount\x18\t \x01(\x05\x12\x18\n\x10uniqueUserHashes\x18\n \x03(\x05\x12:\n\x0cvariantStats\x18\x0b \x03(\x0b\x32$.Usage.StatMessage.VariantStatsEntry\x12\x1e\n\x16uniqueViewedUserHashes\x18\x0c \x03(\x05\x1aH\n\x11VariantStatsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\"\n\x05value\x18\x02 \x01(\x0b\x32\x13.Usage.VariantStats:\x02\x38\x01\"`\n\x0cVariantStats\x12\x12\n\ncheckCount\x18\x01 \x01(\x05\x12\x14\n\x0crequestCount\x18\x02 \x01(\x05\x12\x11\n\tusedCount\x18\x03 \x01(\x05\x12\x13\n\x0bviewedCount\x18\x04 \x01(\x05\"\"\n\nStatResult\x12\x14\n\x0c\x66\x65\x61tureCount\x18\x01 \x01(\x05\x32;\n\x05Usage\x12\x32\n\tSendStats\x12\x12.Usage.FeatureStat\x1a\x11.Usage.StatResultBKZIgithub.com/ops-ai/Toggly.FeatureManagement/toggly-go/toggly/usage/usagepbb\x06proto3"
+descriptor_data = "\n\x0busage.proto\x12\x05Usage\x1a\x1fgoogle/protobuf/timestamp.proto\"\xcf\x03\n\x0b\x46\x65\x61tureStat\x12\x0e\n\x06\x61ppKey\x18\x01 \x01(\t\x12\x13\n\x0b\x65nvironment\x18\x02 \x01(\t\x12(\n\x04time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12!\n\x05stats\x18\x04 \x03(\x0b\x32\x12.Usage.StatMessage\x12\x18\n\x10totalUniqueUsers\x18\x05 \x01(\x05\x12\x19\n\x0cinstanceName\x18\x06 \x01(\tH\x00\x88\x01\x01\x12\x39\n\x10processStartTime\x18\x07 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x01\x88\x01\x01\x12\x17\n\nappVersion\x18\x08 \x01(\tH\x02\x88\x01\x01\x12\x18\n\x10uniqueUserHashes\x18\t \x03(\x05\x12 \n\x13\x64\x65\x66initionCacheHits\x18\n \x01(\x05H\x03\x88\x01\x01\x12\"\n\x15\x64\x65\x66initionCacheMisses\x18\x0b \x01(\x05H\x04\x88\x01\x01\x42\x0f\n\r_instanceNameB\x13\n\x11_processStartTimeB\r\n\x0b_appVersionB\x16\n\x14_definitionCacheHitsB\x18\n\x16_definitionCacheMisses\"\xf2\x03\n\x0bStatMessage\x12\x0f\n\x07\x66\x65\x61ture\x18\x01 \x01(\t\x12\x18\n\x0c\x65nabledCount\x18\x02 \x01(\x05\x42\x02\x18\x01\x12\x19\n\rdisabledCount\x18\x03 \x01(\x05\x42\x02\x18\x01\x12+\n#uniqueContextIdentifierEnabledCount\x18\x04 \x01(\x05\x12,\n$uniqueContextIdentifierDisabledCount\x18\x05 \x01(\x05\x12%\n\x19uniqueRequestEnabledCount\x18\x06 \x01(\x05\x42\x02\x18\x01\x12&\n\x1auniqueRequestDisabledCount\x18\x07 \x01(\x05\x42\x02\x18\x01\x12\x15\n\tusedCount\x18\x08 \x01(\x05\x42\x02\x18\x01\x12\x1c\n\x14uniqueUsersUsedCount\x18\t \x01(\x05\x12\x18\n\x10uniqueUserHashes\x18\n \x03(\x05\x12:\n\x0cvariantStats\x18\x0b \x03(\x0b\x32$.Usage.StatMessage.VariantStatsEntry\x12\x1e\n\x16uniqueViewedUserHashes\x18\x0c \x03(\x05\x1aH\n\x11VariantStatsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\"\n\x05value\x18\x02 \x01(\x0b\x32\x13.Usage.VariantStats:\x02\x38\x01\"\xa7\x01\n\x0cVariantStats\x12\x12\n\ncheckCount\x18\x01 \x01(\x05\x12\x14\n\x0crequestCount\x18\x02 \x01(\x05\x12\x11\n\tusedCount\x18\x03 \x01(\x05\x12\x13\n\x0bviewedCount\x18\x04 \x01(\x05\x12\x12\n\nerrorCount\x18\x05 \x01(\x05\x12\x15\n\rdurationSumMs\x18\x06 \x01(\x03\x12\x1a\n\x12\x65rrorDurationSumMs\x18\x07 \x01(\x03\"\"\n\nStatResult\x12\x14\n\x0c\x66\x65\x61tureCount\x18\x01 \x01(\x05\x32;\n\x05Usage\x12\x32\n\tSendStats\x12\x12.Usage.FeatureStat\x1a\x11.Usage.StatResultBKZIgithub.com/ops-ai/Toggly.FeatureManagement/toggly-go/toggly/usage/usagepbb\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)

data/lib/toggly/telemetry/pb/usage_services_pb.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# Generated by the protocol buffer compiler. DO NOT EDIT!
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
 # Source: usage.proto for package 'Usage'
 
 require "grpc"

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
 
@@ -120,6 +129,19 @@ module Toggly
         batcher&.record_view(feature, identity, variant: variant)
       end
 
+      def record_usage_scope_success(feature, duration_ms, variant: "enabled")
+        batcher = @mutex.synchronize { @usage_batcher }
+        batcher&.record_usage_duration(feature, duration_ms, variant: variant, failed: false)
+      end
+
+      def record_usage_scope_failure(feature, duration_ms, variant: "enabled")
+        batcher = @mutex.synchronize { @usage_batcher }
+        return unless batcher
+
+        batcher.record_usage_error(feature, variant: variant)
+        batcher.record_usage_duration(feature, duration_ms, variant: variant, failed: true)
+      end
+
       def record_definition_cache_hit
         batcher = @mutex.synchronize { @usage_batcher }
         batcher&.record_definition_cache_hit
@@ -160,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
@@ -257,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/telemetry/usage_batcher.rb

@@ -4,8 +4,25 @@ module Toggly
   module Telemetry
     # In-memory feature usage aggregator (Usage.SendStats payload shape).
     class UsageBatcher
-      VariantStatsAgg = Struct.new(:check_count, :request_count, :used_count, :viewed_count, keyword_init: true) do
-        def initialize(check_count: 0, request_count: 0, used_count: 0, viewed_count: 0)
+      VariantStatsAgg = Struct.new(
+        :check_count,
+        :request_count,
+        :used_count,
+        :viewed_count,
+        :error_count,
+        :duration_sum_ms,
+        :error_duration_sum_ms,
+        keyword_init: true
+      ) do
+        def initialize(
+          check_count: 0,
+          request_count: 0,
+          used_count: 0,
+          viewed_count: 0,
+          error_count: 0,
+          duration_sum_ms: 0,
+          error_duration_sum_ms: 0
+        )
           super
         end
 
@@ -14,7 +31,10 @@ module Toggly
             checkCount: check_count,
             requestCount: request_count,
             usedCount: used_count,
-            viewedCount: viewed_count
+            viewedCount: viewed_count,
+            errorCount: error_count,
+            durationSumMs: duration_sum_ms,
+            errorDurationSumMs: error_duration_sum_ms
           }
         end
 
@@ -23,7 +43,10 @@ module Toggly
             check_count: check_count,
             request_count: request_count,
             used_count: used_count,
-            viewed_count: viewed_count
+            viewed_count: viewed_count,
+            error_count: error_count,
+            duration_sum_ms: duration_sum_ms,
+            error_duration_sum_ms: error_duration_sum_ms
           )
         end
       end
@@ -138,6 +161,27 @@ module Toggly
         end
       end
 
+      def record_usage_error(feature, variant: "enabled", count: 1)
+        return if count <= 0
+
+        @mutex.synchronize do
+          get_variant(get_feature(feature), variant.to_s).error_count += count
+        end
+      end
+
+      def record_usage_duration(feature, duration_ms, variant: "enabled", failed: false)
+        return if duration_ms <= 0
+
+        @mutex.synchronize do
+          stats = get_variant(get_feature(feature), variant.to_s)
+          if failed
+            stats.error_duration_sum_ms += duration_ms
+          else
+            stats.duration_sum_ms += duration_ms
+          end
+        end
+      end
+
       def empty?
         @mutex.synchronize { empty_unlocked? }
       end
@@ -180,6 +224,9 @@ module Toggly
               stats.request_count += snap_stats.request_count
               stats.used_count += snap_stats.used_count
               stats.viewed_count += snap_stats.viewed_count
+              stats.error_count += snap_stats.error_count
+              stats.duration_sum_ms += snap_stats.duration_sum_ms
+              stats.error_duration_sum_ms += snap_stats.error_duration_sum_ms
             end
             agg.unique_users_enabled.merge(snap_agg.unique_users_enabled)
             agg.unique_users_disabled.merge(snap_agg.unique_users_disabled)
@@ -250,7 +297,9 @@ module Toggly
         variant_stats = {}
         agg.variant_stats.each do |name, vs|
           next unless vs.check_count.positive? || vs.request_count.positive? ||
-                      vs.used_count.positive? || vs.viewed_count.positive?
+                      vs.used_count.positive? || vs.viewed_count.positive? ||
+                      vs.error_count.positive? || vs.duration_sum_ms.positive? ||
+                      vs.error_duration_sum_ms.positive?
 
           variant_stats[name] = vs.to_wire
         end

data/lib/toggly/telemetry/usage_scope.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "English"
+
+module Toggly
+  module Telemetry
+    # Tracks one usage attempt; call {#fail} to mark failure without raising.
+    class FeatureUsageScope
+      def initialize
+        @failed = false
+      end
+
+      def fail
+        @failed = true
+      end
+
+      def failed?
+        @failed
+      end
+    end
+
+    # Runs a usage-scope block and records attempt, duration, and errors.
+    module UsageScopeRunner
+      module_function
+
+      def run(handlers, &block)
+        record_attempt, record_success, record_failure = handlers
+        record_attempt.call
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        scope = FeatureUsageScope.new
+        outcome_recorded = false
+        # $! is the nearest enclosing rescue, not this scope. A clean return
+        # inside an outer rescue must not inherit that exception as a failure.
+        enclosing_error = $ERROR_INFO
+        begin
+          result = block.call(scope)
+          duration_ms = elapsed_ms(start)
+          if scope.failed?
+            record_failure.call(duration_ms)
+          else
+            record_success.call(duration_ms)
+          end
+          outcome_recorded = true
+          result
+        rescue StandardError => e
+          record_failure.call(elapsed_ms(start))
+          outcome_recorded = true
+          raise e
+        ensure
+          # Non-local exits (return/break/throw) and Exception subclasses that
+          # bypass rescue StandardError still need an outcome. Only a $! raised
+          # by this scope (different from the enclosing rescue) is a failure.
+          # Interrupt / SystemExit / SignalException match Python: attempt only.
+          unless outcome_recorded
+            duration_ms = elapsed_ms(start)
+            raised_here = !$ERROR_INFO.equal?(enclosing_error)
+            if attempt_only_exception?($ERROR_INFO) && raised_here && !scope.failed?
+              # Attempt already recorded; process control exits are not failures.
+            elsif scope.failed? || raised_here
+              record_failure.call(duration_ms)
+            else
+              record_success.call(duration_ms)
+            end
+          end
+        end
+      end
+
+      def attempt_only_exception?(error)
+        error.is_a?(SystemExit) || error.is_a?(Interrupt) || error.is_a?(SignalException)
+      end
+
+      def elapsed_ms(start)
+        ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        ms.negative? ? 0 : ms
+      end
+    end
+  end
+end

data/lib/toggly/telemetry.rb

@@ -2,6 +2,7 @@
 
 require_relative "telemetry/grpc_clients"
 require_relative "telemetry/usage_batcher"
+require_relative "telemetry/usage_scope"
 require_relative "telemetry/metrics_batcher"
 require_relative "telemetry/runtime"
 

data/lib/toggly/version.rb

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

data/proto/usage.proto

@@ -44,6 +44,9 @@ message VariantStats {
   int32 requestCount = 2;
   int32 usedCount = 3;
   int32 viewedCount = 4;
+  int32 errorCount = 5;
+  int64 durationSumMs = 6;
+  int64 errorDurationSumMs = 7;
 }
 
 message StatResult {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-06 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,7 +66,9 @@ 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
 - lib/toggly/variant_allocator.rb
 - lib/toggly/variant_result.rb
@@ -91,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:
   - - ">="