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.

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:

$
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:

1
require 'ldclient-rb'

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.

Here’s how:

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

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:

1
# 1. Create the client before forking.
2
client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")
3
4
# 2. From the newly forked process, reinitialize the client by calling `postfork`.
5
# Examples for specific servers are shown below.
6
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.

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

1
on_worker_boot do
2
  Rails.configuration.client.postfork
3
end

1
Spring.after_fork do
2
  Rails.configuration.client.postfork
3
end

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

1
if defined?(PhusionPassenger)
2
  PhusionPassenger.on_event(:starting_worker_process) do |forked|
3
    Rails.configuration.client.postfork
4
  end
5
end

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:

1
context = LaunchDarkly::LDContext.with_key("example-context-key")
2
show_feature = client.variation("example-flag-key", context, false)
3
if show_feature
4
  # application code to show the feature
5
else
6
  # the code to run if the feature is off
7
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