Documentation

Instrumentation

Learn how to instrument Flipper to be notified of feature operations and events.

Flipper comes with built-in instrumentation. Rails apps are pre-configured to use ActiveSupport Instrumentation. See Advanced Setup to manually configure outside of Rails.

Subscribing to feature operations

Flipper publishes events under the feature_operation.flipper key whenever a feature is checked or modified. So to get notified when your code calls Flipper.enabled?(:my_feature) or any other operation, you can add a subscriber in an initializer:

# config/initializers/flipper.rb
ActiveSupport::Notifications.subscribe('feature_operation.flipper') do |event|
  case event.payload[:operation]
  when :enabled?
    puts "#{event.payload[:feature_name]} enabled? #{event.payload[:result]}"
  when :enable
    puts "#{event.payload[:feature_name]} enabled!"
  when :disable
    puts "#{event.payload[:feature_name]} disabled!"
  when :add
    puts "#{event.payload[:feature_name]} added!"
  when :remove
    puts "#{event.payload[:feature_name]} removed!"
  when :exist?
    puts "#{event.payload[:feature_name]} exist?"
  when :clear
    puts "#{event.payload[:feature_name]} cleared!"
  end
end

The payload contains:

• :feature_name - The name of the feature that Flipper is performing the operation on. For example, :search when you call Flipper.enabled?(:search).
• :operation - One of :enabled?, :enable, :disable, :add, :remove, :exist?, and :clear.
• :result - The result returned when calling the operation.

Subscribing to adapter operations

If you need to know exactly what's happening at the adapter level, you can use the Instrumented adapter to subscribe to adapter_operation.flipper events. You'll need to manually configure your Flipper adapter before you can subscribe.

# config/initializers/flipper.rb
Flipper.configure do |config|
  # To instrument `adapter_operation` events
  config.adapter do
    Flipper::Adapters::Instrumented.new(
      Flipper::Adapters::Memory.new,
      instrumenter: ActiveSupport::Notifications
    )
  end
end

ActiveSupport::Notifications.subscribe('adapter_operation.flipper') do |event|
  puts event.inspect
end

Advanced Setup

If you are using Flipper outside of Rails, or want to use a different instrumentation library than ActiveSupport::Notifications, you can manually configure it by passing the instrumenter option to the Flipper instance, and optionally wrap your adapter with the Instrumented adapter to get adapter_operation events:

require 'active_support/notifications'

Flipper.configure do |config|
  # To instrument `adapter_operation` events
  config.adapter do
    Flipper::Adapters::Instrumented.new(
      Flipper::Adapters::Memory.new,
      instrumenter: ActiveSupport::Notifications
    )
  end

  # To instrument `feature_operation` events
  config.default do
    Flipper.new(config.adapter,
      instrumenter: ActiveSupport::Notifications
    )
  end
end

Pre-built Subscribers

Flipper comes with a few pre-built subscribers.

Logging

The log subscriber is enabled by default in Rails apps. To use it outside of Rails, just require it:

# Gemfile
gem "activesupport"

# config/initializers/flipper.rb (or wherever you want it)
require "flipper/instrumentation/log_subscriber"

StatsD

To use the statsd instrumentation in Flipper 1.1.0 or later:

# Gemfile
gem "activesupport"
gem "statsd-ruby"

# config/initializers/flipper.rb (or wherever you want it)
Flipper.configure do |config|
  config.statsd = Statsd.new # or whatever your statsd instance is
end

require "flipper/instrumentation/statsd"
Flipper::Instrumentation::StatsdSubscriber.client = Statsd.new # or whatever your statsd instance is