Ruby SDK reference

This topic documents how to get started with the server-side Ruby SDK, and links to reference information on all of the supported features.

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.

LaunchDarkly’s SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:

Resource	Location
SDK API documentation	SDK API docs
Supported SDK Versions	Ruby server SDK
GitHub repository	ruby-server-sdk
Sample applications	Ruby , Rails with bootstrapping
Published module	RubyGems

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:

Shell

    gem install launchdarkly-server-sdk

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:

Ruby

    require 'ldclient-rb'

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.

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:

Ruby

    client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")

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:

1. You should initialize a new client before the forking process.
2. 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:

Ruby SDK v8.11+

    # 1. Create the client before forking.
    client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")

    # 2. From the newly forked process, reinitialize the client by calling `postfork`.
    # Examples for specific servers are shown below.
    client.postfork

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.

Ruby

      Rails.configuration.client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")

Expand Using Puma

Using Puma

If you use the Puma web server, we recommend reinitializing the client in on_worker_boot:

Ruby Puma initialization with Rails

      on_worker_boot do
        Rails.configuration.client.postfork
      end

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:

Ruby Spring initialization with Rails

      Spring.after_fork do
        Rails.configuration.client.postfork
      end

Expand Using Unicorn

Using Unicorn

If you use Unicorn, specify an after_fork hook in your unicorn.rb config file:

Ruby Unicorn initialization with Rails

      after_fork do |server,worker|
        Rails.configuration.client.postfork
      end

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:

Ruby Passenger initialization with Rails

      if defined?(PhusionPassenger)
        PhusionPassenger.on_event(:starting_worker_process) do |forked|
          Rails.configuration.client.postfork
        end
      end

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:

Ruby SDK v7.0+

    context = LaunchDarkly::LDContext.with_key("example-context-key")
    show_feature = client.variation("example-flag-key", context, false)
    if show_feature
      # application code to show the feature
    else
      # the code to run if the feature is off
    end

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
  • Application metadata configuration
  • Migration configuration
  • Service endpoint configuration
• Context configuration
• Data saving mode
• 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
  • Using proxy mode
  • Using daemon mode
• Secure mode
• Sending custom events
• Shutting down
• Storing data
• Subscribing to flag changes
• Test data sources
• Web proxy configuration