Ruby SDK

Use the Harness FME Ruby SDK to implement server-side feature management and experiments in Ruby on Rails or vanilla Ruby apps.

This guide provides detailed information about our Ruby SDK. All of our SDKs are open source. Go to our Ruby SDK GitHub repository to learn more.

RULE-BASED SEGMENTS SUPPORT

Rule-based segments are supported in SDK versions 8.6.0 and above. No changes are required to your SDK implementation, but updating to a supported version is required to ensure compatibility.

Older SDK versions will return the control treatment for flags using rule-based segments and log an impression with a special label for unsupported targeting rules.

Initialization

1. Import the SDK into your project

gem install splitclient-rb -v '~> 8.11.3'

gem install splitclient-rb -v '~> 8.11.3'

IF USING SYNCHRONIZER WITH REDIS - SYNCHRONIZER 2.X REQUIRED AFTER SDK VERSION 3.X

Since version 2.0.0 of the split-synchronizer, we use a more efficient scheme to store impressions in Redis. This approach is faster and easier on your Redis instances, since it yields better throughput of impressions to the backend. If you use this SDK with the Synchronizer in Redis or Proxy mode, you need the newest versions of our Split Synchronizer. We recommend that once you're using SDK versions compatible with Split-Sync 2.0 on all your applications pointing to the redis instance maintained by the Split-Sync, you disable backwards compatibility. This is as easy as changing a parameter to true on the JSON config or an environment variable to on if you're using the docker image.

2. Instantiate the SDK and create a new SDK factory client

When the SDK is instantiated, it starts background tasks to update an in-memory cache with small amounts of data fetched from Harness servers. This process can take up to a few hundred milliseconds, depending on the size of data. If the SDK is asked to evaluate which treatment to show to a customer for a specific feature flag while its in this intermediate state, it may not have the data necessary to run the evaluation. In this case, the SDK does not fail, rather, it returns the control treatment.

To make sure the SDK is properly loaded before asking it for a treatment, block it until the SDK is ready. You can do this by using the block_until_ready method of the SDK factory client (or Manager) as part of the instantiation process of the SDK as shown below. Do this as a part of the startup sequence of your application.

We recommend instantiating the SDK factory once as a singleton and reusing it throughout your application.

Configure the SDK with the SDK key for the FME environment that you would like to access. In legacy Split (app.split.io) the SDK key is found on your Admin settings page, in the API keys section. Select a server-side SDK API key. See API keys to learn more.

require 'splitclient-rb'

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY')
split_client = split_factory.client

begin
  split_client.block_until_ready
rescue SplitIoClient::SDKBlockerTimeoutExpiredException
  puts 'SDK is not ready. Decide whether to continue or abort execution'
end

Configure the SDK for use with Rails

Our SDK is compatible with Ruby on Rails. There are a few extra steps for the initialization. You can configure the SDK to work with Rails with the code snippet below.

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY')
Rails.configuration.split_client = split_factory.client

To access the SDK factory client in your controllers, use the code snippet below:

Rails.application.config.split_client

Now you can start asking the SDK to evaluate treatments for your customers.

SDK Server Compatibility

The Ruby SDK has been tested as a standalone app using the following web servers:

Puma
Passenger
Unicorn

For other setups, contact support@split.io.

Unicorn and Puma in cluster mode

Note: This is only applicable when using "memory storage".

During the start of your application, the SDK spawns multiple threads. Each thread has an infinite loop inside, which is used to fetch feature flags/segments or send impressions/events to the FME service continuously. When using Unicorn or Puma in cluster mode (i.e. with workers > 0) the application server will spawn multiple child processes, but they won't recreate the threads that existed in the parent process. So, if your application is running in Unicorn or Puma in cluster mode you need to make two small extra steps.

For both servers, you need to have the following line in your config/initializers/splitclient.rb:

Rails.configuration.split_factory = factory

Find below the specific setup for each one:

Unicorn

If you’re using Unicorn in cluster mode, you’ll need to include these lines in your Unicorn config (likely config/unicorn.rb):

before_fork do |server, worker|
  ## keep your existing before_fork code if any
  Rails.configuration.split_factory.stop!
end
after_fork do |server, worker|
  ## keep your existing after_fork code if any
  Rails.configuration.split_factory.resume!
end

Puma

If using Puma in cluster mode, add these lines to your Puma config (likely config/puma.rb):

before_fork do
  ## keep your existing before_fork code if any
  Rails.configuration.split_factory.stop!
end
on_worker_boot do
  ## keep your existing on_worker_boot code if any
  Rails.configuration.split_factory.resume!
end

By doing the above, the SDK recreates the threads for each new worker and prevents the master process (that doesn't handle requests) from needlessly querying the service.

SERVER SPAWNING METHOD

If you are running NGINX with thread_spawn_method = 'smart', use our Redis integration with the Split Synchronizer or contact support@split.io for alternatives to run FME.

Use the SDK

Basic use

After you instantiate the SDK factory client, you can start using the get_Treatment method of the SDK factory client to decide what version of your features your customers are served. The method requires the FEATURE_FLAG_NAME attribute that you want to ask for a treatment and a unique KEY attribute that corresponds to the end user that you want to serve the feature to.

From there, you simply need to use an if-else-if block as shown below and insert the code for the different treatments that you defined in Harness FME. Remember the final else branch in your code to handle the client returning the control treatment.

## The key here represents the ID of the user, account, etc. you're trying to evaluate a treatment for <a href="#the-key-here-represents-the-id-of-the-user-account-etc-youre-trying-to-evaluate-a-treatment-for" id="the-key-here-represents-the-id-of-the-user-account-etc-youre-trying-to-evaluate-a-treatment-for"></a>
treatment = split_client.get_treatment('KEY', 'FEATURE_FLAG_NAME');

if treatment == 'on'
  ## insert code here to show on treatment
elsif treatment == 'off'
  ## insert code here to show off treatment
else
  ## insert your control treatment code here
end

Attribute syntax

To target based on custom attributes, the SDK's get_treatment method needs to be passed an attribute map at runtime.

In the example below, we are rolling out a feature flag to users. The provided attributes plan_type, registered_date, permissions, paying_customer, and deal_size are passed to the get_treatment call. These attributes are compared and evaluated against the attributes used in the rollout plan as defined in Harness FME to decide whether to show the on or off treatment to this account.

The get_treatment method supports five types of attributes: strings, numbers, dates, booleans, and sets. The proper data type and syntax for each are:

Strings: Use type String.
Numbers: Use type long or int.
Dates: Express the value as seconds since epoch and as objects of class DateTime.
Booleans: Use type Boolean.
Sets: Use type List<string>.

attributes = {}
attributes[:deal_size] = 10000
attributes[:registered_date] = Time.now.to_i ## any time as seconds since epoch
attributes[:plan_type] = "growth"
attributes[:permissions] = ['read', 'write']
attributes[:paying_customer] = true

treatment = split_client.get_treatment("KEY",
                                       "FEATURE_FLAG_NAME",
                                       attributes)

if treatment == 'on'
    ## insert on code here
 elsif treatment == 'off'
    ## insert off code here
 else
    ## insert control code here
end

Multiple evaluations at once

In some instances, you may want to evaluate treatments for multiple feature flag at once. Use the different variations of get_treatments method from the SDK factory client to do this.

get_treatments': Pass a list of the feature flag names you want treatments for.
get_treatments_by_flag_set: Evaluate all flags that are part of the provided set name and are cached on the SDK instance.
get_treatments_by_flag_sets: Evaluate all flags that are part of the provided set names and are cached on the SDK instance.

attributes = {}
split_client.get_treatments('key', ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'], attributes)

attributes = {}
treatments = split.get_treatments_by_flag_set('key', 'backend', attributes)

attributes = {}
treatments = split.get_treatments_by_flag_sets('key', ['backend', 'server_side'], attributes)

You can also use the Split Manager if you want to get all of your treatments at once.

Get treatments with configurations

To leverage dynamic configurations with your treatments, you should use the get_treatment_with_config method.

This method will return an object containing the treatment and associated configuration.

The config element will be a stringified version of the configuration JSON defined in Harness FME. If there are no configs defined for a treatment, the SDK returns None for the config parameter.

This method takes the exact same set of arguments as the standard get_treatment method. See below for examples on proper usage:

result = client.get_treatment_with_config('key', 'new_boxes', attributes)
configs = JSON.parse(result[:config])
treatment = result[:treatment]

If you need to get multiple evaluations at once, you can also use the get_treatments_with_config methods. These methods take the exact same arguments as the get_treatments methods but return a mapping of feature flag names to SplitResult objects instead of strings. Example usage below.


feature_flag_names = ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2']
feature_flag_results = client.get_treatments_with_config('KEY', feature_flag_names)

 ## feature_flag_results will have the following format:
 ## {
 ##   'FEATURE_FLAG_NAME_1': ('on', '{"color": "red"}'),
 ##   'FEATURE_FLAG_NAME_2': ('v2', '{"copy": "better copy"}')
 ## }

attributes = {}
result = split.get_treatments_with_config_by_flag_set('key', 'backend', attributes)
result.each do |feature_flag, treatment_with_config|
 configs = JSON.parse(treatment_with_config[:config])
 treatment = treatment_with_config[:treatment]
 puts "Feature: #{feature_flag}, Treatment: #{treatment}, Config: #{configs}"
end

attributes = {}
result = split.get_treatments_with_config_by_flag_sets('key', ['backend', 'server_side'], attributes)
result.each do |feature_flag, treatment_with_config|
 configs = JSON.parse(treatment_with_config[:config])
 treatment = treatment_with_config[:treatment]
 puts "Feature: #{feature_flag}, Treatment: #{treatment}, Config: #{configs}"
end

If a flag cannot be evaluated, the SDK returns the fallback treatment value (default "control" unless overridden globally or per flag). For more information, see Fallback treatments.

Append properties to impressions

Impressions are generated by the SDK each time a getTreatment method is called. These impressions are periodically sent back to Harness servers for feature monitoring and experimentation.

You can append properties to an impression by passing an object of key-value pairs to the getTreatment method. These properties are then included in the impression sent by the SDK and can provide useful context to the impression data.

Three types of properties are supported: strings, numbers, and booleans.

# Define impression properties <a href="#define-impression-properties" id="define-impression-properties"></a>
evaluation_option = SplitIoClient::Engine::Models::EvaluationOptions.new = ({
  :userType => 'premium',  # string
  :loginCount => 42,       # number
  :isAdmin => true         # boolean
}

# Get treatment with properties <a href="#get-treatment-with-properties" id="get-treatment-with-properties"></a>
treatment = split_client.get_treatment('KEY', 'FEATURE_FLAG_NAME', {}, evaluation_option)

if treatment == 'on'
  # Show ON treatment
elsif treatment == 'off'
  # Show OFF treatment
else
  # Control treatment
end

Shutdown

Call the .destroy method before letting a process using the SDK exit, as this method gracefully shuts down the SDK by stopping all background threads, clearing caches, closing connections, and flushing the remaining unpublished impressions.

client.destroy

Note: Within multi-threaded setups like using Ruby with Rails and Puma, to fully destroy the factory, you need to set it to nil as follows: Rails.configuration.split_factory = nil

IMPORTANT!

A call to the destroy() method also destroys the factory object. When creating new client instance, first create a new factory instance.

Track

Use the track method to record any actions your customers perform. Each action is known as an event and corresponds to an event type. Calling track through one of our SDKs or via the API is the first step to and allows you to measure the impact of your feature flags on your users’ actions and metrics.

Learn more about using track events in feature flags.

In the examples below, you can see that the .track() method can take up to four arguments. The proper data type and syntax for each are:

key: The key variable used in the get_treatment call and firing this track event. The expected data type is String.
TRAFFIC_TYPE: The traffic type of the key in the track call. The expected data type is String. You can only pass values that match the names of traffic types that you have defined in Harness FME.
EVENT_TYPE: The event type that this event should correspond to. The expected data type is String. Full requirements on this argument are:
- Contains 63 characters or fewer.
- Starts with a letter or number.
- Contains only letters, numbers, hyphen, underscore, or period.
- This is the regular expression we use to validate the value: [a-zA-Z0-9][-_\.a-zA-Z0-9]{0,62}
VALUE: (Optional) The value used in creating the metric. This field can be sent in as nil or 0 if you intend to only use the count function when creating a metric. The expected data type is Integer or Float.
PROPERTIES: (Optional) A Hash of key value pairs that can be used to filter your metrics. Learn more about event property capture in the Events guide. FME currently supports three types of properties: strings, numbers, and booleans.

The track method returns a boolean value of true or false to indicate whether or not the SDK successfully queued the event to be sent back to Harness servers on the next event post. The SDK returns false if the current queue size is equal to the config set by events_queue_size or if an incorrect input to the track method is provided.

In the case that a bad input has been provided, refer to the Events guide for more information about our SDK's expected behavior.

## If you would like to send an event without a value <a href="#if-you-would-like-to-send-an-event-without-a-value" id="if-you-would-like-to-send-an-event-without-a-value"></a>
track_event = split_client.track('KEY', 'TRAFFIC_TYPE', 'EVENT_TYPE')

## Example <a href="#example" id="example"></a>
track_event = split_client.track('john@doe.com', 'user', 'page_load_time')

## If you would like to associate a value to an event <a href="#if-you-would-like-to-associate-a-value-to-an-event" id="if-you-would-like-to-associate-a-value-to-an-event"></a>
track_event = split_client.track('KEY', 'TRAFFIC_TYPE', 'EVENT_TYPE', VALUE)

## Example <a href="#example" id="example"></a>
track_event = split_client.track('john@doe.com', 'user', 'page_load_time', 83.334)

## If you would like to associate just properties to an event <a href="#if-you-would-like-to-associate-just-properties-to-an-event" id="if-you-would-like-to-associate-just-properties-to-an-event"></a>
track_event = split_client.track('KEY', 'TRAFFIC_TYPE', 'EVENT_TYPE', nil, { PROPERTIES })

## If you would like to associate a value and properties to an event <a href="#if-you-would-like-to-associate-a-value-and-properties-to-an-event" id="if-you-would-like-to-associate-a-value-and-properties-to-an-event"></a>
track_event = split_client.track('KEY', 'TRAFFIC_TYPE', 'EVENT_TYPE', VALUE, { PROPERTIES })

## Example <a href="#example" id="example"></a>
properties = {
  package: 'premium',
  admin: true,
  discount: 50
}

track_event = split_client.track('john@doe.com', 'user', 'page_load_time', nil, properties)

Configuration

The SDK has a number of knobs for configuring performance. Each knob is tuned to a reasonable default. However, you can override the value while instantiating the SDK. The parameters available for configuration are described below:

Configuration

Description

Default value

block_until_ready

Maximum time (in seconds) the SDK blocks waiting for readiness during initialization. If the SDK does not become ready within this period, it raises a SDKBlockerTimeoutExpiredException.

15s

logger

The log implementation to use for warnings and errors from the SDK.

Logs to STDOUT

debug_enabled

Enabled verbose mode.

false

transport_debug_enabled

Super verbose mode that prints network payloads among others.

false

connection_timeout

HTTP client connection timeout (in seconds).

read_timeout

HTTP socket read timeout (in seconds).

features_refresh_rate

The SDK polls Harness servers for changes to feature flags at this period (in seconds).

60s

segments_refresh_rate

The SDK polls Harness servers for changes to segments at this period (in seconds).

60s

telemetry_refresh_rate

The SDK caches diagnostic data that it periodically sends to Harness servers. This configuration controls how frequently this data is sent back to Harness servers (in seconds).

3600s

impressions_refresh_rate

How often impressions are sent out (in seconds).

300s

events_push_rate

How often events are sent out (in seconds).

60s

cache_adapter

Where to store feature flags and impressions: :memory or :redis

:memory

redis_url

Redis URL or hash with configuration for SDK to connect to. See http://www.rubydoc.info/github/redis/redis-rb/Redis%3Ainitialize

'redis://127.0.0.1:6379/0'

mode

Whether the SDK is running in standalone mode using memory storage or consumer mode using an external storage. See Redis integration.

:standalone

redis_namespace

Prefix to add to elements in Redis cache when having to share Redis with other applications.

"SPLITIO/ruby-#{VERSION}"

labels_enabled

Disable labels from being sent to the Harness servers. Labels may contain sensitive information.

true

impressions_queue_size

The size of the impressions queue in case of cache_adapter == :memory.

5000

events_queue_size

The size of the events queue in case of cache_adapter == :memory.

500

impressions_bulk_size

Max number of impressions to be sent to the backend on each post.

impressions_queue_size

ip_addresses_enabled

Flag to disable IP addresses and host name from being sent to the Harness servers.

true

streaming_enabled

Boolean flag to enable the streaming service as default synchronization mechanism. In the event of an issue with streaming, the SDK will fallback to the polling mechanism. If false, the SDK will poll for changes as usual without attempting to use streaming.

true

impressions_mode

Defines how impressions are queued on the SDK. Supported modes are OPTIMIZED(:optimized), NONE(:none), and DEBUG(:debug). In OPTIMIZED mode, only unique impressions are queued and posted to Harness; this is the recommended mode for experimentation use cases. In NONE mode, no impression is tracked in Harness FME and only minimum viable data to support usage stats is, so never use this mode if you are experimenting with that instance impressions. Use NONE when you want to optimize for feature flagging only use cases and reduce impressions network and storage load. In DEBUG mode, all impressions are queued and sent to Harness; this is useful for validations. Use DEBUG mode when you want every impression to be logged in Harness when trying to debug your SDK setup. This setting does not impact the impression listener which receives all generated impressions locally.

:optimized

flag_sets_filter

This setting allows the SDK to only synchronize the feature flags in the specified flag sets, avoiding unused or unwanted flags from being synced on the SDK instance, bringing all the benefits from a reduced payload.

nil

To set each of these parameters, use the syntax below:

options = {connection_timeout: 10,
           read_timeout: 5,
           impressions_refresh_rate: 360,
           logger: Logger.new('logfile.log')}

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY', options)
split_client = split_factory.client

Configuring this Redis integration section is optional for most setups. Read the information below to determine if it might be useful for your project.

By default, the SDK factory client stores the state it needs to compute treatments (rollout plans, segments, and so on) in memory. As a result, it is easy to get set up with FME by instantiating a client and starting to use it. Configuring this Redis integration section is optional for most setups.

This simplicity hides one important detail that is worth exploring. Because each SDK factory client downloads and stores state separately, a change in a feature flag is picked up by every client on its own schedule. Thus, if a customer issues back-to-back requests that are served by two different machines behind a load balancer, the customer can see different treatments for the same feature flag because one SDK factory client may not have picked up the latest change. This drift in clients is natural and usually ignorable as long as each client sets an aggressive value for features_refresh_rate and segments_refresh_rate. You can learn more about setting these rates in the Configuration section.

However, if your application requires a total guarantee that SDK clients across your entire infrastructure pick up a change in a feature flag at the exact same time, the only way to ensure that is to externalize the state of the SDK factory client in a data store hosted on your infrastructure.

We currently support Redis for this external data store.

To use the Ruby SDK with Redis, set up the Split Synchronizer and instantiate the SDK in consumer mode.

Split Synchronizer

Follow the steps in our Split Synchronizer document to get everything set to sync data to your Redis cache. After you do that, you can set up the SDK in consumer mode.

Consumer Mode

In consumer mode, a client can be embedded in your application code and respond to calls to get_treatment by retrieving state from the data store (Redis in this case).

Here is how to configure and get treatments for a SDK factory client in consumer mode.

options = {
  ## Other options here
  cache_adapter: :redis,
  mode: :consumer,
  redis_url: 'redis://127.0.0.1:6379/0'
}

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY', options)
split_client = split_factory.client

Configure Redis using Sentinel

Use the syntax below to configure Redis using Sentinel:

SENTINELS = [{host: '127.0.0.1', port: 26380},
             {host: '127.0.0.1', port: 26381}]

redis_connection = {
  url: 'redis://mymaster',
  sentinels: SENTINELS,
  role: :master
}

options = {
  ## Other options here
  redis_url: redis_connection
}

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY', options)
split_client = split_factory.client

Localhost mode

Features start their life on one developer's machine. A developer should be able to put code behind feature flags on their development machine without the SDK requiring network connectivity. To achieve this, the SDK can be started in localhost mode (aka off-the-grid mode). In this mode, the SDK neither polls nor updates Harness servers. Instead, it uses an in-memory data structure to determine what treatments to show to the logged in customer for each of the features.

To use the SDK in localhost mode, replace the SDK Key with "localhost", as shown in the example below:

require 'splitclient-rb'
split_file = File.expand_path(File.join(File.dirname(__FILE__), '../test_data/local_treatments/split.yaml'))

split_client = split_factory = SplitIoClient::SplitFactory.new('localhost', split_file: split_file).client

In this mode, the SDK loads a .yaml file containing a simple depiction of a feature flag. eg:

- single_key_feature:
    treatment: 'on'
    keys: 'john_doe'
    config: {'desc': 'this applies only to ON and only for john_doe. The rest will receive OFF'}
- single_key_feature:
    treatment: 'off'
    keys:
    config: {'desc': 'this applies only to OFF treatment'}

In the example given, a call to get_treatment passing john_doe as the key renders the on treatment, while as any other key receives off. Note that configs can be added to test the _with_config versions of get_treatment and get_treatments. Also, you can set multiple keys for the same treatment using an array:

- multiple_keys_feature:
    treatment: 'on'
    keys: ['john_doe', 'jane_doe']
    config: {'desc': 'this applies only to ON and only for john_doe and jane_doe. The rest will receive OFF'}

Any feature that is not provided in the split_file markup map returns the control treatment if the SDK is asked to evaluate them.

By default, changes in the file are not automatically picked up without restarting the client. To have the client automatically pick up changes to the file, specify reload_rate as the interval in seconds at which changes are picked up. Here is an example of specifying both split_file and reload_rate.

factory = SplitIoClient::SplitFactoryBuilder.build('localhost', split_file: '/where/to-look-for/<file_name>', reload_rate: 3)

Manager

Use the Split Manager to get a list of feature flags available to the SDK factory client. To instantiate a Manager in your code base, use the same factory that you used for your client.

## Reusing the split_factory created originally. <a href="#reusing-the-splitfactory-created-originally" id="reusing-the-splitfactory-created-originally"></a>
split_manager = split_factory.manager

The SplitView object referenced above has the following structure.

## returns a List of SplitViews or empty. <a href="#returns-a-list-of-splitviews-or-empty" id="returns-a-list-of-splitviews-or-empty"></a>
list_of_feature_flags = split_manager.splits

## Array of String representing feature flag names <a href="#array-of-string-representing-feature-flag-names" id="array-of-string-representing-feature-flag-names"></a>
list_of_feature_flag_names = split_manager.split_names

## returns a SplitView of the 'name' specified or empty. <a href="#returns-a-splitview-of-the-name-specified-or-empty" id="returns-a-splitview-of-the-name-specified-or-empty"></a>
feature_flag = split_manager.split(name)

The feature_flag object referenced above has the following structure.

{
 :name=>"new_reporting",
 :traffic_type_name=>"user",
 :killed=>false,
 :treatments=>["v1", "v2", "v3"],
 :change_number=>1469134003507,
 :configs=>{:on=>"{\"size\":15,\"test\":20}"},
 :default_treatment=>"off",
 :sets>=["backend"],
 :impressions_disabled=>false
}

Listener

FME SDKs send impression data back to Harness servers periodically when evaluating feature flags. To send this information to a location of your choice, define and attach an impression listener.

The SDK sends the generated impressions to the impression listener right away. However, to avoid blocking the caller thread, use the second parameter to specify the size of the queue acting as a buffer. Refer to the followoing snippet:

If the impression listener is slow at processing the incoming data, the queue fills up and any subsequent impressions are dropped.

class MyImpressionListener
  def log(impression)
    Logger.new($stdout).info(impression)
  end
end

options = {
  ## other options
  impression_listener: MyImpressionListener.new ## do remember to initialize your class here
  ## other options
}

factory = SplitIoClient::SplitFactoryBuilder.build(sdk_key, options)

Logging

Our Ruby SDK makes use of Ruby’s stdlib Logger class to log errors/events. The default option is shown below:

Logger.new($stdout)

You can configure the following options in the config file.

{
  ## ...
  ## you can specify your own Logger class instance here:
  logger: Logger.new('logfile.log'),
  ## to enable more verbose logging, including more debug information (false is the default) use:
  debug_enabled: true,
  ## to log transport data (mostly http requests, false is the default) use:
  transport_debug_enabled: true
  ## ...
}

Proxy

Ruby SDK respects the HTTP_PROXY environment variable. To use a proxy, assign a proxy address to that variable.

http_proxy=http://username:password@hostname:port

Configure fallback treatments

Fallback treatments let you define a treatment value (and optional configuration) to be returned when a flag cannot be evaluated. By default, the SDK returns control, but you can override this globally or for individual flags at the SDK level.

This is useful when you want to:

Maintain a predictable user experience during outages or evaluation failures (avoid unexpected control in production)
Protect critical user flows by returning a safe, stable treatment (for example, forcing off during an incident)
Customize behavior per flag so each evaluation inherits appropriate safe defaults if something goes wrong

Global fallback treatment

Set a global fallback treatment when initializing the SDK factory. This value is returned whenever any flag cannot be evaluated.

// Initialize SDK with global fallback treatment
fallback_config = SplitIoClient::Engine::Models::FallbackTreatmentsConfiguration.new(SplitIoClient::Engine::Models::FallbackTreatment.new("control_fallback_ruby", '{"my_feature": "control"}'))

options = {block_until_ready: 5,
  fallback_treatments: fallback_config
}
split_factory = SplitIoClient::SplitFactoryBuilder.build("SDK API KEY", options)

Flag-level fallback treatment

You can set a fallback treatment per flag in the SDK options. When a flag evaluation fails, the SDK returns the corresponding fallback treatment defined for that flag. This flag-level fallback always takes precedence over the global fallback treatment, so if both are defined, the SDK will return the flag-level value when that flag cannot be evaluated.

fallback_config = SplitIoClient::Engine::Models::FallbackTreatmentsConfiguration.new(nil, {:flag_1 => SplitIoClient::Engine::Models::FallbackTreatment.new(
	"flag_1_FALLBACK", 
	'{"my_feature": "collection control"}')
})

options = {block_until_ready: 5,
  fallback_treatments: fallback_config
}
split_factory = SplitIoClient::SplitFactoryBuilder.build("SDK API KEY", options)
split_client = split_factory.client

treatment = split_client.get_treatment_with_config("ruby", "flag_1")

For more information, see Fallback treatments.

Advanced use cases

This section describes advanced use cases and features provided by the SDK.

SUPPORTED SDK VERSIONS

SDK events and event metadata are supported in the Ruby SDK version 8.11.0 or later.

You can listen for four different events from the SDK.

SDK_READY. This event fires once the SDK is ready to evaluate treatments using the most up-to-date version of your rollout plan, downloaded from Harness servers.
SDK_UPDATE. This event fires whenever your rollout plan is changed. Listen for this event to refresh your app whenever a feature flag or segment is changed in Harness FME.

These events provide hooks to run custom logic whenever the SDK state changes.

require 'splitclient-rb'

def ready_callback(metadata)
    puts "SDK is ready."
end

def update_callback(metadata)
    puts "UPDATE CALLBACK"
    puts metadata.type
    puts metadata.names
end

split_factory = SplitIoClient::SplitFactoryBuilder.build('API KEY', {block_until_ready: 100})

split_client = split_factory.client
split_client.register(SplitIoClient::Engine::Models::SdkEvent::SDK_READY, method(:ready_callback))
split_client.register(SplitIoClient::Engine::Models::SdkEvent::SDK_UPDATE, method(:update_callback))

Include metadata

metadata provides additional context for events:

SDK_READY: No metadata is included.
SDK_UPDATE: Includes the type (SdkEventType.FLAG_UPDATE or SdkEventType.SEGMENTS_UPDATE) and names (list of impacted flags; empty for segment-only updates).

Troubleshooting

SSL Certificate Error: OpenSSL::SSL::SSLError on macOS

I am seeing the following certificate error: OpenSSL::SSL::SSLError. On OSX, if you see an SSL issue that looks similar to the example below, refer to this post for troubleshooting.

OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

Error: uninitialized constant caused by Process::RLIMIT_NOFILE in lib/net/http/persistent.rb

When using Ruby SDK on Windows, initializing the SDK factory object causes the following error:

uninitialized constant error caused by 'Process::RLIMIT_NOFILE' in lib/net/http/persistent.rb

This issue is related to the net-http-persistent 3.0 library on Windows OS. This library is a dependency installed automatically with the SDK gem.

Downgrade net-http-persistent to version 2.9.4, which is compatible with the Ruby SDK on Windows, by running:

gem uninstall net-http-persistent
gem install net-http-persistent -v '2.9.4'

Upgrading Ruby SDK from 4.x to 5.x and Above

The Ruby SDK uses a hashing algorithm to divide users across treatments for feature flags (e.g., a 50/50 split between "on" and "off"). Historically, Split has used two hashing algorithms:

Legacy Hash (Algorithm 1): A simple and fast implementation, but it produces uneven user distributions when user counts are below 100.
Murmur Hash (Algorithm 2): An industry-standard hashing algorithm that is both fast and provides even distributions regardless of user count.

In Ruby SDK versions 4.x and below, feature flags intended to use the Murmur Hash were incorrectly using the Legacy Hash. This caused inconsistent treatment assignments when compared with other language SDKs.

Starting from Ruby SDK version 5.0.0 and above, this issue is fixed and the SDK correctly uses the Murmur Hash.

When upgrading, if feature flags are in a ramping phase (i.e., partially rolled out), users may experience treatment shifts due to the change in hashing algorithm.

Ideally, upgrade the Ruby SDK when all experiments are at 100% distribution to avoid user treatment shifts.
If this is not possible, consider creating new versions of the active feature flags. This resets metric calculations and can lead to users receiving different treatments, but users won’t be excluded from metrics as no treatment changes are recorded within the same flag version.

Why do CLOSE_WAIT TCP connections in Puma not go down as expected?

When using the Ruby SDK with Puma or Unicorn in cluster mode (multiple workers, single thread each), you may notice an increasing number of CLOSE_WAIT TCP connections when the SDK sends treatment events. Running the following command will confirm this:

lsof -l | grep CLOSE_WAIT | wc -l

If no SDK treatment calls are made, the number of CLOSE_WAIT connections does not decrease as expected.

The SDK threads may not be terminating properly, leaving client connections hanging and waiting for the server’s final ACK signal.

Puma spawns a new process for each group of incoming requests. To ensure all SDK threads are terminated before Puma closes the process, add the following to your config/puma.rb file:

before_fork do
  $split_factory.instance_variable_get(:@config).threads.each { |_, t| t.exit }
end

This cleanly shuts down SDK threads, helping close the TCP connections properly.

PreviousPython SDK

NextCustomer-deployed Components

Last updated 17 hours ago

Was this helpful?

Initialization

1. Import the SDK into your project

2. Instantiate the SDK and create a new SDK factory client

Configure the SDK for use with Rails

SDK Server Compatibility

Use the SDK

Basic use

Attribute syntax

Multiple evaluations at once

Get treatments with configurations

Append properties to impressions

Shutdown

Track

Configuration

Sharing state: Redis integration

Configure Redis using Sentinel

Localhost mode

Manager

Listener

Logging

Proxy

Configure fallback treatments

Global fallback treatment

Flag-level fallback treatment

Advanced use cases

Subscribe to events

Troubleshooting

SSL Certificate Error: OpenSSL::SSL::SSLError on macOS

Error: uninitialized constant caused by Process::RLIMIT_NOFILE in lib/net/http/persistent.rb

Upgrading Ruby SDK from 4.x to 5.x and Above

Why do CLOSE_WAIT TCP connections in Puma not go down as expected?