statsig 1.17.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b81f929cdedefaee6f57cb2b0f7aec05bbfd28cf6b4f273fc4fb3bbcf46858f
-  data.tar.gz: 5caa719d8a301cbcd95d68f9bc5802a89f0691600c7b5883bfdbfcc8fa21bb8f
+  metadata.gz: 354a77a658a3232a8695d82136d3e84e5bf0ce2199d06af9fee216eaae7d5dcd
+  data.tar.gz: 3be67ca270e61eedd92fb3aaa96b4f28ff1b79feee3ec4b1a33bdc2d000f8c2e
 SHA512:
-  metadata.gz: 9372cd1b25a0b91054d6315df027833cd2377e51e1f76385dd260fe9a17665da33330c357cf63756f6bc6701e51f76a7d5b81aa99d57a96bfeee807c575c3b19
-  data.tar.gz: 5dd1c6ad849e20c0ed15b451371a78e971f6da4ed83f7bf7f79eb5db65c88ba27f1b8e9da991587d8a46cbd2086d0b30692bbb81e48283e758b84d679a63eb3a
+  metadata.gz: 6f2461d11144a2e822178d69dad1ff50ebb2a4cd14f7b5dc46704b9c285a56d494f512b8058361f0a3ba3c71d899a6b9afc2fe51618abbe73784c6a937c39125
+  data.tar.gz: 45ac2d3a06f60c1cb0a81b109df9d06e1f479d384023e2009343b6d6f74b5d806fdf86e85b5d09ad8f1e55b07ca8c1b010cb23f7c8de2e9594b1092b323c8708

data/lib/diagnostics.rb

@@ -0,0 +1,44 @@
+# typed: true
+
+require 'sorbet-runtime'
+
+module Statsig
+  class Diagnostics
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :context
+
+    sig { returns(T::Array[T::Hash[Symbol, T.untyped]]) }
+    attr_reader :markers
+
+    sig { params(context: String).void }
+
+    def initialize(context)
+      @context = context
+      @markers = []
+    end
+
+    sig { params(key: String, action: String, step: T.any(String, NilClass), value: T.any(String, Integer, T::Boolean, NilClass)).void }
+
+    def mark(key, action, step = nil, value = nil)
+      @markers.push({
+                      key: key,
+                      step: step,
+                      action: action,
+                      value: value,
+                      timestamp: (Time.now.to_f * 1000).to_i
+                    })
+    end
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+
+    def serialize
+      {
+        context: @context,
+        markers: @markers
+      }
+    end
+  end
+
+end

data/lib/error_boundary.rb

@@ -0,0 +1,57 @@
+require "statsig_errors"
+
+$endpoint = 'https://statsigapi.net/v1/sdk_exception'
+
+module Statsig
+  class ErrorBoundary
+    def initialize(sdk_key)
+      @sdk_key = sdk_key
+      @seen = Set.new
+    end
+
+    def capture(task, recover = -> {})
+      begin
+        return task.call
+      rescue StandardError => e
+        if e.is_a?(Statsig::UninitializedError) or e.is_a?(Statsig::ValueError)
+          raise e
+        end
+        puts "[Statsig]: An unexpected exception occurred."
+        log_exception(e)
+        return recover.call
+      end
+    end
+
+    private
+
+    def log_exception(exception)
+      begin
+        name = exception.class.name
+        if @seen.include?(name)
+          return
+        end
+
+        @seen << name
+        meta = Statsig.get_statsig_metadata
+        http = HTTP.headers(
+          {
+            "STATSIG-API-KEY" => @sdk_key,
+            "STATSIG-SDK-TYPE" => meta['sdkType'],
+            "STATSIG-SDK-VERSION" => meta['sdkVersion'],
+            "Content-Type" => "application/json; charset=UTF-8"
+          }).accept(:json)
+        body = {
+          "exception" => name,
+          "info" => {
+            "trace" => exception.backtrace.to_s,
+            "message" => exception.message
+          }.to_s,
+          "statsigMetadata" => meta
+        }
+        http.post($endpoint, body: JSON.generate(body))
+      rescue
+        return
+      end
+    end
+  end
+end

data/lib/evaluator.rb

@@ -17,8 +17,8 @@ module Statsig
   class Evaluator
     attr_accessor :spec_store
 
-    def initialize(network, options, error_callback)
-      @spec_store = Statsig::SpecStore.new(network, options, error_callback)
+    def initialize(network, options, error_callback, init_diagnostics = nil)
+      @spec_store = Statsig::SpecStore.new(network, options, error_callback, init_diagnostics)
       @ua_parser = UserAgentParser::Parser.new
       CountryLookup.initialize
 

data/lib/network.rb

@@ -8,6 +8,15 @@ require 'sorbet-runtime'
 $retry_codes = [408, 500, 502, 503, 504, 522, 524, 599]
 
 module Statsig
+  class NetworkError < StandardError
+    attr_reader :http_code
+
+    def initialize(msg = nil, http_code = nil)
+      super(msg)
+      @http_code = http_code
+    end
+  end
+
   class Network
     extend T::Sig
 
@@ -25,19 +34,23 @@ module Statsig
       @session_id = SecureRandom.uuid
     end
 
-
     sig { params(endpoint: String, body: String, retries: Integer, backoff: Integer)
-      .returns([T.any(HTTP::Response, NilClass), T.any(StandardError, NilClass)]) }
+            .returns([T.any(HTTP::Response, NilClass), T.any(StandardError, NilClass)]) }
 
     def post_helper(endpoint, body, retries = 0, backoff = 1)
       if @local_mode
         return nil, nil
       end
+
+      meta = Statsig.get_statsig_metadata
       http = HTTP.headers(
-        {"STATSIG-API-KEY" => @server_secret,
-        "STATSIG-CLIENT-TIME" => (Time.now.to_f * 1000).to_i.to_s,
-         "STATSIG-SERVER-SESSION-ID" => @session_id,
-        "Content-Type" => "application/json; charset=UTF-8"
+        {
+          "STATSIG-API-KEY" => @server_secret,
+          "STATSIG-CLIENT-TIME" => (Time.now.to_f * 1000).to_i.to_s,
+          "STATSIG-SERVER-SESSION-ID" => @session_id,
+          "Content-Type" => "application/json; charset=UTF-8",
+          "STATSIG-SDK-TYPE" => meta['sdkType'],
+          "STATSIG-SDK-VERSION" => meta['sdkVersion'],
         }).accept(:json)
       begin
         res = http.post(@api + endpoint, body: body)
@@ -47,8 +60,8 @@ module Statsig
         sleep backoff
         return post_helper(endpoint, body, retries - 1, backoff * @backoff_multiplier)
       end
-      return res, nil unless !res.status.success?
-      return nil, StandardError.new("Got an exception when making request to #{@api + endpoint}: #{res.to_s}") unless retries > 0 && $retry_codes.include?(res.code)
+      return res, nil if res.status.success?
+      return nil, NetworkError.new("Got an exception when making request to #{@api + endpoint}: #{res.to_s}", res.status.to_i) unless retries > 0 && $retry_codes.include?(res.code)
       ## status code retry
       sleep backoff
       post_helper(endpoint, body, retries - 1, backoff * @backoff_multiplier)
@@ -56,7 +69,7 @@ module Statsig
 
     def check_gate(user, gate_name)
       begin
-        request_body = JSON.generate({'user' => user&.serialize(false), 'gateName' => gate_name})
+        request_body = JSON.generate({ 'user' => user&.serialize(false), 'gateName' => gate_name })
         response, _ = post_helper('check_gate', request_body)
         return JSON.parse(response.body) unless response.nil?
         false
@@ -67,7 +80,7 @@ module Statsig
 
     def get_config(user, dynamic_config_name)
       begin
-        request_body = JSON.generate({'user' => user&.serialize(false), 'configName' => dynamic_config_name})
+        request_body = JSON.generate({ 'user' => user&.serialize(false), 'configName' => dynamic_config_name })
         response, _ = post_helper('get_config', request_body)
         return JSON.parse(response.body) unless response.nil?
         nil
@@ -78,7 +91,7 @@ module Statsig
 
     def post_logs(events)
       begin
-        json_body = JSON.generate({'events' => events, 'statsigMetadata' => Statsig.get_statsig_metadata})
+        json_body = JSON.generate({ 'events' => events, 'statsigMetadata' => Statsig.get_statsig_metadata })
         post_helper('log_event', json_body, 5)
       rescue
       end

data/lib/spec_store.rb

@@ -14,7 +14,7 @@ module Statsig
     attr_accessor :initial_config_sync_time
     attr_accessor :init_reason
 
-    def initialize(network, options, error_callback)
+    def initialize(network, options, error_callback, init_diagnostics = nil)
       @init_reason = EvaluationReason::UNINITIALIZED
       @network = network
       @options = options
@@ -42,8 +42,12 @@ module Statsig
         begin
           if !@options.data_store.nil?
             puts 'data_store gets priority over bootstrap_values. bootstrap_values will be ignored'
-          elsif process(options.bootstrap_values)
-            @init_reason = EvaluationReason::BOOTSTRAP
+          else
+            init_diagnostics&.mark("bootstrap", "start", "load")
+            if process(options.bootstrap_values)
+              @init_reason = EvaluationReason::BOOTSTRAP
+            end
+            init_diagnostics&.mark("bootstrap", "end", "load", @init_reason == EvaluationReason::BOOTSTRAP)
           end
         rescue
           puts 'the provided bootstrapValues is not a valid JSON string'
@@ -51,13 +55,18 @@ module Statsig
       end
 
       unless @options.data_store.nil?
+        init_diagnostics&.mark("data_store", "start", "load")
         @options.data_store.init
         load_from_storage_adapter
+        init_diagnostics&.mark("data_store", "end", "load", @init_reason == EvaluationReason::DATA_ADAPTER)
+      end
+
+      if @init_reason == EvaluationReason::UNINITIALIZED
+        download_config_specs(init_diagnostics)
       end
 
-      download_config_specs
       @initial_config_sync_time = @last_config_sync_time == 0 ? -1 : @last_config_sync_time
-      get_id_lists
+      get_id_lists(init_diagnostics)
 
       @config_sync_thread = sync_config_specs
       @id_lists_sync_thread = sync_id_lists
@@ -157,26 +166,39 @@ module Statsig
       end
     end
 
-    def download_config_specs
-      e = get_config_specs_from_network
-      @error_callback.call(e) unless e.nil? or @error_callback.nil?
-    end
+    def download_config_specs(init_diagnostics = nil)
+      init_diagnostics&.mark("download_config_specs", "start", "network_request")
 
-    def get_config_specs_from_network
+      error = nil
       begin
         response, e = @network.post_helper('download_config_specs', JSON.generate({ 'sinceTime' => @last_config_sync_time }))
+        code = response&.status.to_i
+        if e.is_a? NetworkError
+          code = e.http_code
+        end
+        init_diagnostics&.mark("download_config_specs", "end", "network_request", code)
+
         if e.nil?
-          if !response.nil? and process(response.body)
-            @init_reason = EvaluationReason::NETWORK
-            @rules_updated_callback.call(response.body.to_s, @last_config_sync_time) unless response.body.nil? or @rules_updated_callback.nil?
+          unless response.nil?
+            init_diagnostics&.mark("download_config_specs", "start", "process")
+
+            if process(response.body)
+              @init_reason = EvaluationReason::NETWORK
+              @rules_updated_callback.call(response.body.to_s, @last_config_sync_time) unless response.body.nil? or @rules_updated_callback.nil?
+            end
+
+            init_diagnostics&.mark("download_config_specs", "end", "process", @init_reason == EvaluationReason::NETWORK)
           end
+
           nil
         else
-          e
+          error = e
         end
       rescue StandardError => e
-        e
+        error = e
       end
+
+      @error_callback.call(error) unless error.nil? or @error_callback.nil?
     end
 
     def process(specs_string, from_adapter = false)
@@ -219,11 +241,13 @@ module Statsig
       true
     end
 
-    def get_id_lists
+    def get_id_lists(init_diagnostics = nil)
+      init_diagnostics&.mark("get_id_lists", "start", "network_request")
       response, e = @network.post_helper('get_id_lists', JSON.generate({ 'statsigMetadata' => Statsig.get_statsig_metadata }))
       if !e.nil? || response.nil?
         return
       end
+      init_diagnostics&.mark("get_id_lists", "end", "network_request", response.status.to_i)
 
       begin
         server_id_lists = JSON.parse(response)
@@ -233,6 +257,12 @@ module Statsig
         end
         tasks = []
 
+        if server_id_lists.length == 0
+          return
+        end
+
+        init_diagnostics&.mark("get_id_lists", "start", "process", server_id_lists.length)
+
         server_id_lists.each do |list_name, list|
           server_list = IDList.new(list)
           local_list = get_id_list(list_name)
@@ -267,6 +297,7 @@ module Statsig
 
         result = Concurrent::Promise.all?(*tasks).execute.wait(@id_lists_sync_interval)
         if result.state != :fulfilled
+          init_diagnostics&.mark("get_id_lists", "end", "process", false)
           return # timed out
         end
 
@@ -279,6 +310,7 @@ module Statsig
         delete_lists.each do |list_name|
           local_id_lists.delete list_name
         end
+        init_diagnostics&.mark("get_id_lists", "end", "process", true)
       rescue
         # Ignored, will try again
       end

data/lib/statsig.rb

@@ -2,11 +2,11 @@
 
 require 'statsig_driver'
 require 'sorbet-runtime'
+require 'statsig_errors'
 
 module Statsig
   extend T::Sig
 
-
   sig { params(secret_key: String, options: T.any(StatsigOptions, NilClass), error_callback: T.any(Method, Proc, NilClass)).void }
   ##
   # Initializes the Statsig SDK.
@@ -35,6 +35,28 @@ module Statsig
     @shared_instance&.check_gate(user, gate_name)
   end
 
+  sig { params(user: StatsigUser, gate_name: String).returns(T::Boolean) }
+  ##
+  # Gets the boolean result of a gate, evaluated against the given user.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param gate_name The name of the gate being checked
+  def self.check_gate_with_exposure_logging_disabled(user, gate_name)
+    ensure_initialized
+    @shared_instance&.check_gate(user, gate_name, StatsigDriver::CheckGateOptions.new(log_exposure: false))
+  end
+
+  sig { params(user: StatsigUser, gate_name: String).void }
+  ##
+  # Logs an exposure event for the gate
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param gate_name The name of the gate being checked
+  def self.manually_log_gate_exposure(user, gate_name)
+    ensure_initialized
+    @shared_instance&.manually_log_gate_exposure(user, gate_name)
+  end
+
   sig { params(user: StatsigUser, dynamic_config_name: String).returns(DynamicConfig) }
   ##
   # Get the values of a dynamic config, evaluated against the given user. An exposure event will automatically be logged for the dynamic config.
@@ -46,6 +68,28 @@ module Statsig
     @shared_instance&.get_config(user, dynamic_config_name)
   end
 
+  sig { params(user: StatsigUser, dynamic_config_name: String).returns(DynamicConfig) }
+  ##
+  # Get the values of a dynamic config, evaluated against the given user.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param dynamic_config_name The name of the dynamic config
+  def self.get_config_with_exposure_logging_disabled(user, dynamic_config_name)
+    ensure_initialized
+    @shared_instance&.get_config(user, dynamic_config_name, StatsigDriver::GetConfigOptions.new(log_exposure: false))
+  end
+
+  sig { params(user: StatsigUser, dynamic_config: String).void }
+  ##
+  # Logs an exposure event for the dynamic config
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param dynamic_config_name The name of the dynamic config
+  def self.manually_log_config_exposure(user, dynamic_config)
+    ensure_initialized
+    @shared_instance&.manually_log_config_exposure(user, dynamic_config)
+  end
+
   sig { params(user: StatsigUser, experiment_name: String).returns(DynamicConfig) }
   ##
   # Get the values of an experiment, evaluated against the given user. An exposure event will automatically be logged for the experiment.
@@ -57,6 +101,28 @@ module Statsig
     @shared_instance&.get_experiment(user, experiment_name)
   end
 
+  sig { params(user: StatsigUser, experiment_name: String).returns(DynamicConfig) }
+  ##
+  # Get the values of an experiment, evaluated against the given user.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param experiment_name The name of the experiment
+  def self.get_experiment_with_exposure_logging_disabled(user, experiment_name)
+    ensure_initialized
+    @shared_instance&.get_experiment(user, experiment_name, StatsigDriver::GetExperimentOptions.new(log_exposure: false))
+  end
+
+  sig { params(user: StatsigUser, experiment_name: String).void }
+  ##
+  # Logs an exposure event for the experiment
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param experiment_name The name of the experiment
+  def self.manually_log_experiment_exposure(user, experiment_name)
+    ensure_initialized
+    @shared_instance&.manually_log_config_exposure(user, experiment_name)
+  end
+
   sig { params(user: StatsigUser, layer_name: String).returns(Layer) }
   ##
   # Get the values of a layer, evaluated against the given user.
@@ -69,6 +135,29 @@ module Statsig
     @shared_instance&.get_layer(user, layer_name)
   end
 
+  sig { params(user: StatsigUser, layer_name: String).returns(Layer) }
+  ##
+  # Get the values of a layer, evaluated against the given user.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param layer_name The name of the layer
+  def self.get_layer_with_exposure_logging_disabled(user, layer_name)
+    ensure_initialized
+    @shared_instance&.get_layer(user, layer_name, StatsigDriver::GetLayerOptions.new(log_exposure: false))
+  end
+
+  sig { params(user: StatsigUser, layer_name: String, parameter_name: String).returns(Layer) }
+  ##
+  # Logs an exposure event for the parameter in the given layer
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param layer_name The name of the layer
+  # @param parameter_name The name of the parameter in the layer
+  def self.manually_log_layer_parameter_exposure(user, layer_name, parameter_name)
+    ensure_initialized
+    @shared_instance&.manually_log_layer_parameter_exposure(user, layer_name, parameter_name)
+  end
+
   sig { params(user: StatsigUser,
                event_name: String,
                value: T.any(String, Integer, Float, NilClass),
@@ -89,7 +178,7 @@ module Statsig
   ##
   # Stops all Statsig activity and flushes any pending events.
   def self.shutdown
-    unless @shared_instance.nil?
+    if defined? @shared_instance and !@shared_instance.nil?
       @shared_instance.shutdown
     end
     @shared_instance = nil
@@ -136,32 +225,32 @@ module Statsig
   def self.get_statsig_metadata
     {
       'sdkType' => 'ruby-server',
-      'sdkVersion' => '1.17.0',
+      'sdkVersion' => '1.19.0',
     }
   end
 
   private
 
   def self.ensure_initialized
-    if @shared_instance.nil?
-      raise 'Must call initialize first.'
+    if not defined? @shared_instance or @shared_instance.nil?
+      raise Statsig::UninitializedError.new
     end
   end
 
   T::Configuration.call_validation_error_handler = lambda do |signature, opts|
-    puts opts[:pretty_message]
+    puts "[Type Error] " + opts[:pretty_message]
   end
 
   T::Configuration.inline_type_error_handler = lambda do |error, opts|
-    puts error.message
+    puts "[Type Error] " + error.message
   end
 
   T::Configuration.sig_builder_error_handler = lambda do |error, location|
-    puts error.message
+    puts "[Type Error] " + error.message
   end
 
   T::Configuration.sig_validation_error_handler = lambda do |error, opts|
-    puts error.message
+    puts "[Type Error] " + error.message
   end
 
 end

data/lib/statsig_driver.rb

@@ -3,14 +3,17 @@
 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 'error_boundary'
 require 'layer'
 require 'sorbet-runtime'
+require 'diagnostics'
 
 class StatsigDriver
   extend T::Sig
@@ -19,132 +22,215 @@ class StatsigDriver
 
   def initialize(secret_key, options = nil, error_callback = nil)
     unless secret_key.start_with?('secret-')
-      raise 'Invalid secret key provided. Provide your project secret key from the Statsig console'
+      raise Statsig::ValueError.new('Invalid secret key provided. Provide your project secret key from the Statsig console')
     end
+
     if !options.nil? && !options.instance_of?(StatsigOptions)
-      raise 'Invalid options provided. Either provide a valid StatsigOptions object or nil'
+      raise Statsig::ValueError.new('Invalid options provided. Either provide a valid StatsigOptions object or nil')
     end
 
-    @options = options || StatsigOptions.new
-    @shutdown = false
-    @secret_key = secret_key
-    @net = Statsig::Network.new(secret_key, @options.api_url_base, @options.local_mode)
-    @logger = Statsig::StatsigLogger.new(@net, @options)
-    @evaluator = Statsig::Evaluator.new(@net, @options, error_callback)
+    @err_boundary = Statsig::ErrorBoundary.new(secret_key)
+    @err_boundary.capture(-> {
+      @init_diagnostics = Statsig::Diagnostics.new("initialize")
+      @init_diagnostics.mark("overall", "start")
+      @options = options || StatsigOptions.new
+      @shutdown = false
+      @secret_key = secret_key
+      @net = Statsig::Network.new(secret_key, @options.api_url_base, @options.local_mode)
+      @logger = Statsig::StatsigLogger.new(@net, @options)
+      @evaluator = Statsig::Evaluator.new(@net, @options, error_callback, @init_diagnostics)
+      @init_diagnostics.mark("overall", "end")
+
+      log_init_diagnostics
+    })
+  end
+
+  class CheckGateOptions < T::Struct
+    prop :log_exposure, T::Boolean, default: true
   end
 
-  sig { params(user: StatsigUser, gate_name: String).returns(T::Boolean) }
+  sig { params(user: StatsigUser, gate_name: String, options: CheckGateOptions).returns(T::Boolean) }
+
+  def check_gate(user, gate_name, options = CheckGateOptions.new)
+    @err_boundary.capture(-> {
+      user = verify_inputs(user, gate_name, "gate_name")
+
+      res = @evaluator.check_gate(user, gate_name)
+      if res.nil?
+        res = Statsig::ConfigResult.new(gate_name)
+      end
+
+      if res == $fetch_from_server
+        res = check_gate_fallback(user, gate_name)
+        # exposure logged by the server
+      else
+        if options.log_exposure
+          @logger.log_gate_exposure(user, res.name, res.gate_value, res.rule_id, res.secondary_exposures, res.evaluation_details)
+        end
+      end
+
+      res.gate_value
+    }, -> { false })
 
-  def check_gate(user, gate_name)
-    user = verify_inputs(user, gate_name, "gate_name")
+  end
 
+  sig { params(user: StatsigUser, gate_name: String).void }
+
+  def manually_log_gate_exposure(user, gate_name)
     res = @evaluator.check_gate(user, gate_name)
-    if res.nil?
-      res = Statsig::ConfigResult.new(gate_name)
-    end
+    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)
+  end
 
-    if res == $fetch_from_server
-      res = check_gate_fallback(user, gate_name)
-      # exposure logged by the server
-    else
-      @logger.log_gate_exposure(user, res.name, res.gate_value, res.rule_id, res.secondary_exposures, res.evaluation_details)
-    end
+  class GetConfigOptions < T::Struct
+    prop :log_exposure, T::Boolean, default: true
+  end
+
+  sig { params(user: StatsigUser, dynamic_config_name: String, options: GetConfigOptions).returns(DynamicConfig) }
 
-    res.gate_value
+  def get_config(user, dynamic_config_name, options = GetConfigOptions.new)
+    @err_boundary.capture(-> {
+      user = verify_inputs(user, dynamic_config_name, "dynamic_config_name")
+      get_config_impl(user, dynamic_config_name, options)
+    }, -> { DynamicConfig.new(dynamic_config_name) })
   end
 
-  sig { params(user: StatsigUser, dynamic_config_name: String).returns(DynamicConfig) }
+  class GetExperimentOptions < T::Struct
+    prop :log_exposure, T::Boolean, default: true
+  end
+
+  sig { params(user: StatsigUser, experiment_name: String, options: GetExperimentOptions).returns(DynamicConfig) }
 
-  def get_config(user, dynamic_config_name)
-    user = verify_inputs(user, dynamic_config_name, "dynamic_config_name")
-    get_config_impl(user, dynamic_config_name)
+  def get_experiment(user, experiment_name, options = GetExperimentOptions.new)
+    @err_boundary.capture(-> {
+      user = verify_inputs(user, experiment_name, "experiment_name")
+      get_config_impl(user, experiment_name, options)
+    }, -> { DynamicConfig.new(experiment_name) })
   end
 
-  sig { params(user: StatsigUser, experiment_name: String).returns(DynamicConfig) }
+  sig { params(user: StatsigUser, config_name: String).void }
 
-  def get_experiment(user, experiment_name)
-    user = verify_inputs(user, experiment_name, "experiment_name")
-    get_config_impl(user, experiment_name)
+  def manually_log_config_exposure(user, config_name)
+    res = @evaluator.get_config(user, config_name)
+    context = {'is_manual_exposure' => true}
+    @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures, res.evaluation_details, context)
   end
 
-  sig { params(user: StatsigUser, layer_name: String).returns(Layer) }
+  class GetLayerOptions < T::Struct
+    prop :log_exposure, T::Boolean, default: true
+  end
 
-  def get_layer(user, layer_name)
-    user = verify_inputs(user, layer_name, "layer_name")
+  sig { params(user: StatsigUser, layer_name: String, options: GetLayerOptions).returns(Layer) }
 
-    res = @evaluator.get_layer(user, layer_name)
-    if res.nil?
-      res = Statsig::ConfigResult.new(layer_name)
-    end
+  def get_layer(user, layer_name, options = GetLayerOptions.new)
+    @err_boundary.capture(-> {
+      user = verify_inputs(user, layer_name, "layer_name")
 
-    if res == $fetch_from_server
-      if res.config_delegate.empty?
-        return Layer.new(layer_name)
+      res = @evaluator.get_layer(user, layer_name)
+      if res.nil?
+        res = Statsig::ConfigResult.new(layer_name)
       end
-      res = get_config_fallback(user, res.config_delegate)
-      # exposure logged by the server
-    end
 
-    Layer.new(res.name, res.json_value, res.rule_id, lambda { |layer, parameter_name|
-      @logger.log_layer_exposure(user, layer, parameter_name, res)
+      if res == $fetch_from_server
+        if res.config_delegate.empty?
+          return Layer.new(layer_name)
+        end
+        res = get_config_fallback(user, res.config_delegate)
+        # exposure logged by the server
+      end
+      
+      exposure_log_func = options.log_exposure ? lambda { |layer, parameter_name|
+        @logger.log_layer_exposure(user, layer, parameter_name, res)
+      } : nil
+      Layer.new(res.name, res.json_value, res.rule_id, exposure_log_func)
+    }, -> {
+      Layer.new(layer_name)
     })
   end
 
+  sig { params(user: StatsigUser, layer_name: String, parameter_name: String).void }
+
+  def manually_log_layer_parameter_exposure(user, layer_name, parameter_name)
+    res = @evaluator.get_layer(user, layer_name)
+    layer = Layer.new(layer_name, res.json_value, res.rule_id)
+    context = {'is_manual_exposure' => true}
+    @logger.log_layer_exposure(user, layer, parameter_name, res, context)
+  end
+
   def log_event(user, event_name, value = nil, metadata = nil)
-    if !user.nil? && !user.instance_of?(StatsigUser)
-      raise 'Must provide a valid StatsigUser or nil'
-    end
-    check_shutdown
+    @err_boundary.capture(-> {
+      if !user.nil? && !user.instance_of?(StatsigUser)
+        raise Statsig::ValueError.new('Must provide a valid StatsigUser or nil')
+      end
+      check_shutdown
 
-    user = normalize_user(user)
+      user = normalize_user(user)
 
-    event = StatsigEvent.new(event_name)
-    event.user = user
-    event.value = value
-    event.metadata = metadata
-    event.statsig_metadata = Statsig.get_statsig_metadata
-    @logger.log_event(event)
+      event = StatsigEvent.new(event_name)
+      event.user = user
+      event.value = value
+      event.metadata = metadata
+      event.statsig_metadata = Statsig.get_statsig_metadata
+      @logger.log_event(event)
+    })
   end
 
   def shutdown
-    @shutdown = true
-    @logger.shutdown
-    @evaluator.shutdown
+    @err_boundary.capture(-> {
+      @shutdown = true
+      @logger.shutdown
+      @evaluator.shutdown
+    })
   end
 
   def override_gate(gate_name, gate_value)
-    @evaluator.override_gate(gate_name, gate_value)
+    @err_boundary.capture(-> {
+      @evaluator.override_gate(gate_name, gate_value)
+    })
   end
 
   def override_config(config_name, config_value)
-    @evaluator.override_config(config_name, config_value)
+    @err_boundary.capture(-> {
+      @evaluator.override_config(config_name, config_value)
+    })
   end
 
   # @param [StatsigUser] user
   # @return [Hash]
   def get_client_initialize_response(user)
-    normalize_user(user)
-    @evaluator.get_client_initialize_response(user)
+    @err_boundary.capture(-> {
+      normalize_user(user)
+      @evaluator.get_client_initialize_response(user)
+    }, -> { nil })
   end
 
   def maybe_restart_background_threads
-    @evaluator.maybe_restart_background_threads
-    @logger.maybe_restart_background_threads
+    if @options.local_mode
+      return
+    end
+
+    @err_boundary.capture(-> {
+      @evaluator.maybe_restart_background_threads
+      @logger.maybe_restart_background_threads
+    })
   end
 
   private
 
+  sig { params(user: StatsigUser, config_name: String, variable_name: String).returns(StatsigUser) }
+
   def verify_inputs(user, config_name, variable_name)
     validate_user(user)
     if !config_name.is_a?(String) || config_name.empty?
-      raise "Invalid #{variable_name} provided"
+      raise Statsig::ValueError.new("Invalid #{variable_name} provided")
     end
 
     check_shutdown
+    maybe_restart_background_threads
     normalize_user(user)
   end
 
-  def get_config_impl(user, config_name)
+  def get_config_impl(user, config_name, options)
     res = @evaluator.get_config(user, config_name)
     if res.nil?
       res = Statsig::ConfigResult.new(config_name)
@@ -154,7 +240,9 @@ class StatsigDriver
       res = get_config_fallback(user, config_name)
       # exposure logged by the server
     else
-      @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures, res.evaluation_details)
+      if options.log_exposure
+        @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures, res.evaluation_details)
+      end
     end
 
     DynamicConfig.new(res.name, res.json_value, res.rule_id)
@@ -168,7 +256,7 @@ class StatsigDriver
         !user.user_id.is_a?(String) &&
           (!user.custom_ids.is_a?(Hash) || user.custom_ids.size == 0)
       )
-      raise 'Must provide a valid StatsigUser with a user_id or at least a custom ID. See https://docs.statsig.com/messages/serverRequiredUserID/ for more details.'
+      raise Statsig::ValueError.new('Must provide a valid StatsigUser with a user_id or at least a custom ID. See https://docs.statsig.com/messages/serverRequiredUserID/ for more details.')
     end
   end
 
@@ -214,4 +302,12 @@ class StatsigDriver
       network_result['rule_id'],
     )
   end
-end
+
+  def log_init_diagnostics
+    if @options.disable_diagnostics_logging
+      return
+    end
+
+    @logger.log_diagnostics_event(@init_diagnostics)
+  end
+end

data/lib/statsig_errors.rb

@@ -0,0 +1,11 @@
+module Statsig
+  class UninitializedError < StandardError
+    def initialize(msg="Must call initialize first.")
+      super
+    end
+  end
+
+  class ValueError < StandardError
+
+  end
+end

data/lib/statsig_logger.rb

@@ -5,6 +5,7 @@ require 'concurrent-ruby'
 $gate_exposure_event = 'statsig::gate_exposure'
 $config_exposure_event = 'statsig::config_exposure'
 $layer_exposure_event = 'statsig::layer_exposure'
+$diagnostics_event = 'statsig::diagnostics'
 
 module Statsig
   class StatsigLogger
@@ -31,7 +32,7 @@ module Statsig
       end
     end
 
-    def log_gate_exposure(user, gate_name, value, rule_id, secondary_exposures, eval_details)
+    def log_gate_exposure(user, gate_name, value, rule_id, secondary_exposures, eval_details, context = nil)
       event = StatsigEvent.new($gate_exposure_event)
       event.user = user
       event.metadata = {
@@ -43,10 +44,11 @@ module Statsig
       event.secondary_exposures = secondary_exposures.is_a?(Array) ? secondary_exposures : []
 
       safe_add_eval_details(eval_details, event)
+      safe_add_exposure_context(context, event)
       log_event(event)
     end
 
-    def log_config_exposure(user, config_name, rule_id, secondary_exposures, eval_details)
+    def log_config_exposure(user, config_name, rule_id, secondary_exposures, eval_details, context = nil)
       event = StatsigEvent.new($config_exposure_event)
       event.user = user
       event.metadata = {
@@ -57,10 +59,11 @@ module Statsig
       event.secondary_exposures = secondary_exposures.is_a?(Array) ? secondary_exposures : []
 
       safe_add_eval_details(eval_details, event)
+      safe_add_exposure_context(context, event)
       log_event(event)
     end
 
-    def log_layer_exposure(user, layer, parameter_name, config_evaluation)
+    def log_layer_exposure(user, layer, parameter_name, config_evaluation, context = nil)
       exposures = config_evaluation.undelegated_sec_exps
       allocated_experiment = ''
       is_explicit = (config_evaluation.explicit_parameters&.include? parameter_name) || false
@@ -82,6 +85,14 @@ module Statsig
       event.secondary_exposures = exposures.is_a?(Array) ? exposures : []
 
       safe_add_eval_details(config_evaluation.evaluation_details, event)
+      safe_add_exposure_context(context, event)
+      log_event(event)
+    end
+
+    def log_diagnostics_event(diagnostics, user = nil)
+      event = StatsigEvent.new($diagnostics_event)
+      event.user = user
+      event.metadata = diagnostics.serialize
       log_event(event)
     end
 
@@ -136,5 +147,15 @@ module Statsig
       event.metadata['initTime'] = eval_details.init_time
       event.metadata['serverTime'] = eval_details.server_time
     end
+
+    def safe_add_exposure_context(context, event)
+      if context.nil?
+        return
+      end
+
+      if context['is_manual_exposure']
+        event.metadata['isManualExposure'] = 'true'
+      end
+    end
   end
 end

data/lib/statsig_options.rb

@@ -64,6 +64,11 @@ class StatsigOptions
   # default: 3
   attr_accessor :idlist_threadpool_size
 
+  sig { returns(T::Boolean) }
+  # Should diagnostics be logged. These include performance metrics for initialize.
+  # default: false
+  attr_accessor :disable_diagnostics_logging
+
   sig do
     params(
       environment: T.any(T::Hash[String, String], NilClass),
@@ -76,7 +81,8 @@ class StatsigOptions
       bootstrap_values: T.any(String, NilClass),
       rules_updated_callback: T.any(Method, Proc, NilClass),
       data_store: T.any(Statsig::Interfaces::IDataStore, NilClass),
-      idlist_threadpool_size: Integer
+      idlist_threadpool_size: Integer,
+      disable_diagnostics_logging: T::Boolean
     ).void
   end
 
@@ -91,7 +97,8 @@ class StatsigOptions
     bootstrap_values: nil,
     rules_updated_callback: nil,
     data_store: nil,
-    idlist_threadpool_size: 3)
+    idlist_threadpool_size: 3,
+    disable_diagnostics_logging: false)
     @environment = environment.is_a?(Hash) ? environment : nil
     @api_url_base = api_url_base
     @rulesets_sync_interval = rulesets_sync_interval
@@ -103,5 +110,6 @@ class StatsigOptions
     @rules_updated_callback = rules_updated_callback
     @data_store = data_store
     @idlist_threadpool_size = idlist_threadpool_size
+    @disable_diagnostics_logging = disable_diagnostics_logging
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statsig
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.19.0
 platform: ruby
 authors:
 - Statsig, Inc
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-01 00:00:00.000000000 Z
+date: 2022-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.10461
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.10461
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.4.27
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.4.27
 - !ruby/object:Gem::Dependency
   name: user_agent_parser
   requirement: !ruby/object:Gem::Requirement
@@ -118,16 +146,16 @@ dependencies:
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.10461
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.10461
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -150,7 +178,9 @@ extra_rdoc_files: []
 files:
 - lib/client_initialize_helpers.rb
 - lib/config_result.rb
+- lib/diagnostics.rb
 - lib/dynamic_config.rb
+- lib/error_boundary.rb
 - lib/evaluation_details.rb
 - lib/evaluation_helpers.rb
 - lib/evaluator.rb
@@ -161,6 +191,7 @@ files:
 - lib/spec_store.rb
 - lib/statsig.rb
 - lib/statsig_driver.rb
+- lib/statsig_errors.rb
 - lib/statsig_event.rb
 - lib/statsig_logger.rb
 - lib/statsig_options.rb
@@ -184,7 +215,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.22
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Statsig server SDK for Ruby