Class: LaunchDarkly::LDClient

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Impl
Defined in:
lib/ldclient-rb/ldclient.rb

Overview

A client for LaunchDarkly. Client instances are thread-safe. Users should create a single client instance for the lifetime of the application.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(sdk_key, config = Config.default, wait_for_sec = 5) ⇒ LDClient

Creates a new client instance that connects to LaunchDarkly. A custom configuration parameter can also supplied to specify advanced options, but for most use cases, the default configuration is appropriate.

The client will immediately attempt to connect to LaunchDarkly and retrieve your feature flag data. If it cannot successfully do so within the time limit specified by ‘wait_for_sec`, the constructor will return a client that is in an uninitialized state. See #initialized? for more details.

Parameters:

  • sdk_key (String) —

    the SDK key for your LaunchDarkly account

  • config (Config) (defaults to: Config.default) —

    an optional client configuration object

  • wait_for_sec (Float) (defaults to: 5) —

    maximum time (in seconds) to wait for initialization



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/ldclient-rb/ldclient.rb', line 45

def initialize(sdk_key, config = Config.default, wait_for_sec = 5)
  # Note that sdk_key is normally a required parameter, and a nil value would cause the SDK to
  # fail in most configurations. However, there are some configurations where it would be OK
  # (offline = true, *or* we are using LDD mode or the file data source and events are disabled
  # so we're not connecting to any LD services) so rather than try to check for all of those
  # up front, we will let the constructors for the data source implementations implement this
  # fail-fast as appropriate, and just check here for the part regarding events.
  if !config.offline? && config.send_events
    raise ArgumentError, "sdk_key must not be nil" if sdk_key.nil?
  end

  @sdk_key = sdk_key

  @shared_executor = Concurrent::SingleThreadExecutor.new

  data_store_broadcaster = LaunchDarkly::Impl::Broadcaster.new(@shared_executor, config.logger)
  store_sink = LaunchDarkly::Impl::DataStore::UpdateSink.new(data_store_broadcaster)

  # We need to wrap the feature store object with a FeatureStoreClientWrapper in order to add
  # some necessary logic around updates. Unfortunately, we have code elsewhere that accesses
  # the feature store through the Config object, so we need to make a new Config that uses
  # the wrapped store.
  @store = Impl::FeatureStoreClientWrapper.new(config.feature_store, store_sink, config.logger)
  updated_config = config.clone
  updated_config.instance_variable_set(:@feature_store, @store)
  @config = updated_config

  @data_store_status_provider = LaunchDarkly::Impl::DataStore::StatusProvider.new(@store, store_sink)

  @big_segment_store_manager = Impl::BigSegmentStoreManager.new(config.big_segments, @config.logger)
  @big_segment_store_status_provider = @big_segment_store_manager.status_provider

  get_flag = lambda { |key| @store.get(FEATURES, key) }
  get_segment = lambda { |key| @store.get(SEGMENTS, key) }
  get_big_segments_membership = lambda { |key| @big_segment_store_manager.get_context_membership(key) }
  @evaluator = LaunchDarkly::Impl::Evaluator.new(get_flag, get_segment, get_big_segments_membership, @config.logger)

  if !@config.offline? && @config.send_events && !@config.diagnostic_opt_out?
    diagnostic_accumulator = Impl::DiagnosticAccumulator.new(Impl::DiagnosticAccumulator.create_diagnostic_id(sdk_key))
  else
    diagnostic_accumulator = nil
  end

  if @config.offline? || !@config.send_events
    @event_processor = NullEventProcessor.new
  else
    @event_processor = EventProcessor.new(sdk_key, config, nil, diagnostic_accumulator)
  end

  if @config.use_ldd?
    @config.logger.info { "[LDClient] Started LaunchDarkly Client in LDD mode" }
    return  # requestor and update processor are not used in this mode
  end

  flag_tracker_broadcaster = LaunchDarkly::Impl::Broadcaster.new(@shared_executor, @config.logger)
  @flag_tracker = LaunchDarkly::Impl::FlagTracker.new(flag_tracker_broadcaster, lambda { |key, context| variation(key, context, nil) })

  data_source_broadcaster = LaunchDarkly::Impl::Broadcaster.new(@shared_executor, @config.logger)

  # Make the update sink available on the config so that our data source factory can access the sink with a shared executor.
  @config.data_source_update_sink = LaunchDarkly::Impl::DataSource::UpdateSink.new(@store, data_source_broadcaster, flag_tracker_broadcaster)

  @data_source_status_provider = LaunchDarkly::Impl::DataSource::StatusProvider.new(data_source_broadcaster, @config.data_source_update_sink)

  data_source_or_factory = @config.data_source || self.method(:create_default_data_source)
  if data_source_or_factory.respond_to? :call
    # Currently, data source factories take two parameters unless they need to be aware of diagnostic_accumulator, in
    # which case they take three parameters. This will be changed in the future to use a less awkware mechanism.
    if data_source_or_factory.arity == 3
      @data_source = data_source_or_factory.call(sdk_key, @config, diagnostic_accumulator)
    else
      @data_source = data_source_or_factory.call(sdk_key, @config)
    end
  else
    @data_source = data_source_or_factory
  end

  ready = @data_source.start
  if wait_for_sec > 0
    ok = ready.wait(wait_for_sec)
    if !ok
      @config.logger.error { "[LDClient] Timeout encountered waiting for LaunchDarkly client initialization" }
    elsif !@data_source.initialized?
      @config.logger.error { "[LDClient] LaunchDarkly client initialization failed" }
    end
  end
end

Instance Attribute Details

#big_segment_store_status_provider ⇒ Object (readonly)

Returns an interface for tracking the status of a Big Segment store.

The Interfaces::BigSegmentStoreStatusProvider has methods for checking whether the Big Segment store is (as far as the SDK knows) currently operational and tracking changes in this status.



447
448
449
 
# File 'lib/ldclient-rb/ldclient.rb', line 447

def big_segment_store_status_provider
  @big_segment_store_status_provider
end

#data_source_status_provider ⇒ LaunchDarkly::Interfaces::DataSource::StatusProvider (readonly)

Returns an interface for tracking the status of the data source.

The data source is the mechanism that the SDK uses to get feature flag configurations, such as a streaming connection (the default) or poll requests. The Interfaces::DataSource::StatusProvider has methods for checking whether the data source is (as far as the SDK knows) currently operational and tracking changes in this status.

Returns:



474
475
476
 
# File 'lib/ldclient-rb/ldclient.rb', line 474

def data_source_status_provider
  @data_source_status_provider
end

#data_store_status_provider ⇒ LaunchDarkly::Interfaces::DataStore::StatusProvider (readonly)

Returns an interface for tracking the status of a persistent data store.

The Interfaces::DataStore::StatusProvider has methods for checking whether the data store is (as far as the SDK knows) currently operational, tracking changes in this status, and getting cache statistics. These are only relevant for a persistent data store; if you are using an in-memory data store, then this method will return a stub object that provides no information.

Returns:



461
462
463
 
# File 'lib/ldclient-rb/ldclient.rb', line 461

def data_store_status_provider
  @data_store_status_provider
end

#flag_tracker ⇒ Object (readonly)

Returns an interface for tracking changes in feature flag configurations.

The Interfaces::FlagTracker contains methods for requesting notifications about feature flag changes using an event listener model.



483
484
485
 
# File 'lib/ldclient-rb/ldclient.rb', line 483

def flag_tracker
  @flag_tracker
end

Instance Method Details

#all_flags_state(context, options = {}) ⇒ FeatureFlagsState

Returns a FeatureFlagsState object that encapsulates the state of all feature flags for a given context, including the flag values and also metadata that can be used on the front end. This method does not send analytics events back to LaunchDarkly.

Parameters:

  • context (Hash, LDContext) —

    a hash or object describing the context requesting the flags,

  • options (Hash) (defaults to: {}) —

    Optional parameters to control how the state is generated

Options Hash (options):

  • :client_side_only (Boolean) — default: false —

    True if only flags marked for use with the client-side SDK should be included in the state. By default, all flags are included.

  • :with_reasons (Boolean) — default: false —

    True if evaluation reasons should be included in the state (see #variation_detail). By default, they are not included.

  • :details_only_for_tracked_flags (Boolean) — default: false —

    True if any flag metadata that is normally only used for event generation - such as flag versions and evaluation reasons - should be omitted for any flag that does not have event tracking or debugging turned on. This reduces the size of the JSON data if you are passing the flag state to the front end.

Returns:



370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
 
# File 'lib/ldclient-rb/ldclient.rb', line 370

def all_flags_state(context, options={})
  return FeatureFlagsState.new(false) if @config.offline?

  unless initialized?
    if @store.initialized?
        @config.logger.warn { "Called all_flags_state before client initialization; using last known values from data store" }
    else
        @config.logger.warn { "Called all_flags_state before client initialization. Data store not available; returning empty state" }
        return FeatureFlagsState.new(false)
    end
  end

  context = Impl::Context::make_context(context)
  unless context.valid?
    @config.logger.error { "[LDClient] Context was invalid for all_flags_state (#{context.error})" }
    return FeatureFlagsState.new(false)
  end

  begin
    features = @store.all(FEATURES)
  rescue => exn
    Util.log_exception(@config.logger, "Unable to read flags for all_flags_state", exn)
    return FeatureFlagsState.new(false)
  end

  state = FeatureFlagsState.new(true)
  client_only = options[:client_side_only] || false
  with_reasons = options[:with_reasons] || false
  details_only_if_tracked = options[:details_only_for_tracked_flags] || false
  features.each do |k, f|
    if client_only && !f[:clientSide]
      next
    end
    begin
      detail = @evaluator.evaluate(f, context).detail
    rescue => exn
      detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION))
      Util.log_exception(@config.logger, "Error evaluating flag \"#{k}\" in all_flags_state", exn)
    end

    requires_experiment_data = experiment?(f, detail.reason)
    flag_state = {
      key: f[:key],
      value: detail.value,
      variation: detail.variation_index,
      reason: detail.reason,
      version: f[:version],
      trackEvents: f[:trackEvents] || requires_experiment_data,
      trackReason: requires_experiment_data,
      debugEventsUntilDate: f[:debugEventsUntilDate],
    }

    state.add_flag(flag_state, with_reasons, details_only_if_tracked)
  end

  state
end

#close ⇒ void

This method returns an undefined value.

Releases all network connections and other resources held by the client, making it no longer usable.



432
433
434
435
436
437
438
439
 
# File 'lib/ldclient-rb/ldclient.rb', line 432

def close
  @config.logger.info { "[LDClient] Closing LaunchDarkly client..." }
  @data_source.stop
  @event_processor.stop
  @big_segment_store_manager.stop
  @store.stop
  @shared_executor.shutdown
end

#flush ⇒ Object

Tells the client that all pending analytics events should be delivered as soon as possible.

When the LaunchDarkly client generates analytics events (from #variation, #variation_detail, #identify, or #track), they are queued on a worker thread. The event thread normally sends all queued events to LaunchDarkly at regular intervals, controlled by the Config#flush_interval option. Calling ‘flush` triggers a send without waiting for the next interval.

Flushing is asynchronous, so this method will return before it is complete. However, if you call #close, events are guaranteed to be sent before that method returns.



145
146
147
 
# File 'lib/ldclient-rb/ldclient.rb', line 145

def flush
  @event_processor.flush
end

#identify(context) ⇒ void

This method returns an undefined value.

Registers the context. This method simply creates an analytics event containing the context properties, so that LaunchDarkly will know about that context if it does not already.

Calling #variation or #variation_detail also sends the context information to LaunchDarkly (if events are enabled), so you only need to use #identify if you want to identify the context without evaluating a flag.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see #flush.

Parameters:

  • context (Hash, LDContext) —

    a hash or object describing the context to register



281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/ldclient-rb/ldclient.rb', line 281

def identify(context)
  context = LaunchDarkly::Impl::Context.make_context(context)
  unless context.valid?
    @config.logger.warn("Identify called with invalid context: #{context.error}")
    return
  end

  if context.key == ""
    @config.logger.warn("Identify called with empty key")
    return
  end

  @event_processor.record_identify_event(context)
end

#initialized? ⇒ Boolean

Returns whether the client has been initialized and is ready to serve feature flag requests.

If this returns false, it means that the client did not succeed in connecting to LaunchDarkly within the time limit that you specified in the constructor. It could still succeed in connecting at a later time (on another thread), or it could have given up permanently (for instance, if your SDK key is invalid). In the meantime, any call to #variation or #variation_detail will behave as follows:

  1. It will check whether the feature store already contains data (that is, you

are using a database-backed store and it was populated by a previous run of this application). If so, it will use the last known feature flag data.

  1. Failing that, it will return the value that you specified for the ‘default`

parameter of #variation or #variation_detail.

Returns:

  • (Boolean) —

    true if the client has been initialized



184
185
186
 
# File 'lib/ldclient-rb/ldclient.rb', line 184

def initialized?
  @config.offline? || @config.use_ldd? || @data_source.initialized?
end

#migration_variation(key, context, default_stage) ⇒ Array<Symbol, Interfaces::Migrations::OpTracker>

This method returns the migration stage of the migration feature flag for the given evaluation context.

This method returns the default stage if there is an error or the flag does not exist. If the default stage is not a valid stage, then a default stage of ‘off’ will be used instead.

Parameters:

  • key (String)
  • context (LDContext)
  • default_stage (Symbol)

Returns:



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/ldclient-rb/ldclient.rb', line 244

def migration_variation(key, context, default_stage)
  unless Migrations::VALID_STAGES.include? default_stage
    @config.logger.error { "[LDClient] default_stage #{default_stage} is not a valid stage; continuing with 'off' as default" }
    default_stage = Migrations::STAGE_OFF
  end

  context = Impl::Context::make_context(context)
  detail, flag, _ = variation_with_flag(key, context, default_stage.to_s)

  stage = detail.value
  stage = stage.to_sym if stage.respond_to? :to_sym

  if Migrations::VALID_STAGES.include?(stage)
    tracker = Impl::Migrations::OpTracker.new(@config.logger, key, flag, context, detail, default_stage)
    return stage, tracker
  end

  detail = LaunchDarkly::Impl::Evaluator.error_result(LaunchDarkly::EvaluationReason::ERROR_WRONG_TYPE, default_stage.to_s)
  tracker = Impl::Migrations::OpTracker.new(@config.logger, key, flag, context, detail, default_stage)

  [default_stage, tracker]
end

#secure_mode_hash(context) ⇒ String?

Creates a hash string that can be used by the JavaScript SDK to identify a context. For more information, see [Secure mode](docs.launchdarkly.com/sdk/features/secure-mode#ruby).

Parameters:

Returns:

  • (String, nil) —

    a hash string or nil if the provided context was invalid



156
157
158
159
160
161
162
163
164
 
# File 'lib/ldclient-rb/ldclient.rb', line 156

def secure_mode_hash(context)
  context = Impl::Context.make_context(context)
  unless context.valid?
    @config.logger.warn("secure_mode_hash called with invalid context: #{context.error}")
    return nil
  end

  OpenSSL::HMAC.hexdigest("sha256", @sdk_key, context.fully_qualified_key)
end

#track(event_name, context, data = nil, metric_value = nil) ⇒ void

This method returns an undefined value.

Tracks that a context performed an event. This method creates a “custom” analytics event containing the specified event name (key), context properties, and optional data.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see #flush.

As of this version’s release date, the LaunchDarkly service does not support the ‘metricValue` parameter. As a result, specifying `metricValue` will not yet produce any different behavior from omitting it. Refer to the [SDK reference guide](docs.launchdarkly.com/sdk/features/events#ruby) for the latest status.

Parameters:

  • event_name (String) —

    The name of the event

  • context (Hash, LDContext) —

    a hash or object describing the context to track

  • data (Hash) (defaults to: nil) —

    An optional hash containing any additional data associated with the event

  • metric_value (Number) (defaults to: nil) —

    A numeric value used by the LaunchDarkly experimentation feature in numeric custom metrics. Can be omitted if this event is used by only non-numeric metrics. This field will also be returned as part of the custom event for Data Export.



317
318
319
320
321
322
323
324
325
 
# File 'lib/ldclient-rb/ldclient.rb', line 317

def track(event_name, context, data = nil, metric_value = nil)
  context = LaunchDarkly::Impl::Context.make_context(context)
  unless context.valid?
    @config.logger.warn("Track called with invalid context: #{context.error}")
    return
  end

  @event_processor.record_custom_event(context, event_name, data, metric_value)
end

#track_migration_op(tracker) ⇒ Object

Tracks the results of a migrations operation. This event includes measurements which can be used to enhance the observability of a migration within the LaunchDarkly UI.

This event should be generated through Interfaces::Migrations::OpTracker. If you are using the Interfaces::Migrations::Migrator to handle migrations, this event will be created and emitted automatically.

Parameters:



337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/ldclient-rb/ldclient.rb', line 337

def track_migration_op(tracker)
  unless tracker.is_a? LaunchDarkly::Interfaces::Migrations::OpTracker
    @config.logger.error { "invalid op tracker received in track_migration_op" }
    return
  end

  event = tracker.build
  if event.is_a? String
    @config.logger.error { "[LDClient] Error occurred generating migration op event; #{event}" }
    return
  end


  @event_processor.record_migration_op_event(event)
end

#variation(key, context, default) ⇒ Object

Determines the variation of a feature flag to present for a context.

Parameters:

  • key (String) —

    the unique feature key for the feature flag, as shown on the LaunchDarkly dashboard

  • context (Hash, LDContext) —

    a hash or LDContext instance describing the context requesting the flag

  • default —

    the default value of the flag; this is used if there is an error condition making it impossible to find or evaluate the flag

Returns:

  • the variation for the provided context, or the default value if there’s an error



199
200
201
202
 
# File 'lib/ldclient-rb/ldclient.rb', line 199

def variation(key, context, default)
  detail, _, _, = variation_with_flag(key, context, default)
  detail.value
end

#variation_detail(key, context, default) ⇒ EvaluationDetail

Determines the variation of a feature flag for a context, like #variation, but also provides additional information about how this value was calculated.

The return value of ‘variation_detail` is an EvaluationDetail object, which has three properties: the result value, the positional index of this value in the flag’s list of variations, and an object describing the main reason why this value was selected. See EvaluationDetail for more on these properties.

Calling ‘variation_detail` instead of `variation` also causes the “reason” data to be included in analytics events, if you are capturing detailed event data for this flag.

For more information, see the reference guide on [Evaluation reasons](docs.launchdarkly.com/sdk/concepts/evaluation-reasons).

Parameters:

  • key (String) —

    the unique feature key for the feature flag, as shown on the LaunchDarkly dashboard

  • context (Hash, LDContext) —

    a hash or object describing the context requesting the flag,

  • default —

    the default value of the flag; this is used if there is an error condition making it impossible to find or evaluate the flag

Returns:



227
228
229
230
 
# File 'lib/ldclient-rb/ldclient.rb', line 227

def variation_detail(key, context, default)
  detail, _, _ = evaluate_internal(key, context, default, true)
  detail
end