Class: LaunchDarkly::LDClient
- Inherits:
-
Object
- Object
- LaunchDarkly::LDClient
- Extended by:
- Forwardable
- 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
-
#big_segment_store_status_provider ⇒ Object
readonly
Returns an interface for tracking the status of a Big Segment store.
-
#data_source_status_provider ⇒ LaunchDarkly::Interfaces::DataSource::StatusProvider
readonly
Returns an interface for tracking the status of the data source.
-
#data_store_status_provider ⇒ LaunchDarkly::Interfaces::DataStore::StatusProvider
readonly
Returns an interface for tracking the status of a persistent data store.
-
#flag_tracker ⇒ Object
readonly
Returns an interface for tracking changes in feature flag configurations.
Instance Method Summary collapse
-
#add_hook(hook) ⇒ Object
Add a hook to the client.
-
#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.
-
#close ⇒ void
Releases all network connections and other resources held by the client, making it no longer usable.
-
#flush ⇒ Object
Tells the client that all pending analytics events should be delivered as soon as possible.
-
#identify(context) ⇒ void
Registers the context.
-
#initialize(sdk_key, config = Config.default, wait_for_sec = 5) ⇒ LDClient
constructor
Creates a new client instance that connects to LaunchDarkly.
-
#initialized? ⇒ Boolean
Returns whether the client has been initialized and is ready to serve feature flag requests.
-
#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.
-
#postfork(wait_for_sec = 5) ⇒ Object
Re-initializes an existing client after a process fork.
-
#secure_mode_hash(context) ⇒ String?
Creates a hash string that can be used by the JavaScript SDK to identify a context.
-
#track(event_name, context, data = nil, metric_value = nil) ⇒ void
Tracks that a context performed an event.
-
#track_migration_op(tracker) ⇒ Object
Tracks the results of a migrations operation.
-
#variation(key, context, default) ⇒ Object
Determines the variation of a feature flag to present for a context.
-
#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.
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.
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
# File 'lib/ldclient-rb/ldclient.rb', line 48 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 config.instance_id = SecureRandom.uuid @config = config 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.
627 628 629 |
# File 'lib/ldclient-rb/ldclient.rb', line 627 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.
654 655 656 |
# File 'lib/ldclient-rb/ldclient.rb', line 654 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.
641 642 643 |
# File 'lib/ldclient-rb/ldclient.rb', line 641 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.
663 664 665 |
# File 'lib/ldclient-rb/ldclient.rb', line 663 def flag_tracker @flag_tracker 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.
183 184 185 186 187 188 189 190 |
# File 'lib/ldclient-rb/ldclient.rb', line 183 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.
548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 |
# File 'lib/ldclient-rb/ldclient.rb', line 548 def all_flags_state(context, ={}) 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 = [:client_side_only] || false with_reasons = [:with_reasons] || false details_only_if_tracked = [: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)) 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.
612 613 614 615 616 617 618 619 |
# File 'lib/ldclient-rb/ldclient.rb', line 612 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.
204 205 206 |
# File 'lib/ldclient-rb/ldclient.rb', line 204 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.
459 460 461 462 463 464 465 466 467 468 469 470 471 472 |
# File 'lib/ldclient-rb/ldclient.rb', line 459 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:
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.
Failing that, it will return the value that you specified for the
default
parameter of #variation or #variation_detail.
243 244 245 |
# File 'lib/ldclient-rb/ldclient.rb', line 243 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.
418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 |
# File 'lib/ldclient-rb/ldclient.rb', line 418 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) 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.
83 84 85 86 87 88 89 |
# File 'lib/ldclient-rb/ldclient.rb', line 83 def postfork(wait_for_sec = 5) @data_source = nil @event_processor = nil @big_segment_store_manager = 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.
215 216 217 218 219 220 221 222 223 |
# File 'lib/ldclient-rb/ldclient.rb', line 215 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.
495 496 497 498 499 500 501 502 503 |
# File 'lib/ldclient-rb/ldclient.rb', line 495 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.
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 |
# File 'lib/ldclient-rb/ldclient.rb', line 515 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.
258 259 260 261 262 263 264 265 266 |
# File 'lib/ldclient-rb/ldclient.rb', line 258 def variation(key, context, default) 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.
291 292 293 294 295 296 297 298 299 |
# File 'lib/ldclient-rb/ldclient.rb', line 291 def variation_detail(key, context, default) 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 |