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



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
 
# File 'lib/ldclient-rb/ldclient.rb', line 60

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 to
  # not provide a SDK key.
  #   * Offline mode
  #   * Using LDD mode with events disabled
  #   * Using a custom data source (like FileData) with events disabled
  if !config.offline? && sdk_key.nil?
    # If the data source is nil we create a default data source which requires the SDK key.
    if config.send_events || (!config.use_ldd? && config.data_source.nil?)
      raise ArgumentError, "sdk_key must not be nil"
    end
  end

  @sdk_key = sdk_key
  config.instance_id = SecureRandom.uuid
  @config = config

  # The pid of the process that owns this client's background threads. A child process that
  # inherits this client after a fork has a different pid. See #check_forked.
  @owner_pid = Process.pid
  # The pid of the process in which the fork warning was last logged, or nil.
  @fork_warned_pid = Concurrent::AtomicReference.new(nil)

  # Each flag lets the matching cached-data warning log once per client.
  @cached_data_evaluation_warned = Concurrent::AtomicBoolean.new(false)
  @cached_data_all_flags_warned = Concurrent::AtomicBoolean.new(false)

  start_up(wait_for_sec)
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.



723
724
725
 
# File 'lib/ldclient-rb/ldclient.rb', line 723

def big_segment_store_status_provider
  @big_segment_store_status_provider
end

Instance Method Details

#add_hook(hook) ⇒ Object

Add a hook to the client. In order to register a hook before the client starts, please use the hooks property of #LDConfig.

Hooks provide entrypoints which allow for observation of SDK functions.

Parameters:



274
275
276
277
278
279
280
281
 
# File 'lib/ldclient-rb/ldclient.rb', line 274

def add_hook(hook)
  unless hook.is_a?(Interfaces::Hooks::Hook)
    @config.logger.error { "[LDClient] Attempted to add a hook that does not include the LaunchDarkly::Intefaces::Hooks::Hook mixin. Ignoring." }
    return
  end

  @hooks.push(hook)
end

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



629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
 
# File 'lib/ldclient-rb/ldclient.rb', line 629

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

  check_forked

  unless initialized?
    if @data_system.store.initialized?
      if @cached_data_all_flags_warned.make_true
        @config.logger.warn { "Called all_flags_state before client initialization; using last known values from data store. This message is logged once." }
      end
    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 = @data_system.store.all(Impl::DataStore::FEATURES)
  rescue => exn
    Impl::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
      (eval_result, eval_state) = @evaluator.evaluate(f, context)
      detail = eval_result.detail
    rescue => exn
      detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION))
      Impl::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,
      prerequisites: eval_state.prerequisites,
      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.



709
710
711
712
713
714
715
 
# File 'lib/ldclient-rb/ldclient.rb', line 709

def close
  check_forked
  @config.logger.info { "[LDClient] Closing LaunchDarkly client..." }
  @data_system.stop
  @event_processor.stop
  @big_segment_store_manager.stop
end

#data_source_status_provider ⇒ LaunchDarkly::Interfaces::DataSource::StatusProvider

Delegates to the data system Impl::DataSystem#data_source_status_provider.

Returns:



42
 
# File 'lib/ldclient-rb/ldclient.rb', line 42

def_delegators :@data_system, :data_store_status_provider, :data_source_status_provider

#data_store_status_provider ⇒ LaunchDarkly::Interfaces::DataStore::StatusProvider

Delegates to the data system Impl::DataSystem#data_store_status_provider.

Returns:



42
 
# File 'lib/ldclient-rb/ldclient.rb', line 42

def_delegators :@data_system, :data_store_status_provider, :data_source_status_provider

#flag_tracker ⇒ Object

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.



732
733
734
 
# File 'lib/ldclient-rb/ldclient.rb', line 732

def flag_tracker
  @flag_tracker
end

#flush ⇒ void

This method returns an undefined value.

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

Delegates to EventProcessorMethods#flush.



700
701
702
703
 
# File 'lib/ldclient-rb/ldclient.rb', line 700

def flush
  check_forked
  @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



537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
 
# File 'lib/ldclient-rb/ldclient.rb', line 537

def identify(context)
  check_forked
  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.

  2. 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



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

def initialized?
  return true if @config.offline? || @config.use_ldd?

  Impl::DataSystem::DataAvailability.at_least?(@data_system.data_availability, Impl::DataSystem::DataAvailability::CACHED)
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:



495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
 
# File 'lib/ldclient-rb/ldclient.rb', line 495

def migration_variation(key, context, default_stage)
  check_forked
  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)
  result = evaluate_with_hooks(key, context, default_stage, :migration_variation) do
    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)
      next LaunchDarkly::Impl::EvaluationWithHookResult.new(detail, {stage: stage, tracker: 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)

    LaunchDarkly::Impl::EvaluationWithHookResult.new(detail, {stage: default_stage, tracker: tracker})
  end

  [result.results[:stage], result.results[:tracker]]
end

#postfork(wait_for_sec = 5) ⇒ Object

Re-initializes an existing client after a process fork.

The SDK relies on multiple background threads to operate correctly. When a process forks, these threads are not available to the child <https://apidock.com/ruby/Process/fork/class>.

As a result, the SDK will not function correctly in the child process until it is re-initialized.

This method is effectively equivalent to instantiating a new client. Future iterations of the SDK will provide increasingly efficient re-initializing improvements.

Note that any configuration provided to the SDK will need to survive the forking process independently. For this reason, it is recommended that any listener or hook integrations be added postfork unless you are certain it can survive the forking process.

If the SDK is used in a forked child process before this method is called, it logs a warning once per process. The warning says that flag updates and analytics events will not work until postfork is called. Calling this method clears that condition for the current process.

Parameters:

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

    maximum time (in seconds) to wait for initialization



112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/ldclient-rb/ldclient.rb', line 112

def postfork(wait_for_sec = 5)
  @data_system = nil
  @event_processor = nil
  @big_segment_store_manager = nil
  @flag_tracker = nil

  @owner_pid = Process.pid
  @fork_warned_pid.set(nil)

  start_up(wait_for_sec)
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.

Parameters:

Returns:

  • (String, nil) —

    a hash string or nil if the provided context was invalid



290
291
292
293
294
295
296
297
298
 
# File 'lib/ldclient-rb/ldclient.rb', line 290

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 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.



574
575
576
577
578
579
580
581
582
583
 
# File 'lib/ldclient-rb/ldclient.rb', line 574

def track(event_name, context, data = nil, metric_value = nil)
  check_forked
  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:



595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
 
# File 'lib/ldclient-rb/ldclient.rb', line 595

def track_migration_op(tracker)
  check_forked
  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



335
336
337
338
339
340
341
342
343
344
 
# File 'lib/ldclient-rb/ldclient.rb', line 335

def variation(key, context, default)
  check_forked
  context = Impl::Context::make_context(context)
  result = evaluate_with_hooks(key, context, default, :variation) do
    detail, _, _ = variation_with_flag(key, context, default)
    LaunchDarkly::Impl::EvaluationWithHookResult.new(detail)
  end

  result.evaluation_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.

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:



369
370
371
372
373
374
375
376
377
378
 
# File 'lib/ldclient-rb/ldclient.rb', line 369

def variation_detail(key, context, default)
  check_forked
  context = Impl::Context::make_context(context)
  result = evaluate_with_hooks(key, context, default, :variation_detail) do
    detail, _, _ = evaluate_internal(key, context, default, true)
    LaunchDarkly::Impl::EvaluationWithHookResult.new(detail)
  end

  result.evaluation_detail
end