Ruby SDK reference
Overview
This topic documents how to get started with the server-side Ruby SDK, and links to reference information on all of the supported features.
SDK quick links
LaunchDarkly’s SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:
SDK version compatibility
The LaunchDarkly Ruby SDK, version 8.0 and higher, is compatible with Ruby 3.0.
The LaunchDarkly Ruby SDK, version 7.x, is compatible with Ruby 2.7 and higher.
Prior to version 7.0, the LaunchDarkly Ruby SDK also supported Ruby 2.5 and 2.6.
Get started
After you complete the Get started process, follow these instructions to start using the LaunchDarkly SDK in your Ruby application.
Install the SDK
First, install the LaunchDarkly SDK as a dependency in your application using your application’s dependency manager. Refer to the SDK releases page to identify the latest version if you want to depend on a specific version.
If you are using Bundler, you can add gem "launchdarkly-server-sdk"
to your Gemfile and run bundle install
. Otherwise, you can install the gem directly:
Next, import the LaunchDarkly client in your application code. This step may not be necessary if you are using a framework that automatically loads all dependencies, as Rails does.
Here’s how:
The Ruby SDK uses an SDK key
The Ruby SDK uses an SDK key. Keys are specific to each project and environment. They are available from Project settings, on the Environments list. To learn more about key types, read Keys.
Initialize the client
After you install and import the SDK, create a single, shared instance of LDClient
. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.
LDClient must be a singleton
It’s important to make LDClient
a singleton for each LaunchDarkly project. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.
If you have multiple LaunchDarkly projects, you can create one LDClient
for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.
Here’s how:
Worker-based servers require specific setup
The Ruby SDK uses multiple background threads to operate correctly. If the SDK is deployed to an environment which forks from the main process, the SDK may not operate as expected. To learn more about this problem and how to fix it, refer to Considerations with worker-based servers, below.
Considerations with worker-based servers
The LaunchDarkly SDK relies on multiple threads to operate correctly. These threads provide essential functionality, including delivering flag updates and sending event data.
If the main process which instantiated the SDK is itself forked, the SDK will still evaluate flags, but it will be unable to receive changes to those flags in that child process. This is because threads do not survive the forking process in Ruby.
The good news is the LaunchDarkly SDK is compatible with process-forking servers. However, there are a few considerations:
- You should initialize a new client before the forking process.
- After you have forked the worker process, you can call
postfork
to reinitialize the client. This way, your client will accurately reflect flag changes in the forked thread.
Here’s how:
Any configuration that you provide to the SDK must survive the forking process independently. We recommend that you add any listeners or hooks after the postfork
call, unless you are certain they can survive the forking process.
If you are using the Relay Proxy, you must use Relay Proxy v8.11 or later to use postfork
.
To learn more about the specific configuration options available in this SDK, read Config
. To learn more about the postfork
reinitialization, read postfork
.
Expand Using a Rails application
Using a Rails application
To use LaunchDarkly in a Rails application, initialize the client in config/initializers/launchdarkly.rb
as shown below. This provides access to the LDClient
globally in the Rails application and through the Rails console.
If the web server running Rails does not fork workers from this process, no further configuration is required. In all other cases, once the worker process has forked, the postfork
method of the LDClient
should be called. To learn more about your specific server, refer to the example server integrations below.
Expand Using Puma
Expand Using Spring
Using Spring
To use LaunchDarkly with the Rails application preloader Spring, we recommend using an after_fork
callback in the config/spring.rb
file to reinitialize the client:
Expand Using Unicorn
Expand Using Passenger
Using Passenger
If you use the Passenger web server, we recommend reinitializing the client in config.ru
, or from any code called while loading config.ru
:
Expand Using httplog
Using httplog
If you are using the Rails httplog
library, you should include launchdarkly.com
in the url_blacklist_pattern
attribute of httplog
’s configuration.
By default, the Rails httplog
library buffers the entire response to a request. However, in the LaunchDarkly SDKs, the streaming request remains open. Therefore, the httplog
library intercepts the request but never returns the response from LaunchDarkly indicating that initialization is complete. This means the Ruby SDK may not complete initialization and also may not log an error. If your application makes flag evaluations before the SDK initialization is complete, you may receive the message: [LDClient] Client has not finished initializing; feature store unavailable, returning default value
.
When you include launchdarkly.com
in the url_blacklist_pattern
attribute of httplog
’s configuration, then httplog
will not intercept the response, and SDK initialization will complete. This lets you use flags as expected.
To learn more, read the httplog
Configuration documentation.
Evaluate a context
You can use client
to check which variation a particular context will receive for a given feature flag. To learn more, read Evaluating flags and Flag evaluation reasons. For more information about how contexts are specified, read Context configuration.
Here’s how:
Shut down the client
Shut down the client when your application terminates. This frees the resources the worker threads were using and provides an explicit signal for the Ruby SDK to send the remaining event data back to LaunchDarkly. To learn more, read Shutting down.
Supported features
This SDK supports the following features:
- Anonymous contexts and users
- Big segments
- Configuration, including
- Context configuration
- Evaluating flags
- Flag evaluation reasons
- Flushing events
- Getting all flags
- Hooks
- Identifying and changing contexts
- Logging configuration
- Migrations
- Monitoring SDK status
- Offline mode
- OpenTelemetry
- Private attributes
- Reading flags from a file
- Relay Proxy configuration
- Secure mode
- Sending custom events
- Shutting down
- Storing data
- Subscribing to flag changes
- Test data sources
- Web proxy configuration