opentelemetry-api 0.2.0 → 0.6.0

data/lib/opentelemetry/instrumentation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/instrumentation/registry'
+require 'opentelemetry/instrumentation/base'
+
+module OpenTelemetry
+  # The instrumentation module contains functionality to register and install
+  # instrumentation
+  module Instrumentation
+  end
+end

data/lib/opentelemetry/instrumentation/base.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+# Copyright 2020 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
+      class << self
+        NAME_REGEX = /^(?:(?<namespace>[a-zA-Z0-9_:]+):{2})?(?<classname>[a-zA-Z0-9_]+)$/.freeze
+        private_constant :NAME_REGEX
+
+        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
+
+        def instance
+          @instance ||= new(instrumentation_name, instrumentation_version, install_blk,
+                            present_blk, compatible_blk)
+        end
+
+        private
+
+        attr_reader :install_blk, :present_blk, :compatible_blk
+
+        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)
+        @name = name
+        @version = version
+        @install_blk = install_blk
+        @present_blk = present_blk
+        @compatible_blk = compatible_blk
+        @config = {}
+        @installed = false
+      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 unless config.nil?
+        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
+
+      # 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,87 @@
+# frozen_string_literal: true
+
+# Copyright 2020 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.logger.warn "Instrumentation: #{instrumentation.name} unhandled exception" \
+                                  "during install #{e}: #{e.backtrace}"
+      end
+    end
+  end
+end

data/lib/opentelemetry/metrics.rb

@@ -7,7 +7,7 @@
 require 'opentelemetry/metrics/handles'
 require 'opentelemetry/metrics/instruments'
 require 'opentelemetry/metrics/meter'
-require 'opentelemetry/metrics/meter_factory'
+require 'opentelemetry/metrics/meter_provider'
 
 module OpenTelemetry
   # The Metrics API allows reporting raw measurements as well as metrics with known aggregation and labels.

data/lib/opentelemetry/metrics/handles.rb

@@ -7,29 +7,19 @@
 module OpenTelemetry
   module Metrics
     # In situations where performance is a requirement and a metric is
-    # repeatedly used with the same set of labels, the developer may elect to
+    # repeatedly used with the same labels, the developer may elect to
     # use instrument {Handles} as an optimization. For handles to be a benefit,
     # it requires that a specific instrument will be re-used with specific
-    # labels. If an instrument will be used with the same label set more than
-    # once, obtaining an instrument handle corresponding to the label set
+    # labels. If an instrument will be used with the same labels more than
+    # once, obtaining an instrument handle corresponding to the labels
     # ensures the highest performance available.
     #
-    # To obtain a handle given an instrument and label set, use the  #handle
-    # method to return an interface that supports the #add, #set, or #record
+    # To obtain a handle given an instrument and labels, use the  #handle
+    # method to return an interface that supports the #add or #record
     # method of the instrument in question.
     #
     # Instrument handles may consume SDK resources indefinitely.
     module Handles
-      # A float gauge handle.
-      class FloatGauge
-        def set(value); end
-      end
-
-      # An integer gauge handle.
-      class IntegerGauge
-        def set(value); end
-      end
-
       # A float counter handle.
       class FloatCounter
         def add(value); end

data/lib/opentelemetry/metrics/instruments.rb

@@ -13,67 +13,19 @@ module OpenTelemetry
     # program to record observations about their behavior. Therefore, we use
     # "metric instrument" to refer to a program object, allocated through the
     # API, used for recording metrics. There are three distinct instruments in
-    # the Metrics API, commonly known as Counters, Gauges, and Measures.
+    # the Metrics API, commonly known as Counters, Observers, and Measures.
     module Instruments
-      # A float gauge instrument.
-      class FloatGauge
-        # Set the value of the gauge.
-        #
-        # @param [Float] value The value to set.
-        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
-        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
-        def set(value, labels_or_label_set = {}); end
-
-        # Obtain a handle from the instrument and label set.
-        #
-        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
-        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
-        # @return [Handles::FloatGauge]
-        def handle(labels_or_label_set = {})
-          Handles::FloatGauge.new
-        end
-
-        # Return a measurement to be recorded via {Meter#record_batch}.
-        #
-        # @param [Float] value
-        # @return [Object, Measurement]
-        def measurement(value)
-          NOOP_MEASUREMENT
-        end
-      end
-
-      # An integer gauge instrument.
-      class IntegerGauge
-        def set(value, labels_or_label_set = {}); end
-
-        # Obtain a handle from the instrument and label set.
-        #
-        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
-        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
-        # @return [Handles::IntegerGauge]
-        def handle(labels_or_label_set = {})
-          Handles::IntegerGauge.new
-        end
-
-        # Return a measurement to be recorded via {Meter#record_batch}.
-        #
-        # @param [Integer] value
-        # @return [Object, Measurement]
-        def measurement(value)
-          NOOP_MEASUREMENT
-        end
-      end
+      # TODO: Observers.
 
       # A float counter instrument.
       class FloatCounter
-        def add(value, labels_or_label_set = {}); end
+        def add(value, labels = {}); end
 
-        # Obtain a handle from the instrument and label set.
+        # Obtain a handle from the instrument and labels.
         #
-        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
-        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @param [optional Hash<String, String>] labels A Hash of Strings.
         # @return [Handles::FloatCounter]
-        def handle(labels_or_label_set = {})
+        def handle(labels = {})
           Handles::FloatCounter.new
         end
 
@@ -88,14 +40,13 @@ module OpenTelemetry
 
       # An integer counter instrument.
       class IntegerCounter
-        def add(value, labels_or_label_set = {}); end
+        def add(value, labels = {}); end
 
-        # Obtain a handle from the instrument and label set.
+        # Obtain a handle from the instrument and labels.
         #
-        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
-        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @param [optional Hash<String, String>] labels A Hash of Strings.
         # @return [Handles::IntegerCounter]
-        def handle(labels_or_label_set = {})
+        def handle(labels = {})
           Handles::IntegerCounter.new
         end
 
@@ -110,14 +61,13 @@ module OpenTelemetry
 
       # A float measure instrument.
       class FloatMeasure
-        def record(value, labels_or_label_set = {}); end
+        def record(value, labels = {}); end
 
-        # Obtain a handle from the instrument and label set.
+        # Obtain a handle from the instrument and labels.
         #
-        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
-        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @param [optional Hash<String, String>] labels A Hash of Strings.
         # @return [Handles::FloatMeasure]
-        def handle(labels_or_label_set = {})
+        def handle(labels = {})
           Handles::FloatMeasure.new
         end
 
@@ -132,14 +82,13 @@ module OpenTelemetry
 
       # An integer measure instrument.
       class IntegerMeasure
-        def record(value, labels_or_label_set = {}); end
+        def record(value, labels = {}); end
 
-        # Obtain a handle from the instrument and label set.
+        # Obtain a handle from the instrument and labels.
         #
-        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
-        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @param [optional Hash<String, String>] labels A Hash of Strings.
         # @return [Handles::IntegerMeasure]
-        def handle(labels_or_label_set = {})
+        def handle(labels = {})
           Handles::IntegerMeasure.new
         end