opentelemetry-instrumentation-base 0.17.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba0841769aa5f9825a4441f3e58c54fd9a6e45e9293b10d69328021ddd737f62
+  data.tar.gz: f036225206648e9a5e62ed94654ae70ed18b4c473daae02aade8ea7dd0f7148b
+SHA512:
+  metadata.gz: ea0bb52d80a047ff083032150a3c1badfc89837f9ef0bbba024318b6db4043a7070df9997e7dd73af7150f454f811a7a4ed0d8ab65448f0a3af15689a88f5750
+  data.tar.gz: '019bf3b8fe6e30ee74c0f6cd4a8361e838ce7a1d52248c661361cc4e71d4a1696aef0507d2a21f8bcc15dc23f0e9f0dae32d518dd814c08481bbff983bda8388'

data/.yardopts

@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Base Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release History: opentelemetry-instrumentation-base
+
+### v0.17.0 / 2021-04-22
+
+* Initial release.

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright The OpenTelemetry Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,154 @@
+# OpenTelemetry Instrumentation Base
+
+The `opentelemetry-instrumentation-base` gem contains the instrumentation base class, and the instrumentation registry.  These modules provide a common interface to support the installation of auto instrumentation libraries.  The instrumentation base is responsible for adding itself to the instrumentation registry as well as providing convenience hooks for the installation process.  The instrumentation registry contains all the instrumentation to be installed during the SDK configuration process.
+
+## How do I get started?
+
+Install the gem using:
+
+```
+gem install opentelemetry-instrumentation-base
+```
+
+Or, if you use [bundler][bundler-home], include `opentelemetry-instrumentation-base` in your `Gemfile`.
+
+### For SDK Authors
+
+The following is a simplified demonstration of how the `OpenTelemetry::Instrumentation.registry` can be used by an SDK to install auto-instrumentation gems as part of its configuration.  This should not be used as an example of how to implement an SDK as there are large omissions.  For an example of a complete implementation see the `opentelemetry-sdk` gem.
+
+```ruby
+require 'bundler/inline'
+
+gemfile(true) do
+  source 'https://rubygems.org'
+  gem 'opentelemetry-api'
+  gem 'opentelemetry-instrumentation-base'
+  gem 'opentelemetry-instrumentation-net_http'
+end
+
+require 'opentelemetry-api'
+require 'opentelemetry-instrumentation-base'
+
+# Setup a noop custom tracer for our SDK
+class MyCustomTracer < OpenTelemetry::Trace::Tracer
+  def initialize(name, version)
+    @name = name
+    @version = version
+  end
+end
+
+# Setup a tracer provider for our SDK
+class MyCustomTracerProvider < OpenTelemetry::Trace::TracerProvider
+  def tracer(name = nil, version = nil)
+    MyCustomTracer.new(name, version)
+  end
+end
+
+class MyCustomSDK
+  def self.configure(config = {})
+    # It is important that we upgrade the API tracer provider to
+    # our SDK tracer provider so that when the install hook is
+    # called that our instrumentation libraries receive an
+    # SDK tracer instead of the noop API tracer.
+    OpenTelemetry.tracer_provider = MyCustomTracerProvider.new
+    OpenTelemetry::Instrumentation.registry.install_all(config)
+  end
+end
+
+# The config option being passed to through to the registry install_all method.
+# This is not a valid configuration option for this instrumentation library
+# so the Opentelemetry logger will receive a warning message.
+config = { 'OpenTelemetry::Instrumentation::Net::HTTP' => { foo: 'bar' } }
+MyCustomSDK.configure(config)
+
+# The purpose of this line is to demonstrate that the instrumentation
+# library has received the SDK tracer and is not using the default
+# API noop tracer.
+puts OpenTelemetry::Instrumentation::Net::HTTP::Instrumentation.instance.tracer.inspect
+
+#### Output
+# Fetching gem metadata from https://rubygems.org/..
+# Resolving dependencies...
+# Using bundler 1.17.3
+# Using opentelemetry-api 0.16.0
+# Using opentelemetry-common 0.16.0
+# Using opentelemetry-instrumentation-base 0.16.0
+# Using opentelemetry-instrumentation-net_http 0.16.0
+# W, [2021-04-08T17:28:04.430002 #8425]  WARN -- : Instrumentation OpenTelemetry::Instrumentation::Net::HTTP ignored the following unknown configuration options [:foo]
+# I, [2021-04-08T17:28:04.430697 #8425]  INFO -- : Instrumentation: OpenTelemetry::Instrumentation::Net::HTTP was successfully installed
+# #<MyCustomTracer:0x00007faee43c6c58 @name="OpenTelemetry::Instrumentation::Net::HTTP", @version="0.16.0">
+```
+
+### For auto-instrumentation authors
+
+The following is a simplified demonstration of how the `OpenTelemetry::Instrumentation::Base` class can be used to hook into the instrumentation registry, and the basic functionality provided.
+
+```ruby
+# A simple class to instrument
+class SimpleClass
+  def greeting
+    puts "hello"
+  end
+end
+
+# Our instrumentation patch
+class SimplePatch
+  def greeting
+    tracer.in_span('SimpleClass#greeting') { super }
+  end
+
+  private
+
+  # We can gain access to the instrumentation tracer using
+  # the instance method available on the class inheriting
+  # from the instrumentation base.
+  def tracer
+    CustomAutoInstrumentation.instance.tracer
+  end
+end
+
+# The OpenTelemetry::Instrumentation::Base class will implicitly add
+# any class that inherits from it to the registry.
+# Note that the name of the instrumentation in the registry will match
+# the class name and its namespace.  In this example the registry
+# will contain 'CustomAutoInstrumentation', if it was within
+# a module named `Legacy`, it would take the form `Legacy::CustomAutoInstrumentation`.
+class CustomAutoInstrumentation < OpenTelemetry::Instrumentation::Base
+  # The install hook is provided to apply patches through prepending
+  # or using library hooks if available.
+  install do |_config|
+    patch
+  end
+
+  # The presence check provides a hook so that we can
+  # test for the presence of the class we intend to patch.
+  # If the presence check returns false, we will not
+  # proceed with the installation hook.
+  present do
+    defined?(SimpleClass)
+  end
+
+  private
+
+  def patch
+    SimpleClass.prepend(SimplePatch)
+  end
+end
+```
+
+## How can I get involved?
+
+The `opentelemetry-instrumentation-base` gem source is [on github][repo-github], along with related gems including `opentelemetry-api` and `opentelemetry-sdk`.
+
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+
+## License
+
+The `opentelemetry-instrumentation-base` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
+
+[bundler-home]: https://bundler.io
+[repo-github]: https://github.com/open-telemetry/opentelemetry-ruby
+[license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/main/LICENSE
+[ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
+[community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

data/lib/opentelemetry-instrumentation-base.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require_relative './opentelemetry/instrumentation'

data/lib/opentelemetry/instrumentation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry'
+require 'opentelemetry/instrumentation/registry'
+require 'opentelemetry/instrumentation/base'
+
+module OpenTelemetry
+  # The instrumentation module contains functionality to register and install
+  # instrumentation
+  module Instrumentation
+    extend self
+
+    # @return [Registry] registry containing all known
+    #  instrumentation
+    def registry
+      @registry ||= Registry.new
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/base.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    # The Base class holds all metadata and configuration for an
+    # instrumentation. All instrumentation packages should
+    # include a subclass of +Instrumentation::Base+ that will register
+    # it with +OpenTelemetry.instrumentation_registry+ and make it available for
+    # discovery and installation by an SDK.
+    #
+    # A typical subclass of Base will provide an install block, a present
+    # block, and possibly a compatible block. Below is an
+    # example:
+    #
+    # module OpenTelemetry
+    #   module Instrumentation
+    #     module Sinatra
+    #       class Instrumentation < OpenTelemetry::Instrumentation::Base
+    #         install do |config|
+    #           # install instrumentation, either by library hook or applying
+    #           # a monkey patch
+    #         end
+    #
+    #         # determine if the target library is present
+    #         present do
+    #           defined?(::Sinatra)
+    #         end
+    #
+    #         # if the target library is present, is it compatible?
+    #         compatible do
+    #           Gem.loaded_specs['sinatra'].version > MIN_VERSION
+    #         end
+    #       end
+    #     end
+    #   end
+    # end
+    #
+    # The instrumentation name and version will be inferred from the namespace of the
+    # class. In this example, they'd be 'OpenTelemetry::Instrumentation::Sinatra' and
+    # OpenTelemetry::Instrumentation::Sinatra::VERSION, but can be explicitly set using
+    # the +instrumentation_name+ and +instrumetation_version+ methods if necessary.
+    #
+    # All subclasses of OpenTelemetry::Instrumentation::Base are automatically
+    # registered with OpenTelemetry.instrumentation_registry which is used by
+    # SDKs for instrumentation discovery and installation.
+    #
+    # Instrumentation libraries can use the instrumentation subclass to easily gain
+    # a reference to its named tracer. For example:
+    #
+    # OpenTelemetry::Instrumentation::Sinatra.instance.tracer
+    #
+    # The instrumention class establishes a convention for disabling an instrumentation
+    # by environment variable and local configuration. An instrumentation disabled
+    # by environment variable will take precedence over local config. The
+    # convention for environment variable name is the library name, upcased with
+    # '::' replaced by underscores, OPENTELEMETRY shortened to OTEL_{LANG}, and '_ENABLED' appended.
+    # For example: OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED = false.
+    class Base # rubocop:disable Metrics/ClassLength
+      class << self
+        NAME_REGEX = /^(?:(?<namespace>[a-zA-Z0-9_:]+):{2})?(?<classname>[a-zA-Z0-9_]+)$/.freeze
+        VALIDATORS = {
+          array: ->(v) { v.is_a?(Array) },
+          boolean: ->(v) { v == true || v == false }, # rubocop:disable Style/MultipleComparison
+          callable: ->(v) { v.respond_to?(:call) },
+          integer: ->(v) { v.is_a?(Integer) },
+          string: ->(v) { v.is_a?(String) }
+        }.freeze
+
+        private_constant :NAME_REGEX, :VALIDATORS
+
+        private :new # rubocop:disable Style/AccessModifierDeclarations
+
+        def inherited(subclass)
+          OpenTelemetry::Instrumentation.registry.register(subclass)
+        end
+
+        # Optionally set the name of this instrumentation. If not
+        # explicitly set, the name will default to the namespace of the class,
+        # or the class name if it does not have a namespace. If there is not
+        # a namespace, or a class name, it will default to 'unknown'.
+        #
+        # @param [String] instrumentation_name The full name of the instrumentation package
+        def instrumentation_name(instrumentation_name = nil)
+          if instrumentation_name
+            @instrumentation_name = instrumentation_name
+          else
+            @instrumentation_name ||= infer_name || 'unknown'
+          end
+        end
+
+        # Optionally set the version of this instrumentation. If not explicitly set,
+        # the version will default to the VERSION constant under namespace of
+        # the class, or the VERSION constant under the class name if it does not
+        # have a namespace. If a VERSION constant cannot be found, it defaults
+        # to '0.0.0'.
+        #
+        # @param [String] instrumentation_version The version of the instrumentation package
+        def instrumentation_version(instrumentation_version = nil)
+          if instrumentation_version
+            @instrumentation_version = instrumentation_version
+          else
+            @instrumentation_version ||= infer_version || '0.0.0'
+          end
+        end
+
+        # The install block for this instrumentation. This will be where you install
+        # instrumentation, either by framework hook or applying a monkey patch.
+        #
+        # @param [Callable] blk The install block for this instrumentation
+        # @yieldparam [Hash] config The instrumentation config will be yielded to the
+        #   install block
+        def install(&blk)
+          @install_blk = blk
+        end
+
+        # The present block for this instrumentation. This block is used to detect if
+        # target library is present on the system. Typically this will involve
+        # checking to see if the target gem spec was loaded or if expected
+        # constants from the target library are present.
+        #
+        # @param [Callable] blk The present block for this instrumentation
+        def present(&blk)
+          @present_blk = blk
+        end
+
+        # The compatible block for this instrumentation. This check will be run if the
+        # target library is present to determine if it's compatible. It's not
+        # required, but a common use case will be to check to target library
+        # version for compatibility.
+        #
+        # @param [Callable] blk The compatibility block for this instrumentation
+        def compatible(&blk)
+          @compatible_blk = blk
+        end
+
+        # The option method is used to define default configuration options
+        # for the instrumentation library. It requires a name, default value,
+        # and a validation callable to be provided.
+        # @param [String] name The name of the configuration option
+        # @param default The default value to be used, or to used if validation fails
+        # @param [Callable, Symbol] validate Accepts a callable or a symbol that matches
+        # a key in the VALIDATORS hash.  The supported keys are, :array, :boolean,
+        # :callable, :integer, :string.
+        def option(name, default:, validate:)
+          validate = VALIDATORS[validate] || validate
+          raise ArgumentError, "validate must be #{VALIDATORS.keys.join(', ')}, or a callable" unless validate.respond_to?(:call)
+
+          @options ||= []
+          @options << { name: name, default: default, validate: validate }
+        end
+
+        def instance
+          @instance ||= new(instrumentation_name, instrumentation_version, install_blk,
+                            present_blk, compatible_blk, options)
+        end
+
+        private
+
+        attr_reader :install_blk, :present_blk, :compatible_blk, :options
+
+        def infer_name
+          @inferred_name ||= if (md = name.match(NAME_REGEX)) # rubocop:disable Naming/MemoizedInstanceVariableName
+                               md['namespace'] || md['classname']
+                             end
+        end
+
+        def infer_version
+          return unless (inferred_name = infer_name)
+
+          mod = inferred_name.split('::').map(&:to_sym).inject(Object) do |object, const|
+            object.const_get(const)
+          end
+          mod.const_get(:VERSION)
+        rescue NameError
+          nil
+        end
+      end
+
+      attr_reader :name, :version, :config, :installed, :tracer
+
+      alias installed? installed
+
+      def initialize(name, version, install_blk, present_blk,
+                     compatible_blk, options)
+        @name = name
+        @version = version
+        @install_blk = install_blk
+        @present_blk = present_blk
+        @compatible_blk = compatible_blk
+        @config = {}
+        @installed = false
+        @options = options
+        @tracer = OpenTelemetry::Trace::Tracer.new
+      end
+
+      # Install instrumentation with the given config. The present? and compatible?
+      # will be run first, and install will return false if either fail. Will
+      # return true if install was completed successfully.
+      #
+      # @param [Hash] config The config for this instrumentation
+      def install(config = {})
+        return true if installed?
+        return false unless installable?(config)
+
+        @config = config_options(config)
+        instance_exec(@config, &@install_blk)
+        @tracer = OpenTelemetry.tracer_provider.tracer(name, version)
+        @installed = true
+      end
+
+      # Whether or not this instrumentation is installable in the current process. Will
+      # be true when the instrumentation defines an install block, is not disabled
+      # by environment or config, and the target library present and compatible.
+      #
+      # @param [Hash] config The config for this instrumentation
+      def installable?(config = {})
+        @install_blk && enabled?(config) && present? && compatible?
+      end
+
+      # Calls the present block of the Instrumentation subclasses, if no block is provided
+      # it's assumed the instrumentation is not present
+      def present?
+        return false unless @present_blk
+
+        instance_exec(&@present_blk)
+      end
+
+      # Calls the compatible block of the Instrumentation subclasses, if no block is provided
+      # it's assumed to be compatible
+      def compatible?
+        return true unless @compatible_blk
+
+        instance_exec(&@compatible_blk)
+      end
+
+      # Whether this instrumentation is enabled. It first checks to see if it's enabled
+      # by an environment variable and will proceed to check if it's enabled
+      # by local config, if given.
+      #
+      # @param [optional Hash] config The local config
+      def enabled?(config = nil)
+        return false unless enabled_by_env_var?
+        return config[:enabled] if config&.key?(:enabled)
+
+        true
+      end
+
+      private
+
+      # The config_options method is responsible for validating that the user supplied
+      # config hash is valid.
+      # Unknown configuration keys are not included in the final config hash.
+      # Invalid configuration values are logged, and replaced by the default.
+      #
+      # @param [Hash] user_config The user supplied configuration hash
+      def config_options(user_config) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        @options ||= {}
+        user_config ||= {}
+        validated_config = @options.each_with_object({}) do |option, h|
+          option_name = option[:name]
+          config_value = user_config[option_name]
+
+          value = if config_value.nil?
+                    option[:default]
+                  elsif option[:validate].call(config_value)
+                    config_value
+                  else
+                    OpenTelemetry.logger.warn(
+                      "Instrumentation #{name} configuration option #{option_name} value=#{config_value} " \
+                      "failed validation, falling back to default value=#{option[:default]}"
+                    )
+                    option[:default]
+                  end
+
+          h[option_name] = value
+        rescue StandardError => e
+          OpenTelemetry.handle_error(exception: e, message: "Instrumentation #{name} unexpected configuration error")
+          h[option_name] = option[:default]
+        end
+
+        dropped_config_keys = user_config.keys - validated_config.keys
+        OpenTelemetry.logger.warn("Instrumentation #{name} ignored the following unknown configuration options #{dropped_config_keys}") unless dropped_config_keys.empty?
+
+        validated_config
+      end
+
+      # Checks to see if this instrumentation is enabled by env var. By convention, the
+      # environment variable will be the instrumentation name upper cased, with '::'
+      # replaced by underscores, OPENTELEMETRY shortened to OTEL_{LANG} and _ENABLED appended.
+      # For example, the, environment variable name for OpenTelemetry::Instrumentation::Sinatra
+      # will be OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED. A value of 'false' will disable
+      # the instrumentation, all other values will enable it.
+      def enabled_by_env_var?
+        var_name = name.dup.tap do |n|
+          n.upcase!
+          n.gsub!('::', '_')
+          n.gsub!('OPENTELEMETRY_', 'OTEL_RUBY_')
+          n << '_ENABLED'
+        end
+        ENV[var_name] != 'false'
+      end
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/registry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    # The instrumentation Registry contains information about instrumentation
+    # available and facilitates discovery, installation and
+    # configuration. This functionality is primarily useful for SDK
+    # implementors.
+    class Registry
+      def initialize
+        @lock = Mutex.new
+        @instrumentation = []
+      end
+
+      # @api private
+      def register(instrumentation)
+        @lock.synchronize do
+          @instrumentation << instrumentation
+        end
+      end
+
+      # Lookup an instrumentation definition by name. Returns nil if +instrumentation_name+
+      # is not found.
+      #
+      # @param [String] instrumentation_name A stringified class name for an instrumentation
+      # @return [Instrumentation]
+      def lookup(instrumentation_name)
+        @lock.synchronize do
+          find_instrumentation(instrumentation_name)
+        end
+      end
+
+      # Install the specified instrumentation with optionally specified configuration.
+      #
+      # @param [Array<String>] instrumentation_names An array of instrumentation names to
+      #   install
+      # @param [optional Hash<String, Hash>] instrumentation_config_map A map of
+      #   instrumentation_name to config. This argument is optional and config can be
+      #   passed for as many or as few instrumentations as desired.
+      def install(instrumentation_names, instrumentation_config_map = {})
+        @lock.synchronize do
+          instrumentation_names.each do |instrumentation_name|
+            instrumentation = find_instrumentation(instrumentation_name)
+            OpenTelemetry.logger.warn "Could not install #{instrumentation_name} because it was not found" unless instrumentation
+
+            install_instrumentation(instrumentation, instrumentation_config_map[instrumentation.name])
+          end
+        end
+      end
+
+      # Install all instrumentation available and installable in this process.
+      #
+      # @param [optional Hash<String, Hash>] instrumentation_config_map A map of
+      #   instrumentation_name to config. This argument is optional and config can be
+      #   passed for as many or as few instrumentations as desired.
+      def install_all(instrumentation_config_map = {})
+        @lock.synchronize do
+          @instrumentation.map(&:instance).each do |instrumentation|
+            install_instrumentation(instrumentation, instrumentation_config_map[instrumentation.name])
+          end
+        end
+      end
+
+      private
+
+      def find_instrumentation(instrumentation_name)
+        @instrumentation.detect { |a| a.instance.name == instrumentation_name }
+                   &.instance
+      end
+
+      def install_instrumentation(instrumentation, config)
+        if instrumentation.install(config)
+          OpenTelemetry.logger.info "Instrumentation: #{instrumentation.name} was successfully installed"
+        else
+          OpenTelemetry.logger.warn "Instrumentation: #{instrumentation.name} failed to install"
+        end
+      rescue => e # rubocop:disable Style/RescueStandardError
+        OpenTelemetry.handle_error(exception: e, message: "Instrumentation: #{instrumentation.name} unhandled exception during install: #{e.backtrace}")
+      end
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    VERSION = '0.17.0'
+  end
+end

metadata

@@ -0,0 +1,168 @@
+--- !ruby/object:Gem::Specification
+name: opentelemetry-instrumentation-base
+version: !ruby/object:Gem::Version
+  version: 0.17.0
+platform: ruby
+authors:
+- OpenTelemetry Authors
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.17.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.17.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 12.3.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 12.3.3
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.73.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.73.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.17.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.17.1
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: yard-doctest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.6
+description: Instrumentation Base for the OpenTelemetry framework
+email:
+- cncf-opentelemetry-contributors@lists.cncf.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/opentelemetry-instrumentation-base.rb
+- lib/opentelemetry/instrumentation.rb
+- lib/opentelemetry/instrumentation/base.rb
+- lib/opentelemetry/instrumentation/registry.rb
+- lib/opentelemetry/instrumentation/version.rb
+homepage: https://github.com/open-telemetry/opentelemetry-ruby
+licenses:
+- Apache-2.0
+metadata:
+  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-instrumentation-base/v0.17.0/file.CHANGELOG.html
+  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/instrumentation/base
+  bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
+  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-instrumentation-base/v0.17.0
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Instrumentation Base for the OpenTelemetry framework
+test_files: []