statsig 2.1.0 → 2.8.1

data/lib/statsig_driver.rb

@@ -1,18 +1,20 @@
-require 'config_result'
-require 'evaluator'
-require 'network'
-require 'statsig_errors'
-require 'statsig_event'
-require 'statsig_logger'
-require 'statsig_options'
-require 'statsig_user'
-require 'spec_store'
-require 'dynamic_config'
-require 'feature_gate'
-require 'error_boundary'
-require 'layer'
-require 'memo'
-require 'diagnostics'
+require_relative 'api_config'
+require_relative 'config_result'
+require_relative 'diagnostics'
+require_relative 'dynamic_config'
+require_relative 'error_boundary'
+require_relative 'evaluator'
+require_relative 'feature_gate'
+require_relative 'layer'
+require_relative 'memo'
+require_relative 'network'
+require_relative 'sdk_configs'
+require_relative 'spec_store'
+require_relative 'statsig_errors'
+require_relative 'statsig_event'
+require_relative 'statsig_logger'
+require_relative 'statsig_options'
+require_relative 'statsig_user'
 
 class StatsigDriver
 
@@ -27,15 +29,16 @@ class StatsigDriver
 
     @err_boundary = Statsig::ErrorBoundary.new(secret_key, !options.nil? && options.local_mode)
     @err_boundary.capture(caller: __method__) do
-      @diagnostics = Statsig::Diagnostics.new()
+      @diagnostics = Statsig::Diagnostics.new
+      @sdk_configs = Statsig::SDKConfigs.new
       tracker = @diagnostics.track('initialize', 'overall')
       @options = options || StatsigOptions.new
       @shutdown = false
       @secret_key = secret_key
       @net = Statsig::Network.new(secret_key, @options)
-      @logger = Statsig::StatsigLogger.new(@net, @options, @err_boundary)
+      @logger = Statsig::StatsigLogger.new(@net, @options, @err_boundary, @sdk_configs)
       @persistent_storage_utils = Statsig::UserPersistentStorageUtils.new(@options)
-      @store = Statsig::SpecStore.new(@net, @options, error_callback, @diagnostics, @err_boundary, @logger, secret_key)
+      @store = Statsig::SpecStore.new(@net, @options, error_callback, @diagnostics, @err_boundary, @logger, secret_key, @sdk_configs)
       @evaluator = Statsig::Evaluator.new(@store, @options, @persistent_storage_utils)
       tracker.end(success: true)
 
@@ -43,6 +46,10 @@ class StatsigDriver
     end
   end
 
+  def get_initialization_details
+    @store.get_initialization_details
+  end
+
   def get_gate_impl(
     user,
     gate_name,
@@ -59,7 +66,7 @@ class StatsigDriver
 
     user = verify_inputs(user, gate_name, 'gate_name')
 
-    Statsig::Memo.for(user.get_memo, :get_gate_impl, gate_name) do
+    Statsig::Memo.for(user.get_memo, :get_gate_impl, gate_name, disable_evaluation_memoization: @options.disable_evaluation_memoization) do
       res = Statsig::ConfigResult.new(
         name: gate_name,
         disable_exposures: disable_log_exposure,
@@ -68,9 +75,7 @@ class StatsigDriver
       @evaluator.check_gate(user, gate_name, res, ignore_local_overrides: ignore_local_overrides)
 
       unless disable_log_exposure
-        @logger.log_gate_exposure(
-          user, res.name, res.gate_value, res.rule_id, res.secondary_exposures, res.evaluation_details
-        )
+        @logger.log_gate_exposure(user, res)
       end
 
       FeatureGate.from_config_result(res)
@@ -109,7 +114,16 @@ class StatsigDriver
       res = Statsig::ConfigResult.new(name: gate_name)
       @evaluator.check_gate(user, gate_name, res)
       context = { :is_manual_exposure => true }
-      @logger.log_gate_exposure(user, gate_name, res.gate_value, res.rule_id, res.secondary_exposures, res.evaluation_details, context)
+      @logger.log_gate_exposure(user, res, context)
+    end
+  end
+
+  def get_fields_used_for_gate(gate_name)
+    @err_boundary.capture(caller: __method__, recover: -> { [] }) do
+        gate = @store.get_gate(gate_name)
+        return [] if gate.nil?
+
+        gate[:fieldsUsed] || []
     end
   end
 
@@ -128,6 +142,15 @@ class StatsigDriver
     end
   end
 
+  def get_fields_used_for_config(config_name)
+    @err_boundary.capture(caller: __method__, recover: -> { [] }) do
+        config = @store.get_config(config_name)
+        return [] if config.nil?
+
+        config[:fieldsUsed] || []
+    end
+  end
+
   def get_experiment(user, experiment_name, options = nil)
     @err_boundary.capture(caller: __method__, recover: -> { DynamicConfig.new(experiment_name) }) do
       run_with_diagnostics(caller: :get_experiment) do
@@ -150,7 +173,7 @@ class StatsigDriver
       @evaluator.get_config(user, config_name, res)
 
       context = { :is_manual_exposure => true }
-      @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures, res.evaluation_details, context)
+      @logger.log_config_exposure(user, res, context)
     end
   end
 
@@ -167,7 +190,7 @@ class StatsigDriver
     @err_boundary.capture(caller: __method__, recover: -> { Layer.new(layer_name) }) do
       run_with_diagnostics(caller: :get_layer) do
         user = verify_inputs(user, layer_name, "layer_name")
-        Statsig::Memo.for(user.get_memo, :get_layer, layer_name) do
+        Statsig::Memo.for(user.get_memo, :get_layer, layer_name, disable_evaluation_memoization: @options.disable_evaluation_memoization) do
           exposures_disabled = options&.disable_log_exposure == true
           res = Statsig::ConfigResult.new(
             name: layer_name,
@@ -197,6 +220,15 @@ class StatsigDriver
     end
   end
 
+  def get_fields_used_for_layer(layer_name)
+    @err_boundary.capture(caller: __method__, recover: -> { [] }) do
+        layer = @store.get_layer(layer_name)
+        return [] if layer.nil?
+
+        layer[:fieldsUsed] || []
+    end
+  end
+
   def log_event(user, event_name, value = nil, metadata = nil)
     @err_boundary.capture(caller: __method__) do
       if !user.nil? && !user.instance_of?(StatsigUser)
@@ -300,6 +332,18 @@ class StatsigDriver
     end
   end
 
+  def clear_experiment_overrides
+    @err_boundary.capture(caller: __method__) do
+      @evaluator.clear_experiment_overrides
+    end
+  end
+
+  def remove_experiment_override(experiment_name)
+    @err_boundary.capture(caller: __method__) do
+      @evaluator.remove_experiment_override(experiment_name)
+    end
+  end
+
   def set_debug_info(debug_info)
     @err_boundary.capture(caller: __method__) do
       @logger.set_debug_info(debug_info)
@@ -333,6 +377,10 @@ class StatsigDriver
     end
   end
 
+  def override_experiment_by_group_name(experiment_name, group_name)
+    @evaluator.override_experiment_by_group_name(experiment_name, group_name)
+  end
+
   private
 
   def run_with_diagnostics(caller:)
@@ -357,7 +405,7 @@ class StatsigDriver
 
   def verify_inputs(user, config_name, variable_name)
     validate_user(user)
-    user = Statsig::Memo.for(user.get_memo(), :verify_inputs, 0) do
+    user = Statsig::Memo.for(user.get_memo(), :verify_inputs, 0, disable_evaluation_memoization: @options.disable_evaluation_memoization) do
       user = normalize_user(user)
       check_shutdown
       maybe_restart_background_threads
@@ -372,7 +420,7 @@ class StatsigDriver
   end
 
   def get_config_impl(user, config_name, disable_log_exposure, user_persisted_values: nil, disable_evaluation_details: false, ignore_local_overrides: false)
-    Statsig::Memo.for(user.get_memo, :get_config_impl, config_name) do
+    Statsig::Memo.for(user.get_memo, :get_config_impl, config_name, disable_evaluation_memoization: @options.disable_evaluation_memoization) do
       res = Statsig::ConfigResult.new(
         name: config_name,
         disable_exposures: disable_log_exposure,
@@ -381,7 +429,7 @@ class StatsigDriver
       @evaluator.get_config(user, config_name, res, user_persisted_values: user_persisted_values, ignore_local_overrides: ignore_local_overrides)
 
       unless disable_log_exposure
-        @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures, res.evaluation_details)
+        @logger.log_config_exposure(user, res)
       end
 
       DynamicConfig.new(res.name, res.json_value, res.rule_id, res.group_name, res.id_type, res.evaluation_details)

data/lib/statsig_event.rb

@@ -1,4 +1,3 @@
-
 class StatsigEvent
   attr_accessor :value, :metadata, :statsig_metadata, :secondary_exposures
   attr_reader :user
@@ -15,7 +14,7 @@ class StatsigEvent
 
   def user=(value)
     if value.is_a?(StatsigUser)
-      @user = Statsig::Memo.for(value.get_memo(), :serialize, 0) do
+      @user = Statsig::Memo.for(value.get_memo(), :serialize, 0, disable_evaluation_memoization: Statsig.get_options&.disable_evaluation_memoization) do
         value.serialize(true)
       end
     end

data/lib/statsig_logger.rb

@@ -1,15 +1,24 @@
-require 'constants'
-require 'statsig_event'
 require 'concurrent-ruby'
+require_relative 'constants'
+require_relative 'hash_utils'
+require_relative 'statsig_event'
+require_relative 'ttl_set'
 
 $gate_exposure_event = 'statsig::gate_exposure'
 $config_exposure_event = 'statsig::config_exposure'
 $layer_exposure_event = 'statsig::layer_exposure'
 $diagnostics_event = 'statsig::diagnostics'
 $ignored_metadata_keys = [:serverTime, :configSyncTime, :initTime, :reason]
+
+class EntityType
+  GATE = "gate"
+  CONFIG = "config"
+  LAYER = "layer"
+end
+
 module Statsig
   class StatsigLogger
-    def initialize(network, options, error_boundary)
+    def initialize(network, options, error_boundary, sdk_configs)
       @network = network
       @events = []
       @options = options
@@ -25,10 +34,12 @@ module Statsig
 
       @error_boundary = error_boundary
       @background_flush = periodic_flush
-      @deduper = Concurrent::Set.new()
+      @deduper = Concurrent::Set.new
+      @sampling_key_set = Statsig::TTLSet.new
       @interval = 0
       @flush_mutex = Mutex.new
       @debug_info = nil
+      @sdk_configs = sdk_configs
     end
 
     def log_event(event)
@@ -38,43 +49,64 @@ module Statsig
       end
     end
 
-    def log_gate_exposure(user, gate_name, value, rule_id, secondary_exposures, eval_details, context = nil)
+    def log_gate_exposure(user, result, context = nil)
+      should_log, logged_sampling_rate, shadow_logged = determine_sampling(EntityType::GATE, result.name, result, user)
+      return unless should_log
       event = StatsigEvent.new($gate_exposure_event)
       event.user = user
       metadata = {
-        gate: gate_name,
-        gateValue: value.to_s,
-        ruleID: rule_id || Statsig::Const::EMPTY_STR,
+        gate: result.name,
+        gateValue: result.gate_value.to_s,
+        ruleID: result.rule_id || Statsig::Const::EMPTY_STR,
       }
+      if result.config_version != nil
+        metadata[:configVersion] = result.config_version.to_s
+      end
       if @debug_info != nil
         metadata[:debugInfo] = @debug_info
       end
+      unless result.override_config_name.nil?
+        metadata[:overrideConfigName] = result.override_config_name
+      end
       return false if not is_unique_exposure(user, $gate_exposure_event, metadata)
       event.metadata = metadata
+      event.statsig_metadata = {}
 
-      event.secondary_exposures = secondary_exposures.is_a?(Array) ? secondary_exposures : []
+      event.secondary_exposures = result.secondary_exposures.is_a?(Array) ? result.secondary_exposures : []
 
-      safe_add_eval_details(eval_details, event)
+      safe_add_eval_details(result.evaluation_details, event)
       safe_add_exposure_context(context, event)
+      safe_add_sampling_metadata(event, logged_sampling_rate, shadow_logged)
       log_event(event)
     end
 
-    def log_config_exposure(user, config_name, rule_id, secondary_exposures, eval_details, context = nil)
+    def log_config_exposure(user, result, context = nil)
+      should_log, logged_sampling_rate, shadow_logged = determine_sampling(EntityType::CONFIG, result.name, result, user)
+      return unless should_log
       event = StatsigEvent.new($config_exposure_event)
       event.user = user
       metadata = {
-        config: config_name,
-        ruleID: rule_id || Statsig::Const::EMPTY_STR,
+        config: result.name,
+        ruleID: result.rule_id || Statsig::Const::EMPTY_STR,
+        rulePassed: result.gate_value.to_s,
       }
+      if result.config_version != nil
+        metadata[:configVersion] = result.config_version.to_s
+      end
       if @debug_info != nil
         metadata[:debugInfo] = @debug_info
       end
+      unless result.override_config_name.nil?
+        metadata[:overrideConfigName] = result.override_config_name
+      end
       return false if not is_unique_exposure(user, $config_exposure_event, metadata)
       event.metadata = metadata
-      event.secondary_exposures = secondary_exposures.is_a?(Array) ? secondary_exposures : []
+      event.secondary_exposures = result.secondary_exposures.is_a?(Array) ? result.secondary_exposures : []
+      event.statsig_metadata = {}
 
-      safe_add_eval_details(eval_details, event)
+      safe_add_eval_details(result.evaluation_details, event)
       safe_add_exposure_context(context, event)
+      safe_add_sampling_metadata(event, logged_sampling_rate, shadow_logged)
       log_event(event)
     end
 
@@ -87,6 +119,9 @@ module Statsig
         exposures = config_evaluation.secondary_exposures
       end
 
+      should_log, logged_sampling_rate, shadow_logged = determine_sampling(EntityType::LAYER, config_evaluation.name, config_evaluation, user, allocated_experiment, parameter_name)
+      return unless should_log
+
       event = StatsigEvent.new($layer_exposure_event)
       event.user = user
       metadata = {
@@ -96,15 +131,20 @@ module Statsig
         parameterName: parameter_name,
         isExplicitParameter: String(is_explicit)
       }
+      if config_evaluation.config_version != nil
+        metadata[:configVersion] = config_evaluation.config_version.to_s
+      end
       if @debug_info != nil
         metadata[:debugInfo] = @debug_info
       end
       return false unless is_unique_exposure(user, $layer_exposure_event, metadata)
       event.metadata = metadata
       event.secondary_exposures = exposures.is_a?(Array) ? exposures : []
+      event.statsig_metadata = {}
 
       safe_add_eval_details(config_evaluation.evaluation_details, event)
       safe_add_exposure_context(context, event)
+      safe_add_sampling_metadata(event, logged_sampling_rate, shadow_logged)
       log_event(event)
     end
 
@@ -140,6 +180,7 @@ module Statsig
 
     def shutdown
       @background_flush&.exit
+      @sampling_key_set.shutdown
       @logging_pool.shutdown
       @logging_pool.wait_for_termination(timeout = 3)
       flush
@@ -159,8 +200,11 @@ module Statsig
 
         events_clone = @events
         @events = []
-        flush_events = events_clone.map { |e| e.serialize }
-        @network.post_logs(flush_events, @error_boundary)
+        serialized_events = events_clone.map { |e| e.serialize }
+
+        serialized_events.each_slice(@options.logging_max_buffer_size) do |batch|
+          @network.post_logs(batch, @error_boundary)
+        end
       end
     end
 
@@ -197,6 +241,18 @@ module Statsig
       end
     end
 
+    def safe_add_sampling_metadata(event, logged_sampling_rate = nil, shadow_logged = nil)
+      unless logged_sampling_rate.nil?
+        event.statsig_metadata["samplingRate"] = logged_sampling_rate
+      end
+
+      unless shadow_logged.nil?
+        event.statsig_metadata["shadowLogged"] = shadow_logged
+      end
+
+      event.statsig_metadata["samplingMode"] = @sdk_configs.get_config_string_value("sampling_mode")
+    end
+
     def is_unique_exposure(user, event_name, metadata)
       return true if user.nil?
       @deduper.clear if @deduper.size > 10000
@@ -214,5 +270,69 @@ module Statsig
       @deduper.add(key)
       true
     end
+
+    def determine_sampling(type, name, result, user, exp_name = "", param_name = "")
+      begin
+        shadow_should_log, logged_sampling_rate = true, nil
+        env = @options.environment&.dig(:tier)
+        sampling_mode = @sdk_configs.get_config_string_value("sampling_mode")
+        special_case_sampling_rate = @sdk_configs.get_config_int_value("special_case_sampling_rate")
+        special_case_rules = ["disabled", "default", ""]
+
+        if sampling_mode.nil? || sampling_mode == "none" || env != "production"
+          return true, nil, nil
+        end
+
+        return true, nil, nil if result.forward_all_exposures
+        return true, nil, nil if result.rule_id.end_with?(":override", ":id_override")
+        return true, nil, nil if result.has_seen_analytical_gates
+
+        sampling_set_key = "#{name}_#{result.rule_id}"
+        unless @sampling_key_set.contains?(sampling_set_key)
+          @sampling_key_set.add(sampling_set_key)
+          return true, nil, nil
+        end
+
+        should_sample = result.sampling_rate || special_case_rules.include?(result.rule_id)
+        unless should_sample
+          return true, nil, nil
+        end
+
+        exposure_key = ""
+        case type
+        when EntityType::GATE
+          exposure_key = Statsig::HashUtils.compute_dedupe_key_for_gate(name, result.rule_id, result.gate_value, user.user_id, user.custom_ids)
+        when EntityType::CONFIG
+          exposure_key = Statsig::HashUtils.compute_dedupe_key_for_config(name, result.rule_id, user.user_id, user.custom_ids)
+        when EntityType::LAYER
+          exposure_key = Statsig::HashUtils.compute_dedupe_key_for_layer(name, exp_name, param_name, result.rule_id, user.user_id, user.custom_ids)
+        end
+
+        if result.sampling_rate
+          shadow_should_log = Statsig::HashUtils.is_hash_in_sampling_rate(exposure_key, result.sampling_rate)
+          logged_sampling_rate = result.sampling_rate
+        elsif special_case_rules.include?(result.rule_id) && special_case_sampling_rate
+          shadow_should_log = Statsig::HashUtils.is_hash_in_sampling_rate(exposure_key, special_case_sampling_rate)
+          logged_sampling_rate = special_case_sampling_rate
+        end
+
+        shadow_logged = if logged_sampling_rate.nil?
+                          nil
+                        else
+                          shadow_should_log ? "logged" : "dropped"
+                        end
+        if sampling_mode == "on"
+          return shadow_should_log, logged_sampling_rate, shadow_logged
+        elsif sampling_mode == "shadow"
+          return true, logged_sampling_rate, shadow_logged
+        end
+
+        return true, nil, nil
+      rescue => e
+        @error_boundary.log_exception(e, "__determine_sampling")
+        return true, nil, nil
+      end
+    end
+
   end
 end

data/lib/statsig_options.rb

@@ -88,6 +88,10 @@ class StatsigOptions
   # Implements Statsig::Interfaces::IUserPersistentStorage.
   attr_accessor :user_persistent_storage
 
+  # Disable memoization of evaluation results. When true, each evaluation will be performed fresh.
+  # default: false
+  attr_accessor :disable_evaluation_memoization
+
   def initialize(
     environment = nil,
     download_config_specs_url: nil,
@@ -110,7 +114,8 @@ class StatsigOptions
     network_timeout: nil,
     post_logs_retry_limit: 3,
     post_logs_retry_backoff: nil,
-    user_persistent_storage: nil
+    user_persistent_storage: nil,
+    disable_evaluation_memoization: false
   )
     @environment = environment.is_a?(Hash) ? environment : nil
 
@@ -140,6 +145,6 @@ class StatsigOptions
     @post_logs_retry_limit = post_logs_retry_limit
     @post_logs_retry_backoff = post_logs_retry_backoff
     @user_persistent_storage = user_persistent_storage
-
+    @disable_evaluation_memoization = disable_evaluation_memoization
   end
 end

data/lib/statsig_user.rb

@@ -1,5 +1,5 @@
 require 'json'
-require 'constants'
+require_relative 'constants'
 ##
 #  The user object to be evaluated against your Statsig configurations (gates/experiments/dynamic configs).
 class StatsigUser

data/lib/ttl_set.rb

@@ -0,0 +1,36 @@
+require 'concurrent-ruby'
+
+RESET_INTERVAL = 60
+
+module Statsig
+  class TTLSet
+    def initialize
+      @store = Concurrent::Set.new
+      @reset_interval = RESET_INTERVAL
+      @background_reset = periodic_reset
+    end
+
+    def add(key)
+      @store.add(key)
+    end
+
+    def contains?(key)
+      @store.include?(key)
+    end
+
+    def shutdown
+      @background_reset&.exit
+    end
+
+    def periodic_reset
+      Thread.new do
+        loop do
+          sleep @reset_interval
+          @store.clear
+        end
+      end
+    end
+  end
+end
+
+

data/lib/user_persistent_storage_utils.rb

@@ -1,4 +1,4 @@
-require 'statsig_options'
+require_relative 'statsig_options'
 
 module Statsig
   class UserPersistentStorageUtils
@@ -65,15 +65,27 @@ module Statsig
       if user_persisted_values.nil?
         user_persisted_values = {}
       end
-      user_persisted_values[config_name] = evaluation.to_hash
+      hash = evaluation.to_hash
+      if hash['json_value'].is_a?(Hash)
+        hash['json_value'] = self.class.symbolize_keys(hash['json_value'])
+      end
+      user_persisted_values[config_name] = hash
     end
 
     private
 
     def self.parse(values_string)
-      return JSON.parse(values_string)
-    rescue JSON::ParserError
-      return nil
+      return nil if values_string.nil?
+
+      parsed = JSON.parse(values_string)
+      return nil if parsed.nil?
+
+      parsed.each do |config_name, config_value|
+        if config_value.is_a?(Hash) && config_value.key?('json_value')
+          config_value['json_value'] = symbolize_keys(config_value['json_value'])
+        end
+      end
+      parsed
     end
 
     def self.stringify(values_object)
@@ -85,5 +97,15 @@ module Statsig
     def self.get_storage_key(user, id_type)
       "#{user.get_unit_id(id_type)}:#{id_type}"
     end
+
+    def self.symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      symbolized = {}
+      hash.each do |key, value|
+        symbolized[key.to_sym] = value.is_a?(Hash) ? symbolize_keys(value) : value
+      end
+      symbolized
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statsig
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.8.1
 platform: ruby
 authors:
 - Statsig, Inc
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-26 00:00:00.000000000 Z
+date: 2025-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -226,14 +226,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.15.0
+        version: 2.18.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.15.0
+        version: 2.18.0
 - !ruby/object:Gem::Dependency
   name: http
   requirement: !ruby/object:Gem::Requirement
@@ -340,6 +340,7 @@ files:
 - lib/layer.rb
 - lib/memo.rb
 - lib/network.rb
+- lib/sdk_configs.rb
 - lib/spec_store.rb
 - lib/statsig.rb
 - lib/statsig_driver.rb
@@ -348,13 +349,14 @@ files:
 - lib/statsig_logger.rb
 - lib/statsig_options.rb
 - lib/statsig_user.rb
+- lib/ttl_set.rb
 - lib/ua_parser.rb
 - lib/user_persistent_storage_utils.rb
 homepage: https://rubygems.org/gems/statsig
 licenses:
 - ISC
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -370,7 +372,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.2.33
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Statsig server SDK for Ruby
 test_files: []