cw-datadog 2.23.0.2

data/lib/datadog/tracing/contrib/active_support/cache/instrumentation.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require_relative '../../../../core/utils'
+require_relative '../../../metadata/ext'
+require_relative '../ext'
+require_relative 'event'
+
+module Datadog
+  module Tracing
+    module Contrib
+      module ActiveSupport
+        module Cache
+          # DEV-3.0: Backwards compatibility code for the 2.x gem series.
+          # DEV-3.0:
+          # DEV-3.0: `ActiveSupport::Cache` is now instrumented by subscribing to ActiveSupport::Notifications events.
+          # DEV-3.0: The implementation is located at {Datadog::Tracing::Contrib::ActiveSupport::Cache::Events::Cache}.
+          # DEV-3.0: The events emitted provide richer introspection points (e.g. events for cache misses on `#fetch`) while
+          # DEV-3.0: also ensuring we are using Rails' public API for improved compatibility.
+          # DEV-3.0:
+          # DEV-3.0: But a few operations holds us back:
+          # DEV-3.0: 1. `ActiveSupport::Cache::Store#fetch`:
+          # DEV-3.0:   This method does not have an event that can produce an equivalent span to today's 2.x implementation.
+          # DEV-3.0:   In 2.x, `#fetch` produces two separate, *nested* spans: one for the `#read` operation and
+          # DEV-3.0:   another for the `#write` operation that is called internally by `#fetch` when the cache key needs
+          # DEV-3.0:   to be populated on a cache miss.
+          # DEV-3.0:   But the ActiveSupport events emitted by `#fetch` provide two *sibling* events for the`#read` and
+          # DEV-3.0:   `#write` operations.
+          # DEV-3.0:   Moving from nested spans to sibling spans would be a breaking change. One notable difference is
+          # DEV-3.0:   that if the nested `#write` operation fails 2.x, the `#read` span is marked as an error. This would
+          # DEV-3.0:   not be the case with sibling spans, and would be a very visible change.
+          # DEV-3.0: 2. `ActiveSupport::Cache::Store#read_multi` & `ActiveSupport::Cache::Store#fetch_multi`:
+          # DEV-3.0:   ActiveSupport events were introduced in ActiveSupport 5.2.0 for these methods.
+          # DEV-3.0:
+          # DEV-3.0: At the end of the day, moving to ActiveSupport events is the better approach, but we have to retain
+          # DEV-3.0: this last few monkey patches (and all the supporting code) to avoid a breaking change for now.
+          #
+          # Defines the deprecate  monkey-patch instrumentation for `ActiveSupport::Cache::Store#fetch`
+          module Instrumentation
+            module_function
+
+            # @param action [String] type of cache operation. Will be set as the span resource.
+            # @param key [Object] redis cache key. Used for actions with a single key locator.
+            # @param multi_key [Array<Object>] list of redis cache keys. Used for actions with a multiple key locators.
+            def trace(action, store, key: nil, multi_key: nil)
+              return yield unless enabled?
+
+              # create a new ``Span`` and add it to the tracing context
+              Tracing.trace(
+                Ext::SPAN_CACHE,
+                type: Ext::SPAN_TYPE_CACHE,
+                service: Datadog.configuration.tracing[:active_support][:cache_service],
+                resource: action
+              ) do |span|
+                span.set_tag(Tracing::Metadata::Ext::TAG_COMPONENT, Ext::TAG_COMPONENT)
+                span.set_tag(Tracing::Metadata::Ext::TAG_OPERATION, Ext::TAG_OPERATION_CACHE)
+
+                if span.service != Datadog.configuration.service
+                  span.set_tag(Tracing::Contrib::Ext::Metadata::TAG_BASE_SERVICE, Datadog.configuration.service)
+                end
+
+                span.set_tag(Ext::TAG_CACHE_BACKEND, store) if store
+
+                set_cache_key(span, key, multi_key) if Datadog.configuration.tracing[:active_support][:cache_key].enabled
+
+                yield
+              end
+            end
+
+            # In most of the cases, `#fetch()` and `#read()` calls are nested.
+            # Instrument both does not add any value.
+            # This method checks if these two operations are nested.
+            #
+            # DEV-3.0: We should not have these checks in the 3.x series because ActiveSupport events provide more
+            # DEV-3.0: legible nested spans. While using ActiveSupport events, the nested spans actually provide meaningful
+            # DEV-3.0: information.
+            def nested_read?
+              current_span = Tracing.active_span
+              current_span && current_span.name == Ext::SPAN_CACHE && current_span.resource == Ext::RESOURCE_CACHE_GET
+            end
+
+            # (see #nested_read?)
+            def nested_multiread?
+              current_span = Tracing.active_span
+              current_span && current_span.name == Ext::SPAN_CACHE && current_span.resource == Ext::RESOURCE_CACHE_MGET
+            end
+
+            def set_cache_key(span, single_key, multi_key)
+              if multi_key
+                resolved_key = multi_key.map { |key| ::ActiveSupport::Cache.expand_cache_key(key) }
+                cache_key = Core::Utils.truncate(resolved_key, Ext::QUANTIZE_CACHE_MAX_KEY_SIZE)
+                span.set_tag(Ext::TAG_CACHE_KEY_MULTI, cache_key)
+              else
+                resolved_key = ::ActiveSupport::Cache.expand_cache_key(single_key)
+                cache_key = Core::Utils.truncate(resolved_key, Ext::QUANTIZE_CACHE_MAX_KEY_SIZE)
+                span.set_tag(Ext::TAG_CACHE_KEY, cache_key)
+              end
+            end
+
+            def enabled?
+              Tracing.enabled? && Datadog.configuration.tracing[:active_support][:enabled]
+            end
+
+            # Instance methods injected into the cache client
+            module InstanceMethods
+              private
+
+              # The name of the store is never saved.
+              # ActiveSupport looks up stores by converting a symbol into a 'require' path,
+              # then "camelizing" it for a `const_get` call:
+              # ```
+              # require "active_support/cache/#{store}"
+              # ActiveSupport::Cache.const_get(store.to_s.camelize)
+              # ```
+              # @see https://github.com/rails/rails/blob/261975dbef77731d2c76f907f1076c5132ebc0e4/activesupport/lib/active_support/cache.rb#L139-L149
+              #
+              # As `self` is the store object, we can reverse engineer
+              # the original symbol by converting the class name to snake case:
+              # e.g. ActiveSupport::Cache::RedisStore -> active_support/cache/redis_store
+              # In this case, `redis_store` is the store name.
+              #
+              # Because there's no API retrieve only the class name
+              # (only `RedisStore`, and not `ActiveSupport::Cache::RedisStore`)
+              # the easiest way to retrieve the store symbol is to convert the fully qualified
+              # name using the Rails-provided method `#underscore`, which is the reverse of `#camelize`,
+              # then extracting the last part of it.
+              #
+              # Also, this method caches the store name, given this value will be retrieve
+              # multiple times and involves string manipulation.
+              def dd_store_name
+                return @store_name if defined?(@store_name)
+
+                # DEV: String#underscore is available through ActiveSupport, and is
+                # DEV: the exact reverse operation to `#camelize`.
+                # DEV: String#demodulize is available through ActiveSupport, and is
+                # DEV: used to remove the module ('*::') part of a constant name.
+                @store_name = self.class.name.demodulize.underscore
+              end
+            end
+
+            # Defines the the legacy monkey-patching instrumentation for ActiveSupport cache read_multi
+            # DEV-3.0: ActiveSupport::Notifications events were introduced in ActiveSupport 5.2.0 for this method.
+            # DEV-3.0: As long as we support ActiveSupport < 5.2.0, we have to keep this method.
+            module ReadMulti
+              include InstanceMethods
+
+              def read_multi(*keys, **options, &block)
+                return super if Instrumentation.nested_multiread?
+
+                Instrumentation.trace(Ext::RESOURCE_CACHE_MGET, dd_store_name, multi_key: keys) { super }
+              end
+            end
+
+            # Defines the the legacy monkey-patching instrumentation for ActiveSupport cache fetch
+            module Fetch
+              include InstanceMethods
+
+              def fetch(*args, &block)
+                return super if Instrumentation.nested_read?
+
+                Instrumentation.trace(Ext::RESOURCE_CACHE_GET, dd_store_name, key: args[0]) { super }
+              end
+            end
+
+            # Defines the the legacy monkey-patching instrumentation for ActiveSupport cache fetch_multi
+            # DEV-3.0: ActiveSupport::Notifications events were introduced in ActiveSupport 5.2.0 for this method.
+            # DEV-3.0: As long as we support ActiveSupport < 5.2.0, we have to keep this method.
+            module FetchMulti
+              include InstanceMethods
+
+              def fetch_multi(*args, **options, &block)
+                return super if Instrumentation.nested_multiread?
+
+                keys = args[-1].instance_of?(Hash) ? args[0..-2] : args
+                Instrumentation.trace(Ext::RESOURCE_CACHE_MGET, dd_store_name, multi_key: keys) { super }
+              end
+            end
+
+            # Backports the payload[:store] key present since Rails 6.1:
+            # https://github.com/rails/rails/commit/6fa747f2946ee244b2aab0cd8c3c064f05d950a5
+            module Store
+              def instrument(operation, key, options = nil)
+                polyfill_options = options&.dup || {}
+                polyfill_options[:store] = self.class.name
+                super(operation, key, polyfill_options)
+              end
+            end
+
+            # Save the original, user-supplied cache key, before it gets normalized.
+            #
+            # Normalized keys can include internal implementation detail,
+            # for example FileStore keys include temp directory names, which
+            # changes on every run, making it impossible to group by the cache key afterward.
+            # Also, the user is never exposed to the normalized key, and only sets/gets using the
+            # original key.
+            module PreserveOriginalKey
+              # Stores the original keys in the options hash, as an array of keys.
+              # It's important to keep all the keys for multi-key operations.
+              # For single-key operations, the key is stored as an array of a single element.
+              def normalize_key(key, options)
+                orig_keys = options[:dd_original_keys] || []
+                orig_keys << key
+                options[:dd_original_keys] = orig_keys
+
+                super
+              end
+
+              # Ensure we don't pollute the default Store instance `options` in {PreserveOriginalKey#normalize_key}.
+              # In most cases, `merged_options` returns a new hash,
+              # but we check for cases where it reuses the instance hash.
+              def merged_options(call_options)
+                ret = super
+
+                if ret.equal?(options)
+                  ret.dup
+                else
+                  ret
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/contrib/active_support/cache/patcher.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../../patcher'
+require_relative 'instrumentation'
+require_relative 'events'
+
+module Datadog
+  module Tracing
+    module Contrib
+      module ActiveSupport
+        module Cache
+          # Patcher enables patching of 'active_support' module.
+          module Patcher
+            include Contrib::Patcher
+
+            module_function
+
+            def target_version
+              Integration.version
+            end
+
+            def patch
+              Events.subscribe!
+
+              if Integration.version >= Gem::Version.new('8.0.0')
+                ::ActiveSupport::Cache::Store.prepend(Cache::Instrumentation::PreserveOriginalKey)
+              end
+
+              # Backfill the `:store` key in the ActiveSupport event payload for older Rails.
+              if Integration.version < Gem::Version.new('6.1.0')
+                ::ActiveSupport::Cache::Store.prepend(Cache::Instrumentation::Store)
+              end
+
+              # DEV-3.0: Backwards compatibility code for the 2.x gem series.
+              # DEV-3.0: See documentation at {Datadog::Tracing::Contrib::ActiveSupport::Cache::Instrumentation}
+              # DEV-3.0: for the complete information about this backwards compatibility code.
+              patch_legacy_cache_store
+            end
+
+            # This method is overwritten by
+            # `datadog/tracing/contrib/active_support/cache/redis.rb`
+            # with more complex behavior.
+            def cache_store_class(meth)
+              [::ActiveSupport::Cache::Store]
+            end
+
+            def patch_legacy_cache_store
+              cache_store_class(:read_multi).each { |clazz| clazz.prepend(Cache::Instrumentation::ReadMulti) }
+              cache_store_class(:fetch).each { |clazz| clazz.prepend(Cache::Instrumentation::Fetch) }
+              cache_store_class(:fetch_multi).each { |clazz| clazz.prepend(Cache::Instrumentation::FetchMulti) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/contrib/active_support/cache/redis.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../../support'
+require_relative 'patcher'
+
+module Datadog
+  module Tracing
+    module Contrib
+      module ActiveSupport
+        module Cache
+          # Support for Redis with ActiveSupport
+          module Redis
+            # Patching behavior for Redis with ActiveSupport
+            module Patcher
+              # For Rails < 5.2 w/ redis-activesupport...
+              # When Redis is used, we can't only patch Cache::Store as it is
+              # Cache::RedisStore, a sub-class of it that is used, in practice.
+              # We need to do a per-method monkey patching as some of them might
+              # be redefined, and some of them not. The latest version of redis-activesupport
+              # redefines write but leaves untouched read and delete:
+              # https://github.com/redis-store/redis-activesupport/blob/v4.1.5/lib/active_support/cache/redis_store.rb
+              #
+              # For Rails >= 5.2 w/o redis-activesupport...
+              # ActiveSupport includes a Redis cache store internally, and does not require these overrides.
+              # https://github.com/rails/rails/blob/master/activesupport/lib/active_support/cache/redis_cache_store.rb
+              def patch_redis_store?(meth)
+                !Gem.loaded_specs['redis-activesupport'].nil? \
+                  && defined?(::ActiveSupport::Cache::RedisStore) \
+                  && ::ActiveSupport::Cache::RedisStore.instance_methods(false).include?(meth)
+              end
+
+              # Patches the Rails built-in Redis cache backend `redis_cache_store`, added in Rails 5.2.
+              # We avoid loading the RedisCacheStore class, as it invokes the statement `gem "redis", ">= 4.0.1"` which
+              # fails if the application is using an old version of Redis, or not using Redis at all.
+              # @see https://github.com/rails/rails/blob/d0dcb8fa6073a0c4d42600c15e82e3bb386b27d3/activesupport/lib/active_support/cache/redis_cache_store.rb#L4
+              def patch_redis_cache_store?(meth)
+                Gem.loaded_specs['redis'] &&
+                  Support.fully_loaded?(::ActiveSupport::Cache, :RedisCacheStore) &&
+                  ::ActiveSupport::Cache::RedisCacheStore.instance_methods(false).include?(meth)
+              end
+
+              def cache_store_class(meth)
+                if patch_redis_store?(meth)
+                  [::ActiveSupport::Cache::RedisStore, ::ActiveSupport::Cache::Store]
+                elsif patch_redis_cache_store?(meth)
+                  [::ActiveSupport::Cache::RedisCacheStore, ::ActiveSupport::Cache::Store]
+                else
+                  super
+                end
+              end
+            end
+
+            # Decorate Cache patcher with Redis support
+            Cache::Patcher.singleton_class.prepend(Redis::Patcher)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/contrib/active_support/configuration/settings.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../../configuration/settings'
+require_relative '../ext'
+
+module Datadog
+  module Tracing
+    module Contrib
+      module ActiveSupport
+        module Configuration
+          # Custom settings for the ActiveSupport integration
+          # @public_api
+          class Settings < Contrib::Configuration::Settings
+            option :enabled do |o|
+              o.type :bool
+              o.env Ext::ENV_ENABLED
+              o.default true
+            end
+
+            # @!visibility private
+            option :analytics_enabled do |o|
+              o.type :bool
+              o.env Ext::ENV_ANALYTICS_ENABLED
+              o.default false
+            end
+
+            option :analytics_sample_rate do |o|
+              o.type :float
+              o.env Ext::ENV_ANALYTICS_SAMPLE_RATE
+              o.default 1.0
+            end
+
+            option :cache_service do |o|
+              o.type :string, nilable: true
+              o.default do
+                Contrib::SpanAttributeSchema.fetch_service_name(
+                  '',
+                  Ext::SERVICE_CACHE
+                )
+              end
+            end
+
+            # grouped "cache_key.*" settings
+            settings :cache_key do
+              # enable or disabling the inclusion of the cache_key in the span
+              option :enabled do |o|
+                # cache_key.enabled
+                o.type :bool
+                o.default true
+              end
+            end
+
+            # Specifies which cache stores to trace.
+            # Accepts a list, with the same format as `config.cache_store`
+            # (e.g. `memory_store`, `file_store`, or symbols like `:file_store`).
+            # Defaults to `nil`, which traces all cache stores.
+            # @see https://github.com/rails/rails/blob/b7520a13adda46c0cc5f3fb4a4c1726633af2bba/guides/source/caching_with_rails.md?plain=1#L576-L582
+            option :cache_store do |o|
+              o.type :array, nilable: true
+              o.default nil
+              o.after_set do |stores|
+                stores&.map!(&:to_s) # Convert symbols to strings to match the Rails configuration format
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/contrib/active_support/ext.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Contrib
+      module ActiveSupport
+        # ActiveSupport integration constants
+        # @public_api Changing resource names, tag names, or environment variables creates breaking changes.
+        module Ext
+          ENV_ENABLED = 'DD_TRACE_ACTIVE_SUPPORT_ENABLED'
+          # @!visibility private
+          ENV_ANALYTICS_ENABLED = 'DD_TRACE_ACTIVE_SUPPORT_ANALYTICS_ENABLED'
+          ENV_ANALYTICS_SAMPLE_RATE = 'DD_TRACE_ACTIVE_SUPPORT_ANALYTICS_SAMPLE_RATE'
+          QUANTIZE_CACHE_MAX_KEY_SIZE = 300
+          RESOURCE_CACHE_DELETE = 'DELETE'
+          RESOURCE_CACHE_GET = 'GET'
+          RESOURCE_CACHE_MGET = 'MGET'
+          RESOURCE_CACHE_SET = 'SET'
+          RESOURCE_CACHE_MSET = 'MSET'
+          SERVICE_CACHE = 'active_support-cache'
+          SPAN_CACHE = 'rails.cache'
+          SPAN_TYPE_CACHE = 'cache'
+          TAG_CACHE_BACKEND = 'rails.cache.backend'
+          TAG_CACHE_KEY = 'rails.cache.key'
+          TAG_CACHE_KEY_MULTI = 'rails.cache.keys'
+          TAG_COMPONENT = 'active_support'
+          TAG_OPERATION_CACHE = 'cache'
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/contrib/active_support/integration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative '../integration'
+require_relative 'configuration/settings'
+require_relative 'patcher'
+require_relative 'cache/redis'
+require_relative '../rails/ext'
+require_relative '../../../core/contrib/rails/utils'
+
+module Datadog
+  module Tracing
+    module Contrib
+      module ActiveSupport
+        # Describes the ActiveSupport integration
+        class Integration
+          include Contrib::Integration
+
+          MINIMUM_VERSION = Contrib::Rails::Ext::MINIMUM_VERSION
+
+          # @public_api Changing the integration name or integration options can cause breaking changes
+          register_as :active_support, auto_patch: false
+          def self.gem_name
+            'activesupport'
+          end
+
+          def self.version
+            Gem.loaded_specs['activesupport']&.version
+          end
+
+          def self.loaded?
+            !defined?(::ActiveSupport).nil?
+          end
+
+          def self.compatible?
+            super && version >= MINIMUM_VERSION
+          end
+
+          # enabled by rails integration so should only auto instrument
+          # if detected that it is being used without rails
+          def auto_instrument?
+            !Core::Contrib::Rails::Utils.railtie_supported?
+          end
+
+          def new_configuration
+            Configuration::Settings.new
+          end
+
+          def patcher
+            ActiveSupport::Patcher
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/contrib/active_support/notifications/event.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'subscriber'
+
+module Datadog
+  module Tracing
+    module Contrib
+      module ActiveSupport
+        module Notifications
+          # Defines behaviors for an ActiveSupport::Notifications event.
+          # Compose this into a module or class, then define
+          # #event_name, #span_name, and #process. You can then
+          # invoke Event.subscribe! to more easily subscribe to an event.
+          module Event
+            def self.included(base)
+              base.include(Subscriber)
+              base.extend(ClassMethods)
+              base.send(:on_subscribe) { base.subscribe }
+            end
+
+            # Redefines some class behaviors for a Subscriber to make
+            # it a bit simpler for an Event.
+            module ClassMethods
+              # Publicly exposes protected method `subscribe!`
+              def subscribe! # rubocop:disable Lint/UselessMethodDefinition
+                super
+              end
+
+              def subscription(span_name = nil, span_options = nil, on_start: nil, on_finish: nil, trace: nil)
+                super(
+                  span_name || self.span_name,
+                  span_options || self.span_options,
+                  on_start: on_start,
+                  on_finish: on_finish,
+                  trace: trace
+                )
+              end
+
+              def subscribe(pattern = nil, span_name = nil, span_options = nil)
+                if supported?
+                  super(
+                    pattern || event_name,
+                    span_name || self.span_name,
+                    span_options || self.span_options,
+                    on_start: method(:on_start),
+                    on_finish: method(:on_finish),
+                    trace: method(:trace?)
+                  )
+                end
+              end
+
+              def supported?
+                true
+              end
+
+              def span_options
+                {}
+              end
+
+              def report_if_exception(span, payload)
+                exception = payload_exception(payload)
+                span.set_error(payload[:exception]) if exception
+              end
+
+              def payload_exception(payload)
+                payload[:exception_object] ||
+                  payload[:exception] # Fallback for ActiveSupport < 5.0
+              end
+
+              def on_start(_span, _event, _id, _payload)
+              end
+
+              def on_finish(span, _event, _id, payload)
+                record_exception(span, payload)
+              end
+
+              def trace?(_event, _payload)
+                true
+              end
+
+              def record_exception(span, payload)
+                if payload[:exception_object]
+                  span.set_error(payload[:exception_object])
+                elsif payload[:exception]
+                  # Fallback for ActiveSupport < 5.0
+                  span.set_error(payload[:exception])
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/contrib/active_support/notifications/subscriber.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative 'subscription'
+
+module Datadog
+  module Tracing
+    module Contrib
+      module ActiveSupport
+        module Notifications
+          # For classes that listen to ActiveSupport::Notification events.
+          # Creates subscriptions that are wrapped with tracing.
+          module Subscriber
+            def self.included(base)
+              base.extend(ClassMethods)
+            end
+
+            # Class methods that are implemented in the inheriting class.
+            module ClassMethods
+              # Returns a list of subscriptions created for this class.
+              def subscriptions
+                @subscriptions ||= Set.new
+              end
+
+              # Returns whether subscriptions have been activated, via #subscribe!
+              def subscribed?
+                subscribed == true
+              end
+
+              protected
+
+              # Defines a callback for when subscribe! is called.
+              # Should contain subscription setup, defined by the inheriting class.
+              def on_subscribe(&block)
+                @on_subscribe_block = block
+              end
+
+              # Runs the on_subscribe callback once, to activate subscriptions.
+              # Should be triggered by the inheriting class.
+              def subscribe!
+                return subscribed? if subscribed? || on_subscribe_block.nil?
+
+                on_subscribe_block.call
+                @subscribed = true
+              end
+
+              # Creates a subscription and immediately activates it.
+              def subscribe(pattern, span_name, span_options = {}, on_start: nil, on_finish: nil, trace: nil)
+                subscription(
+                  span_name,
+                  span_options,
+                  on_start: on_start,
+                  on_finish: on_finish,
+                  trace: trace
+                ).tap do |subscription|
+                  subscription.subscribe(pattern)
+                end
+              end
+
+              # Creates a subscription without activating it.
+              # Subscription is added to the inheriting class' list of subscriptions.
+              def subscription(span_name, span_options = {}, on_start: nil, on_finish: nil, trace: nil)
+                Subscription.new(
+                  span_name,
+                  span_options,
+                  on_start: on_start,
+                  on_finish: on_finish,
+                  trace: trace
+                ).tap do |subscription|
+                  subscriptions << subscription
+                end
+              end
+
+              private
+
+              attr_reader :subscribed, :on_subscribe_block
+            end
+          end
+        end
+      end
+    end
+  end
+end