---
title: "OpenFeature Ruby Provider"
description: "ConfigDirector Provider for the OpenFeature Ruby SDK"
canonical_url: "https://docs.configdirector.com/sdks/openfeature/ruby"
---
# OpenFeature Ruby Provider

> ConfigDirector Provider for the OpenFeature Ruby SDK

<div hidden="true" dataTitleIcon="openfeature-ruby">



</div>

<external-badges package-url="https://rubygems.org/gems/configdirector-openfeature-server-provider" registry="rubygems" repo="ruby-sdks/tree/main/configdirector-openfeature-server-provider">



</external-badges>

## Introduction

The OpenFeature Ruby Provider is intended to be used in combination with the [OpenFeature Ruby SDK](https://openfeature.dev/docs/reference/sdks/server/ruby/). The provider wraps the ConfigDirector [Ruby SDK](https://docs.configdirector.com/sdks/server/ruby).

The provider is thread safe. Register one per process the first time the process reads a flag, and shut OpenFeature down when the process exits. Evaluations read config state the provider already holds in memory, so they make no network calls on the request path.

## Installation

The provider can be installed with Bundler. Its gem page is on RubyGems: [https://rubygems.org/gems/configdirector-openfeature-server-provider](https://rubygems.org/gems/configdirector-openfeature-server-provider)

The minimum Ruby version supported is `3.4`, because the OpenFeature Ruby SDK requires it.

The OpenFeature Ruby SDK (`openfeature-sdk`) and the ConfigDirector Ruby SDK are included as dependencies.

<code-group>

```bash [bundler]
bundle add configdirector-openfeature-server-provider
```

</code-group>

## Configure and initialize the client

1. Create an instance of the provider using your server SDK key. You can retrieve a server SDK key for each environment under `SDK keys` in the dashboard's navigation panel. Creating the provider makes no network call.
2. Set the OpenFeature provider and wait for it to connect.
3. Get a client instance from OpenFeature.

The example registers the provider the first time a process reads a flag, and returns the same OpenFeature client to every later read in the process:

```ruby [lib/open_feature_client_per_process.rb]
require "configdirector/openfeature"

# Registers the provider the first time a process reads a flag, and returns the same client afterwards.
module OpenFeatureClientPerProcess
  @lock = Mutex.new
  @client = nil

  def self.client
    @lock.synchronize { @client ||= client_after_registering_the_provider }
  end

  def self.client_after_registering_the_provider
    # IMPORTANT: Do not commit the server SDK key to your source code, it is a secret value.
    provider = ConfigDirector::OpenFeature::ConfigDirectorProvider.new(ENV.fetch("CONFIGDIRECTOR_SERVER_KEY"))
    begin
      OpenFeature::SDK.set_provider_and_wait(provider)
    rescue OpenFeature::SDK::ProviderInitializationError => e
      warn("Starting on in-code default values until ConfigDirector sends config: #{e.message}")
    end
    at_exit { OpenFeature::SDK.shutdown }
    OpenFeature::SDK.build_client
  end

  private_class_method :client_after_registering_the_provider
end
```

<warning>

Server SDK keys are secret values. Do not commit them to your source code repository. Provide them at runtime via environment variables instead.

</warning>

Each Ruby process holds its own provider and its own connection to ConfigDirector. Registering the provider on first use, rather than while the application boots, keeps the processes that never read a flag from connecting, such as the master process of Puma in cluster mode, a console session or an image build that has no server SDK key. A provider registered before the process forked keeps working in the forked process, with nothing to call. The Ruby SDK's page explains both in [Servers that fork their workers](https://docs.configdirector.com/sdks/server/ruby#servers-that-fork-their-workers).

### When no config arrives in time

`set_provider_and_wait` raises `OpenFeature::SDK::ProviderInitializationError` with the `PROVIDER_NOT_READY` error code when no config arrives from ConfigDirector within the connection timeout, which is 3 seconds unless you set the connection's [`timeout`](https://docs.configdirector.com/sdks/server/ruby#connection), or when ConfigDirector rejects the server SDK key. The provider then reports the `ERROR` status, with a `PROVIDER_ERROR` event, and after a timeout it keeps connecting in the background. Until config arrives, flags resolve to their in-code default values with the `PROVIDER_NOT_READY` error code. Once it arrives, the provider reports `READY`, with one `PROVIDER_READY` event.

The example above rescues the error, prints it and starts on in-code default values. To start without waiting for ConfigDirector at all, set the provider with `set_provider` instead, which initializes it in the background:

```ruby [lib/open_feature_client_per_process.rb]
OpenFeature::SDK.set_provider(ConfigDirector::OpenFeature::ConfigDirectorProvider.new(ENV.fetch("CONFIGDIRECTOR_SERVER_KEY")))
```

A provider whose connection drops later stays `READY` and serves the values it has, so the provider never reports the `STALE` or `FATAL` status.

### Additional configuration options

Additional configuration options can be passed into the provider as keyword arguments of `ConfigDirectorProvider.new`.

For example, the `metadata` can be provided like this:

```ruby [lib/open_feature_client_per_process.rb]
provider = ConfigDirector::OpenFeature::ConfigDirectorProvider.new(
  ENV.fetch("CONFIGDIRECTOR_SERVER_KEY"),
  metadata: ConfigDirector::Metadata.new(app_name: "YOUR-APP-NAME", app_version: "1.0.2")
)
```

The provider accepts the same `metadata`, `connection`, `logger`, `log_level` and `telemetry` options as the Ruby SDK client, [refer to the additional configuration options section of the Ruby SDK for a full list](https://docs.configdirector.com/sdks/server/ruby#additional-configuration-options). It does not take the client's `hooks` option: listen to the OpenFeature [events](#events) instead.

That includes [running without a connection](https://docs.configdirector.com/sdks/server/ruby#run-without-a-connection): created with `connection: ConfigDirector::ConnectionOptions.new(mode: "offline", ...)` and no server SDK key, the provider serves the values you give it without connecting to ConfigDirector, and `set_provider_and_wait` raises `OpenFeature::SDK::ProviderInitializationError` with the `GENERAL` error code if those values cannot be loaded.

### Shut down

Shutting OpenFeature down closes the provider, which closes its connection and reports any pending telemetry. The example above does it when the process exits:

```ruby [lib/open_feature_client_per_process.rb]
at_exit { OpenFeature::SDK.shutdown }
```

## Retrieve config values

To retrieve config values, use the OpenFeature client:

Every getter takes the flag key and the in-code default value and, optionally, the evaluation context, as keyword arguments:

```ruby [main.rb]
client = OpenFeatureClientPerProcess.client

boolean_value = client.fetch_boolean_value(flag_key: "my-config-key", default_value: false)

string_value = client.fetch_string_value(flag_key: "my-string-config-key", default_value: "Default")
```

Each OpenFeature getter maps to a ConfigDirector config type:

<table>
<thead>
  <tr>
    <th>
      OpenFeature getter
    </th>
    
    <th>
      ConfigDirector config value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        fetch_boolean_value
      </code>
    </td>
    
    <td>
      Boolean
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch_string_value
      </code>
    </td>
    
    <td>
      String or enum
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch_number_value
      </code>
      
      , <code>
        fetch_integer_value
      </code>
      
      , <code>
        fetch_float_value
      </code>
    </td>
    
    <td>
      Number
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch_object_value
      </code>
    </td>
    
    <td>
      JSON object or JSON array
    </td>
  </tr>
</tbody>
</table>

`fetch_number_value` reads any finite number, whatever the class of the in-code default value: a whole number comes back as an Integer and any other number as a Float. `fetch_integer_value` reads whole numbers only, and `fetch_float_value` returns a Float.

`fetch_object_value` returns the parsed JSON: with a Hash as the in-code default value it reads a JSON object, as a Hash with String keys, and with an Array it reads a JSON array. A JSON array read with a Hash, or a JSON object read with an Array, returns the in-code default value with `TYPE_MISMATCH`:

```ruby [main.rb]
settings = client.fetch_object_value(flag_key: "my-json-config-key", default_value: {})
theme = settings["theme"]
```

For additional information regarding the OpenFeature client [refer to the OpenFeature Ruby SDK documentation](https://openfeature.dev/docs/reference/sdks/server/ruby/).

### Evaluation details

The detailed getters of the OpenFeature client, such as `fetch_boolean_details`, report why an evaluation produced the value that it did:

<table>
<thead>
  <tr>
    <th>
      Outcome
    </th>
    
    <th>
      Reason
    </th>
    
    <th>
      Error code
    </th>
    
    <th>
      Variant
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A value was found
    </td>
    
    <td>
      <code>
        TARGETING_MATCH
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The variation name, or the value ID
    </td>
  </tr>
  
  <tr>
    <td>
      A percentage rollout was skipped for a context without a targeting key
    </td>
    
    <td>
      <code>
        DEFAULT
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The variation name, or the value ID
    </td>
  </tr>
  
  <tr>
    <td>
      The config carries no value
    </td>
    
    <td>
      <code>
        DEFAULT
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      The config key is unknown
    </td>
    
    <td>
      <code>
        ERROR
      </code>
    </td>
    
    <td>
      <code>
        FLAG_NOT_FOUND
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      No config state has arrived yet
    </td>
    
    <td>
      <code>
        ERROR
      </code>
    </td>
    
    <td>
      <code>
        PROVIDER_NOT_READY
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      The value does not match the requested type
    </td>
    
    <td>
      <code>
        ERROR
      </code>
    </td>
    
    <td>
      <code>
        TYPE_MISMATCH
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

The `variant` is the name of the variation served, such as `treatment`, when the config has variations and that variation has a name. Otherwise it is ConfigDirector's ID for the value served, a stable hash you can send to analytics in place of the value itself; values served in offline mode have none. In the cases without a variant, the in-code default value is returned. The details carry no flag metadata.

```ruby [main.rb]
details = client.fetch_boolean_details(flag_key: "new-checkout", default_value: false, evaluation_context: user)
warn("new-checkout fell back to its in-code default value: #{details.error_code}") if details.error_code
```

To report an experiment to an analytics tool, follow the page for [Amplitude](https://docs.configdirector.com/integrations/analytics/amplitude), [Mixpanel](https://docs.configdirector.com/integrations/analytics/mixpanel), [Google Analytics 4](https://docs.configdirector.com/integrations/analytics/ga4), [Segment](https://docs.configdirector.com/integrations/analytics/segment) or [PostHog](https://docs.configdirector.com/integrations/analytics/posthog), which names the event that tool reads.

## Context

The context is the `evaluation_context` argument of every getter of the OpenFeature client. The OpenFeature Ruby provider evaluates targeting rules locally without additional network calls for different contexts.

```ruby [main.rb]
user = OpenFeature::SDK::EvaluationContext.new(
  targeting_key: "12345", # In OpenFeature, the targeting key represents the context's identifier
  name: "Example User",
  traits: { "region" => "North America" } # Any arbitrary traits which can be referenced in targeting rules
)

boolean_value = client.fetch_boolean_value(flag_key: "my-config-key", default_value: false, evaluation_context: user)
```

To evaluate flags for an entity other than a user, such as a tenant, set the context kind with a top-level `kind` attribute:

```ruby [main.rb]
tenant = OpenFeature::SDK::EvaluationContext.new(
  targeting_key: "acme",
  kind: "tenant",
  name: "Acme Inc.",
  traits: { "plan" => "enterprise" }
)

boolean_value = client.fetch_boolean_value(flag_key: "my-config-key", default_value: false, evaluation_context: tenant)
```

Leaving `kind` out means `user`. A `kind` inside `traits` is an ordinary trait, not the context kind. A context kind is 1 to 64 lowercase letters, digits, dashes, or underscores. A context with an invalid context kind is ignored: the SDK logs an error, and flags still resolve successfully, as if no context had been given.

The evaluation context maps onto the ConfigDirector context as follows:

<table>
<thead>
  <tr>
    <th>
      OpenFeature evaluation context
    </th>
    
    <th>
      ConfigDirector context
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      The targeting key, or otherwise an <code>
        id
      </code>
      
       attribute
    </td>
    
    <td>
      <code>
        id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      The top-level <code>
        kind
      </code>
      
       attribute
    </td>
    
    <td>
      <code>
        kind
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      The <code>
        name
      </code>
      
       attribute
    </td>
    
    <td>
      <code>
        name
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      The <code>
        traits
      </code>
      
       attribute, a Hash
    </td>
    
    <td>
      <code>
        traits
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      The <code>
        anonymous
      </code>
      
       attribute, when it is <code>
        true
      </code>
    </td>
    
    <td>
      <code>
        anonymous
      </code>
    </td>
  </tr>
</tbody>
</table>

An id or a name given as a Symbol, `true` or `false`, an Integer, a Float or a date is read as text, and any other id or name is left out. A date, given as a `Time`, a `DateTime` or a `Date`, is written as UTC text such as `2026-11-17T10:00:00.000Z`, or as `2026-11-17` for a `Date`, inside the traits too, so date conditions can compare it.

An evaluation context with neither a targeting key nor an `id` attribute skips percentage rollouts: a rollout does not apply to it, and the targeting rules after the rollout are tried, as they are after a conditional rule the context does not match. When none of them applies, the flag resolves to the default targeting rule value with the reason `DEFAULT`; a later rule that applies resolves with `TARGETING_MATCH`. A rule that serves a single value still applies to it. To keep an anonymous visitor in a rollout, give the context a stable targeting key, such as a session ID.

For additional information regarding the OpenFeature client [refer to the OpenFeature Ruby SDK documentation](https://openfeature.dev/docs/reference/sdks/server/ruby/).

## Events

The provider emits `PROVIDER_CONFIGURATION_CHANGED` whenever configs are updated on the dashboard or via the admin API, carrying the keys of the configs in the update followed by the keys of the configs it removed:

```ruby [main.rb]
OpenFeature::SDK.add_handler(
  OpenFeature::SDK::ProviderEvent::PROVIDER_CONFIGURATION_CHANGED,
  ->(event_details) { puts "Configs updated: #{event_details[:flags_changed].join(", ")}" }
)
```

When no config arrived in time at startup, the provider emits `PROVIDER_READY` once config arrives, as described in [When no config arrives in time](#when-no-config-arrives-in-time).

## Track events

The provider implements OpenFeature's tracking API. `client.track` reports to ConfigDirector that something happened in your application, such as a completed checkout, and ConfigDirector shows it on the Live feed and counts it for each variation of a running experiment; see [Tracked events](https://docs.configdirector.com/monitoring/activity#tracked-events).

```ruby [main.rb]
client.track(
  "checkout-completed",
  evaluation_context: OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-123"),
  tracking_event_details: OpenFeature::SDK::TrackingEventDetails.new(value: 49.9, plan: "pro", seats: 3)
)
```

The `value` of the tracking event details is sent as the event's value, and their other fields as the event's details. The context the event happened for is the merged evaluation context: its targeting key, or otherwise its `id` attribute, and its `kind`.

An event counts for an experiment only when its evaluation context has the targeting key the experiment's flag was evaluated with, so track with the context you evaluate with. Without one, the event is still reported and counts for no experiment. For a context marked `anonymous`, the event is reported without the targeting key, so it counts for no experiment either.

`track` never raises: an event the provider cannot pass on, for example because its evaluation context cannot be read, is logged as a warning and not reported. It does nothing in offline mode. The provider sends tracked events as the [Ruby SDK](https://docs.configdirector.com/sdks/server/ruby#track-events) does, with the same limits.

## Test your code

Code that reads flags through OpenFeature is tested by swapping the provider, so it never has to change for a test and nothing from ConfigDirector is involved. The OpenFeature Ruby SDK ships an in-memory provider for that, `OpenFeature::SDK::Provider::InMemoryProvider`, which serves the values your test sets:

```ruby [spec/checkout_spec.rb]
RSpec.describe "the checkout" do
  after { OpenFeature::SDK.shutdown }

  it "shows the new checkout" do
    provider = OpenFeature::SDK::Provider::InMemoryProvider.new("new-checkout" => true, "max-items" => 20)
    OpenFeature::SDK.set_provider_and_wait(provider)
    client = OpenFeature::SDK.build_client

    expect(client.fetch_boolean_value(flag_key: "new-checkout", default_value: false)).to be(true)
    expect(client.fetch_integer_value(flag_key: "max-items", default_value: 0)).to eq(20)

    provider.add_flag(flag_key: "new-checkout", value: false)
    expect(client.fetch_boolean_value(flag_key: "new-checkout", default_value: true)).to be(false)
  end
end
```

`add_flag` changes a value in the middle of a test and emits `PROVIDER_CONFIGURATION_CHANGED` with the flag's key. The OpenFeature API is one global, so shut it down after each test with `OpenFeature::SDK.shutdown`, as the `after` block above does, which lets the next test register its own provider.

When the provider is registered the first time a process reads a flag, as in [Configure and initialize the client](#configure-and-initialize-the-client), make `ConfigDirectorProvider.new` return the in-memory provider, so your application's own registration runs as it does in production, and forget the module's client after each example:

```ruby [spec/support/in_memory_provider_in_place_of_the_configdirector_provider.rb]
RSpec.shared_context "with an in-memory provider in place of the ConfigDirector provider" do
  let(:in_memory_provider) { OpenFeature::SDK::Provider::InMemoryProvider.new("new-checkout" => true) }

  before { allow(ConfigDirector::OpenFeature::ConfigDirectorProvider).to receive(:new).and_return(in_memory_provider) }

  after do
    OpenFeature::SDK.shutdown
    OpenFeatureClientPerProcess.instance_variable_set(:@client, nil)
  end
end
```


## Sitemap

See the full [sitemap](https://docs.configdirector.com/sitemap.md) for all pages.
