opentelemetry-api 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23c4a8602afe2513fff72ec29784b696ae41eccee8c3b25eb4cf48081856b22b
-  data.tar.gz: 17507ad2d0dbb697e6f1bb8cbf133d0baa01234d7383d9bb726b0d5fb11c4cb3
+  metadata.gz: d9a70b684347cdc76e7cc5654e09ad01eb406cb415006b8f9418ff5c421521cf
+  data.tar.gz: 818b8c0cd95656898d0ce0eb4cf44d5fcc15ad7dd86e88b43b8aa1dc920dc05d
 SHA512:
-  metadata.gz: 5c37bb2d8a469bda44a121bfca1218380553cbc66d24e8001df4c2e67d93f9b474335962095b77a28e6de3c53f34af98ea18b12a3335cdd45d0b04d50510b2be
-  data.tar.gz: 3980934cdfdb34e96eb8215a9ebb26eb0b3d096be3e545837ee9d6595ff5e114ea680e692ccc7d0af2d89d8a4550e180671e4d92c5266b6a445c45fc991e0602
+  metadata.gz: 3823e1d3a42b7cf8fcab40b5d2eb42f1fa312639175f8b57fef4ea5452451d8b358439424dc8da1825dbbb61e38c9a987c5996144d927bf6cb883a38f9dbaba0
+  data.tar.gz: 24365bbb7500da52d4b07ae1a54996d86a4ee98db465f15fe9b93aef4d6911ca072b1f48b1c1977351f0326607c271536b2b2b1df98b4831c70912be5adf0e65

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History: opentelemetry-api
 
+### v0.15.0 / 2021-02-18
+
+* ADDED: Add instrumentation config validation 
+* DOCS: Clarify nil attribute values not allowed 
+
 ### v0.14.0 / 2021-02-03
 
 * BREAKING CHANGE: Replace getter and setter callables and remove rack specific propagators 

data/lib/opentelemetry/instrumentation/base.rb

@@ -59,10 +59,18 @@ module OpenTelemetry
     # 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 Base # rubocop:disable Metrics/ClassLength
       class << self
         NAME_REGEX = /^(?:(?<namespace>[a-zA-Z0-9_:]+):{2})?(?<classname>[a-zA-Z0-9_]+)$/.freeze
-        private_constant :NAME_REGEX
+        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
 
@@ -129,14 +137,30 @@ module OpenTelemetry
           @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)
+                            present_blk, compatible_blk, options)
         end
 
         private
 
-        attr_reader :install_blk, :present_blk, :compatible_blk
+        attr_reader :install_blk, :present_blk, :compatible_blk, :options
 
         def infer_name
           @inferred_name ||= if (md = name.match(NAME_REGEX)) # rubocop:disable Naming/MemoizedInstanceVariableName
@@ -161,7 +185,7 @@ module OpenTelemetry
       alias installed? installed
 
       def initialize(name, version, install_blk, present_blk,
-                     compatible_blk)
+                     compatible_blk, options)
         @name = name
         @version = version
         @install_blk = install_blk
@@ -169,6 +193,7 @@ module OpenTelemetry
         @compatible_blk = compatible_blk
         @config = {}
         @installed = false
+        @options = options
       end
 
       # Install instrumentation with the given config. The present? and compatible?
@@ -180,7 +205,7 @@ module OpenTelemetry
         return true if installed?
         return false unless installable?(config)
 
-        @config = config unless config.nil?
+        @config = config_options(config)
         instance_exec(@config, &@install_blk)
         @tracer ||= OpenTelemetry.tracer_provider.tracer(name, version)
         @installed = true
@@ -225,6 +250,43 @@ module OpenTelemetry
 
       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.

data/lib/opentelemetry/trace/span.rb

@@ -51,6 +51,9 @@ module OpenTelemetry
       #
       # @param [String] key
       # @param [String, Boolean, Numeric, Array<String, Numeric, Boolean>] value
+      #   Values must be non-nil and (array of) string, boolean or numeric type.
+      #   Array values must not contain nil elements and all elements must be of
+      #   the same basic type (string, numeric, boolean).
       #
       # @return [self] returns itself
       def set_attribute(key, value)

data/lib/opentelemetry/version.rb

@@ -6,5 +6,5 @@
 
 module OpenTelemetry
   ## Current OpenTelemetry version
-  VERSION = '0.14.0'
+  VERSION = '0.15.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-api
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-03 00:00:00.000000000 Z
+date: 2021-02-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ipsa
@@ -196,10 +196,10 @@ homepage: https://github.com/open-telemetry/opentelemetry-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.14.0/file.CHANGELOG.html
+  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.15.0/file.CHANGELOG.html
   source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/api
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
-  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.14.0
+  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.15.0
 post_install_message: 
 rdoc_options: []
 require_paths: