opentelemetry-api 0.12.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7c58fd79dce24997ec350919d59c831940d6604acea611b2a0be72177f0b692
-  data.tar.gz: a0c08af587e1002da839ff0f4d9860f528256fbb3dbba3b885c0494f06c71b95
+  metadata.gz: 2044ecfc3776d70aa668bcbd537f9df904f3a48a19b3b1daa67d0632686b3358
+  data.tar.gz: 996749298853bb15d62cadff700e06a1f3bcb505f5b49786b713c1daa1796165
 SHA512:
-  metadata.gz: 3988fc0200883dadf62a8623d6c727d032c6648c2bc4e860cac0e3f7ae3e8bacc6a0c8a05638272cbf24d254cfaf3723bfdb2564e306bb99e029d1f88860d5d4
-  data.tar.gz: 183d0203693f3585a153992582aee24e7df9ce3afc66ba536dd3dcfc7295ca00226b3cb02f468fa9ce17fce2dc6b5a54523c5cfba4b79c87d8f879255d6a34e1
+  metadata.gz: 12c9863e4b90e34f5b4d6e2e3e5b97244d609e5381d554b39d461e77cfff5e7f8130b1389c68743d6fb7ea3080321aa4b12dc56e3ca78cac20fda1cc0100e7b7
+  data.tar.gz: 990f49fa7ef5e2990283cf4b42af9a6ecaa4989078a7b084568806675a9a2d3ae635bb830bccc9626b51869e3f0bfc9df5406f2cdbfda6c33576e4fd92c26716

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Release History: opentelemetry-api
 
+### v0.16.0 / 2021-03-17
+
+* ADDED: Span#add_attributes 
+* FIXED: Handle rack env getter edge cases 
+* DOCS: Replace Gitter with GitHub Discussions 
+
+### 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 
+
+* ADDED: Replace getter and setter callables and remove rack specific propagators 
+
+### v0.13.0 / 2021-01-29
+
+* ADDED: Add optional attributes to record_exception 
+* FIXED: Small test fixes. 
+
+### v0.12.1 / 2021-01-13
+
+* FIXED: Eliminate warning about Random::DEFAULT on Ruby 3.0 
+
 ### v0.12.0 / 2020-12-24
 
 * ADDED: Structured error handling 

data/README.md

@@ -49,7 +49,7 @@ For additional examples, see the [examples on github][examples-github].
 
 The `opentelemetry-api` gem source is [on github][repo-github], along with related gems including `opentelemetry-sdk`.
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [gitter channel][ruby-gitter] 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].
+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
 
@@ -59,8 +59,8 @@ The `opentelemetry-api` gem is distributed under the Apache 2.0 license. See [LI
 [opentelemetry-home]: https://opentelemetry.io
 [bundler-home]: https://bundler.io
 [repo-github]: https://github.com/open-telemetry/opentelemetry-ruby
-[license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/master/LICENSE
-[examples-github]: https://github.com/open-telemetry/opentelemetry-ruby/tree/master/examples
+[license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/main/LICENSE
+[examples-github]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
-[ruby-gitter]: https://gitter.im/open-telemetry/opentelemetry-ruby
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

data/lib/opentelemetry.rb

@@ -22,7 +22,8 @@ require 'opentelemetry/version'
 module OpenTelemetry
   extend self
 
-  attr_writer :tracer_provider, :meter_provider, :baggage, :logger, :error_handler
+  attr_writer :tracer_provider, :meter_provider, :propagation, :baggage,
+              :logger, :error_handler
 
   # @return [Object, Logger] configured Logger or a default STDOUT Logger.
   def logger
@@ -68,8 +69,11 @@ module OpenTelemetry
     @baggage ||= Baggage::Manager.new
   end
 
-  # @return [Context::Propagation::Propagation] an instance of the propagation API
+  # @return [Context::Propagation::Propagator] a propagator instance
   def propagation
-    @propagation ||= Context::Propagation::Propagation.new
+    @propagation ||= Context::Propagation::Propagator.new(
+      Context::Propagation::NoopInjector.new,
+      Context::Propagation::NoopExtractor.new
+    )
   end
 end

data/lib/opentelemetry/baggage/propagation.rb

@@ -15,17 +15,11 @@ module OpenTelemetry
     module Propagation
       extend self
 
+      BAGGAGE_KEY = 'baggage'
       TEXT_MAP_EXTRACTOR = TextMapExtractor.new
       TEXT_MAP_INJECTOR = TextMapInjector.new
-      RACK_EXTRACTOR = TextMapExtractor.new(
-        baggage_key: 'HTTP_BAGGAGE'
-      )
-      RACK_INJECTOR = TextMapInjector.new(
-        baggage_key: 'HTTP_BAGGAGE'
-      )
 
-      private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR, :RACK_INJECTOR,
-                       :RACK_EXTRACTOR
+      private_constant :BAGGAGE_KEY, :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR
 
       # Returns an extractor that extracts context using the W3C Baggage
       # format
@@ -38,20 +32,6 @@ module OpenTelemetry
       def text_map_extractor
         TEXT_MAP_EXTRACTOR
       end
-
-      # Returns an extractor that extracts context using the W3C Baggage
-      # format with Rack normalized keys (upcased and prefixed with
-      # HTTP_)
-      def rack_injector
-        RACK_INJECTOR
-      end
-
-      # Returns an injector that injects context using the W3C Baggage
-      # format with Rack normalized keys (upcased and prefixed with
-      # HTTP_)
-      def rack_extractor
-        RACK_EXTRACTOR
-      end
     end
   end
 end

data/lib/opentelemetry/baggage/propagation/text_map_extractor.rb

@@ -11,16 +11,15 @@ module OpenTelemetry
     module Propagation
       # Extracts baggage from carriers in the W3C Baggage format
       class TextMapExtractor
-        include Context::Propagation::DefaultGetter
-
         # Returns a new TextMapExtractor that extracts context using the specified
-        # header key
+        # getter
         #
-        # @param [String] baggage_key The baggage header
-        #   key used in the carrier
+        # @param [optional Getter] default_getter The default getter used to read
+        #   headers from a carrier during extract. Defaults to a
+        #   {OpenTelemetry::Context::Propagation::TextMapGetter} instance.
         # @return [TextMapExtractor]
-        def initialize(baggage_key: 'baggage')
-          @baggage_key = baggage_key
+        def initialize(default_getter = Context::Propagation.text_map_getter)
+          @default_getter = default_getter
         end
 
         # Extract remote baggage from the supplied carrier.
@@ -28,16 +27,14 @@ module OpenTelemetry
         #
         # @param [Carrier] carrier The carrier to get the header from
         # @param [Context] context The context to be updated with extracted baggage
-        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
-        #   returns the value associated with the key. If omitted the default getter will be used
-        #   which expects the carrier to respond to [] and []=.
-        # @yield [Carrier, String] if an optional getter is provided, extract will yield the carrier
-        #   and the header key to the getter.
+        # @param [optional Getter] getter If the optional getter is provided, it
+        #   will be used to read the header from the carrier, otherwise the default
+        #   getter will be used.
         # @return [Context] context updated with extracted baggage, or the original context
         #   if extraction fails
-        def extract(carrier, context, &getter)
-          getter ||= default_getter
-          header = getter.call(carrier, @baggage_key)
+        def extract(carrier, context, getter = nil)
+          getter ||= @default_getter
+          header = getter.get(carrier, BAGGAGE_KEY)
 
           entries = header.gsub(/\s/, '').split(',')
 

data/lib/opentelemetry/baggage/propagation/text_map_injector.rb

@@ -11,33 +11,30 @@ module OpenTelemetry
     module Propagation
       # Injects baggage using the W3C Baggage format
       class TextMapInjector
-        include Context::Propagation::DefaultSetter
-
         # Returns a new TextMapInjector that injects context using the specified
-        # header key
+        # setter
         #
-        # @param [String] baggage_key The baggage header
-        #   key used in the carrier
+        # @param [optional Setter] default_setter The default setter used to
+        #   write context into a carrier during inject. Defaults to a
+        #   {OpenTelemetry::Context::Propagation::TextMapSetter} instance.
         # @return [TextMapInjector]
-        def initialize(baggage_key: 'baggage')
-          @baggage_key = baggage_key
+        def initialize(default_setter = Context::Propagation.text_map_setter)
+          @default_setter = default_setter
         end
 
         # Inject in-process baggage into the supplied carrier.
         #
         # @param [Carrier] carrier The carrier to inject baggage into
         # @param [Context] context The context to read baggage from
-        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
-        #   returns the value associated with the key. If omitted the default getter will be used
-        #   which expects the carrier to respond to [] and []=.
-        # @yield [Carrier, String] if an optional getter is provided, inject will yield the carrier
-        #   and the header key to the getter.
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   setter will be used.
         # @return [Object] carrier with injected baggage
-        def inject(carrier, context, &setter)
+        def inject(carrier, context, setter = nil)
           return carrier unless (baggage = context[ContextKeys.baggage_key]) && !baggage.empty?
 
-          setter ||= default_setter
-          setter.call(carrier, @baggage_key, encode(baggage))
+          setter ||= @default_setter
+          setter.set(carrier, BAGGAGE_KEY, encode(baggage))
 
           carrier
         end

data/lib/opentelemetry/context/propagation.rb

@@ -5,18 +5,43 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require 'opentelemetry/context/propagation/composite_propagator'
-require 'opentelemetry/context/propagation/default_getter'
-require 'opentelemetry/context/propagation/default_setter'
 require 'opentelemetry/context/propagation/noop_extractor'
 require 'opentelemetry/context/propagation/noop_injector'
-require 'opentelemetry/context/propagation/propagation'
 require 'opentelemetry/context/propagation/propagator'
+require 'opentelemetry/context/propagation/text_map_getter'
+require 'opentelemetry/context/propagation/text_map_setter'
+require 'opentelemetry/context/propagation/rack_env_getter'
 
 module OpenTelemetry
   class Context
     # The propagation module contains APIs and utilities to interact with context
     # and propagate across process boundaries.
     module Propagation
+      extend self
+
+      TEXT_MAP_GETTER = TextMapGetter.new
+      TEXT_MAP_SETTER = TextMapSetter.new
+      RACK_ENV_GETTER = RackEnvGetter.new
+
+      private_constant :TEXT_MAP_GETTER, :TEXT_MAP_SETTER, :RACK_ENV_GETTER
+
+      # Returns a {TextMapGetter} instance suitable for reading values from a
+      # hash-like carrier
+      def text_map_getter
+        TEXT_MAP_GETTER
+      end
+
+      # Returns a {TextMapSetter} instance suitable for writing values into a
+      # hash-like carrier
+      def text_map_setter
+        TEXT_MAP_SETTER
+      end
+
+      # Returns a {RackEnvGetter} instance suitable for reading values from a
+      # Rack environment.
+      def rack_env_getter
+        RACK_ENV_GETTER
+      end
     end
   end
 end

data/lib/opentelemetry/context/propagation/composite_propagator.rb

@@ -30,15 +30,14 @@ module OpenTelemetry
         #   context into
         # @param [optional Context] context Context to be injected into carrier.
         #   Defaults to +Context.current+
-        # @param [optional Callable] setter An optional callable that takes a
-        #   carrier, a key and a value and assigns the key-value pair in the
-        #   carrier. If omitted the default setter will be used which expects
-        #   the carrier to respond to [] and []=.
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   setter will be used.
         #
         # @return [Object] carrier
-        def inject(carrier, context = Context.current, &setter)
+        def inject(carrier, context: Context.current, setter: Context::Propagation.text_map_setter)
           @injectors.inject(carrier) do |memo, injector|
-            injector.inject(memo, context, &setter)
+            injector.inject(memo, context, setter)
           rescue => e # rubocop:disable Style/RescueStandardError
             OpenTelemetry.logger.warn "Error in CompositePropagator#inject #{e.message}"
             carrier
@@ -53,15 +52,15 @@ module OpenTelemetry
         # @param [Object] carrier The carrier to extract context from
         # @param [optional Context] context Context to be updated with the state
         #   extracted from the carrier. Defaults to +Context.current+
-        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
-        #   returns the value associated with the key. If omitted the default getter will be used
-        #   which expects the carrier to respond to [] and []=.
+        # @param [optional Getter] getter If the optional getter is provided, it
+        #   will be used to read the header from the carrier, otherwise the default
+        #   getter will be used.
         #
         # @return [Context] a new context updated with state extracted from the
         #   carrier
-        def extract(carrier, context = Context.current, &getter)
+        def extract(carrier, context: Context.current, getter: Context::Propagation.text_map_getter)
           @extractors.inject(context) do |ctx, extractor|
-            extractor.extract(carrier, ctx, &getter)
+            extractor.extract(carrier, ctx, getter)
           rescue => e # rubocop:disable Style/RescueStandardError
             OpenTelemetry.logger.warn "Error in CompositePropagator#extract #{e.message}"
             ctx

data/lib/opentelemetry/context/propagation/noop_extractor.rb

@@ -17,7 +17,7 @@ module OpenTelemetry
         # @param [optional Callable] getter An optional callable that takes a carrier and a key and
         #   and returns the value associated with the key
         # @return [Context]
-        def extract(carrier, context, &getter)
+        def extract(carrier, context, getter = nil)
           context
         end
       end

data/lib/opentelemetry/context/propagation/propagator.rb

@@ -28,13 +28,13 @@ module OpenTelemetry
         #   context into
         # @param [optional Context] context Context to be injected into carrier. Defaults
         #   to +Context.current+
-        # @param [optional Callable] setter An optional callable that takes a carrier, a key and
-        #   a value and assigns the key-value pair in the carrier. If omitted the default setter
-        #   will be used which expects the carrier to respond to [] and []=.
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   setter will be used.
         #
         # @return [Object] carrier
-        def inject(carrier, context = Context.current, &setter)
-          @injector.inject(carrier, context, &setter)
+        def inject(carrier, context: Context.current, setter: Context::Propagation.text_map_setter)
+          @injector.inject(carrier, context, setter)
         rescue => e # rubocop:disable Style/RescueStandardError
           OpenTelemetry.logger.warn "Error in Propagator#inject #{e.message}"
           carrier
@@ -46,14 +46,14 @@ module OpenTelemetry
         # @param [Object] carrier The carrier to extract context from
         # @param [optional Context] context Context to be updated with the state
         #   extracted from the carrier. Defaults to +Context.current+
-        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
-        #   returns the value associated with the key. If omitted the default getter will be used
-        #   which expects the carrier to respond to [] and []=.
+        # @param [optional Getter] getter If the optional getter is provided, it
+        #   will be used to read the header from the carrier, otherwise the default
+        #   getter will be used.
         #
         # @return [Context] a new context updated with state extracted from the
         #   carrier
-        def extract(carrier, context = Context.current, &getter)
-          @extractor.extract(carrier, context, &getter)
+        def extract(carrier, context: Context.current, getter: Context::Propagation.text_map_getter)
+          @extractor.extract(carrier, context, getter)
         rescue => e # rubocop:disable Style/RescueStandardError
           OpenTelemetry.logger.warn "Error in Propagator#extract #{e.message}"
           context

data/lib/opentelemetry/context/propagation/rack_env_getter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # The RackEnvGetter class provides a common methods for reading
+      # keys from a rack environment. It abstracts away the rack-normalization
+      # process so that keys can be looked up without having to transform them
+      # first. With this class you can get +traceparent+ instead of
+      # +HTTP_TRACEPARENT+
+      class RackEnvGetter
+        # Converts key into a rack-normalized key and reads it from the carrier.
+        # Useful for extract operations.
+        def get(carrier, key)
+          carrier[to_rack_key(key)] || carrier[key]
+        end
+
+        # Reads all keys from a carrier and converts them from the rack-normalized
+        # form to the original. The resulting keys will be lowercase and
+        # underscores will be replaced with dashes.
+        def keys(carrier)
+          carrier.keys.map(&method(:from_rack_key))
+        end
+
+        private
+
+        def to_rack_key(key)
+          ret = 'HTTP_' + key
+          ret.tr!('-', '_')
+          ret.upcase!
+          ret
+        end
+
+        def from_rack_key(key)
+          start = key.start_with?('HTTP_') ? 5 : 0
+          ret = key[start..-1]
+          ret.tr!('_', '-')
+          ret.downcase!
+          ret
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/context/propagation/text_map_getter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # The default getter module provides a common methods for reading
+      # key from a carrier that implements +[]+ and a +keys+ method
+      class TextMapGetter
+        # Reads a key from a carrier that implements +[]+. Useful for extract
+        # operations.
+        def get(carrier, key)
+          carrier[key]
+        end
+
+        # Reads all keys from a carrier. Useful for iterating over a carrier's
+        # keys.
+        def keys(carrier)
+          carrier.keys
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/context/propagation/text_map_setter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # The default setter module provides a common method for writing
+      # a key into a carrier that implements +[]=+
+      class TextMapSetter
+        # Writes key into a carrier that implements +[]=+. Useful for inject
+        # operations.
+        def set(carrier, key, value)
+          carrier[key] = value
+        end
+      end
+    end
+  end
+end

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.rb

@@ -13,7 +13,17 @@ module OpenTelemetry
 
     CURRENT_SPAN_KEY = Context.create_key('current-span')
 
-    private_constant :CURRENT_SPAN_KEY
+    # Random number generator for generating IDs. This is an object that can
+    # respond to `#bytes` and uses the system PRNG. The current logic is
+    # compatible with Ruby 2.5 (which does not implement the `Random.bytes`
+    # class method) and with Ruby 3.0+ (which deprecates `Random::DEFAULT`).
+    # When we drop support for Ruby 2.5, this can simply be replaced with
+    # the class `Random`.
+    #
+    # @return [#bytes]
+    RANDOM = Random.respond_to?(:bytes) ? Random : Random::DEFAULT
+
+    private_constant :CURRENT_SPAN_KEY, :RANDOM
 
     # An invalid trace identifier, a 16-byte string with all zero bytes.
     INVALID_TRACE_ID = ("\0" * 16).b
@@ -27,7 +37,7 @@ module OpenTelemetry
     # @return [String] a valid trace ID.
     def generate_trace_id
       loop do
-        id = Random::DEFAULT.bytes(16)
+        id = RANDOM.bytes(16)
         return id unless id == INVALID_TRACE_ID
       end
     end
@@ -38,7 +48,7 @@ module OpenTelemetry
     # @return [String] a valid span ID.
     def generate_span_id
       loop do
-        id = Random::DEFAULT.bytes(8)
+        id = RANDOM.bytes(8)
         return id unless id == INVALID_SPAN_ID
       end
     end

data/lib/opentelemetry/trace/propagation/trace_context.rb

@@ -15,20 +15,13 @@ module OpenTelemetry
       # for context propagation in the W3C Trace Context format.
       module TraceContext
         extend self
-
+        TRACEPARENT_KEY = 'traceparent'
+        TRACESTATE_KEY = 'tracestate'
         TEXT_MAP_EXTRACTOR = TextMapExtractor.new
         TEXT_MAP_INJECTOR = TextMapInjector.new
-        RACK_EXTRACTOR = TextMapExtractor.new(
-          traceparent_key: 'HTTP_TRACEPARENT',
-          tracestate_key: 'HTTP_TRACESTATE'
-        )
-        RACK_INJECTOR = TextMapInjector.new(
-          traceparent_key: 'HTTP_TRACEPARENT',
-          tracestate_key: 'HTTP_TRACESTATE'
-        )
 
-        private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR,
-                         :RACK_INJECTOR, :RACK_EXTRACTOR
+        private_constant :TRACEPARENT_KEY, :TRACESTATE_KEY,
+                         :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR
 
         # Returns an extractor that extracts context using the W3C Trace Context
         # format
@@ -41,18 +34,6 @@ module OpenTelemetry
         def text_map_injector
           TEXT_MAP_INJECTOR
         end
-
-        # Returns an extractor that extracts context using the W3C Trace Context
-        # with Rack normalized keys (upcased and prefixed with HTTP_)
-        def rack_extractor
-          RACK_EXTRACTOR
-        end
-
-        # Returns an injector that injects context using the W3C Trace Context
-        # format with Rack normalized keys (upcased and prefixed with HTTP_)
-        def rack_injector
-          RACK_INJECTOR
-        end
       end
     end
   end

data/lib/opentelemetry/trace/propagation/trace_context/text_map_extractor.rb

@@ -9,18 +9,15 @@ module OpenTelemetry
       module TraceContext
         # Extracts context from carriers in the W3C Trace Context format
         class TextMapExtractor
-          include Context::Propagation::DefaultGetter
-
           # Returns a new TextMapExtractor that extracts context using the
-          # specified header keys
+          # specified getter
           #
-          # @param [String] traceparent_key The traceparent header key used in the carrier
-          # @param [String] tracestate_key The tracestate header key used in the carrier
+          # @param [optional Getter] default_getter The default getter used to read
+          #   headers from a carrier during extract. Defaults to a +TextMapGetter+
+          #   instance.
           # @return [TextMapExtractor]
-          def initialize(traceparent_key: 'traceparent',
-                         tracestate_key: 'tracestate')
-            @traceparent_key = traceparent_key
-            @tracestate_key = tracestate_key
+          def initialize(default_getter = Context::Propagation.text_map_getter)
+            @default_getter = default_getter
           end
 
           # Extract a remote {Trace::SpanContext} from the supplied carrier.
@@ -28,17 +25,15 @@ module OpenTelemetry
           #
           # @param [Carrier] carrier The carrier to get the header from.
           # @param [Context] context The context to be updated with extracted context
-          # @param [optional Callable] getter An optional callable that takes a carrier and a key and
-          #   returns the value associated with the key. If omitted the default getter will be used
-          #   which expects the carrier to respond to [] and []=.
-          # @yield [Carrier, String] if an optional getter is provided, extract will yield the carrier
-          #   and the header key to the getter.
+          # @param [optional Getter] getter If the optional getter is provided, it
+          #   will be used to read the header from the carrier, otherwise the default
+          #   getter will be used.
           # @return [Context] Updated context with span context from the header, or the original
           #   context if parsing fails.
-          def extract(carrier, context, &getter)
-            getter ||= default_getter
-            tp = TraceParent.from_string(getter.call(carrier, @traceparent_key))
-            tracestate = Tracestate.from_string(getter.call(carrier, @tracestate_key))
+          def extract(carrier, context, getter = nil)
+            getter ||= @default_getter
+            tp = TraceParent.from_string(getter.get(carrier, TRACEPARENT_KEY))
+            tracestate = Tracestate.from_string(getter.get(carrier, TRACESTATE_KEY))
 
             span_context = Trace::SpanContext.new(trace_id: tp.trace_id,
                                                   span_id: tp.span_id,

data/lib/opentelemetry/trace/propagation/trace_context/text_map_injector.rb

@@ -9,35 +9,30 @@ module OpenTelemetry
       module TraceContext
         # Injects context into carriers using the W3C Trace Context format
         class TextMapInjector
-          include Context::Propagation::DefaultSetter
-
           # Returns a new TextMapInjector that injects context using the
-          # specified header keys
+          # specified setter
           #
-          # @param [String] traceparent_key The traceparent header key used in the carrier
-          # @param [String] tracestate_key The tracestate header key used in the carrier
+          # @param [optional Setter] default_setter The default setter used to
+          #   write context into a carrier during inject. Defaults to a
+          #   {TextMapSetter} instance.
           # @return [TextMapInjector]
-          def initialize(traceparent_key: 'traceparent',
-                         tracestate_key: 'tracestate')
-            @traceparent_key = traceparent_key
-            @tracestate_key = tracestate_key
+          def initialize(default_setter = Context::Propagation.text_map_setter)
+            @default_setter = default_setter
           end
 
           # Set the span context on the supplied carrier.
           #
           # @param [Context] context The active {Context}.
-          # @param [optional Callable] setter An optional callable that takes a carrier and a key and
-          #   a value and assigns the key-value pair in the carrier. If omitted the default setter
-          #   will be used which expects the carrier to respond to [] and []=.
-          # @yield [Carrier, String, String] if an optional setter is provided, inject will yield
-          #   carrier, header key, header value to the setter.
+          # @param [optional Setter] setter If the optional setter is provided, it
+          #   will be used to write context into the carrier, otherwise the default
+          #   setter will be used.
           # @return [Object] the carrier with context injected
-          def inject(carrier, context, &setter)
+          def inject(carrier, context, setter = nil)
             return carrier unless (span_context = span_context_from(context))
 
-            setter ||= DEFAULT_SETTER
-            setter.call(carrier, @traceparent_key, TraceParent.from_span_context(span_context).to_s)
-            setter.call(carrier, @tracestate_key, span_context.tracestate.to_s) unless span_context.tracestate.empty?
+            setter ||= @default_setter
+            setter.set(carrier, TRACEPARENT_KEY, TraceParent.from_span_context(span_context).to_s)
+            setter.set(carrier, TRACESTATE_KEY, span_context.tracestate.to_s) unless span_context.tracestate.empty?
 
             carrier
           end

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)
@@ -58,6 +61,23 @@ module OpenTelemetry
       end
       alias []= set_attribute
 
+      # Add attributes
+      #
+      # Note that the OpenTelemetry project
+      # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md
+      # documents} certain "standard attributes" that have prescribed semantic
+      # meanings.
+      #
+      # @param [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes
+      #   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 add_attributes(attributes)
+        self
+      end
+
       # Add an event to a {Span}.
       #
       # Example:
@@ -85,9 +105,13 @@ module OpenTelemetry
       # can be recorded on a span.
       #
       # @param [Exception] exception The exception to recorded
+      # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+      #   attributes One or more key:value pairs, where the keys must be
+      #   strings and the values may be (array of) string, boolean or numeric
+      #   type.
       #
       # @return [void]
-      def record_exception(exception); end
+      def record_exception(exception, attributes: nil); end
 
       # Sets the Status to the Span
       #

data/lib/opentelemetry/version.rb

@@ -6,5 +6,5 @@
 
 module OpenTelemetry
   ## Current OpenTelemetry version
-  VERSION = '0.12.0'
+  VERSION = '0.16.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-api
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.16.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-24 00:00:00.000000000 Z
+date: 2021-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ipsa
@@ -160,12 +160,12 @@ files:
 - lib/opentelemetry/context/key.rb
 - lib/opentelemetry/context/propagation.rb
 - lib/opentelemetry/context/propagation/composite_propagator.rb
-- lib/opentelemetry/context/propagation/default_getter.rb
-- lib/opentelemetry/context/propagation/default_setter.rb
 - lib/opentelemetry/context/propagation/noop_extractor.rb
 - lib/opentelemetry/context/propagation/noop_injector.rb
-- lib/opentelemetry/context/propagation/propagation.rb
 - lib/opentelemetry/context/propagation/propagator.rb
+- lib/opentelemetry/context/propagation/rack_env_getter.rb
+- lib/opentelemetry/context/propagation/text_map_getter.rb
+- lib/opentelemetry/context/propagation/text_map_setter.rb
 - lib/opentelemetry/error.rb
 - lib/opentelemetry/instrumentation.rb
 - lib/opentelemetry/instrumentation/base.rb
@@ -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.12.0/file.CHANGELOG.html
-  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/master/api
+  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.16.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.12.0
+  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.16.0
 post_install_message: 
 rdoc_options: []
 require_paths:

data/lib/opentelemetry/context/propagation/default_getter.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright The OpenTelemetry Authors
-#
-# SPDX-License-Identifier: Apache-2.0
-
-module OpenTelemetry
-  class Context
-    module Propagation
-      # The default getter module provides a common method for reading
-      # a key from a carrier that implements +[]+
-      module DefaultGetter
-        DEFAULT_GETTER = ->(carrier, key) { carrier[key] }
-        private_constant :DEFAULT_GETTER
-
-        # Returns a callable that can read a key from a carrier that implements
-        # +[]+. Useful for extract operations.
-        #
-        # @return [Callable]
-        def default_getter
-          DEFAULT_GETTER
-        end
-      end
-    end
-  end
-end

data/lib/opentelemetry/context/propagation/default_setter.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright The OpenTelemetry Authors
-#
-# SPDX-License-Identifier: Apache-2.0
-
-module OpenTelemetry
-  class Context
-    module Propagation
-      # The default setter module provides a common method for writing
-      # a key into a carrier that implements +[]=+
-      module DefaultSetter
-        DEFAULT_SETTER = ->(carrier, key, value) { carrier[key] = value }
-        private_constant :DEFAULT_SETTER
-
-        # Returns a callable that can write a key into a carrier that implements
-        # +[]=+. Useful for inject operations.
-        #
-        # @return [Callable]
-        def default_setter
-          DEFAULT_SETTER
-        end
-      end
-    end
-  end
-end

data/lib/opentelemetry/context/propagation/propagation.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright The OpenTelemetry Authors
-#
-# SPDX-License-Identifier: Apache-2.0
-
-module OpenTelemetry
-  class Context
-    module Propagation
-      # The Propagation class provides methods to inject and extract context
-      # to pass across process boundaries
-      class Propagation
-        # Get or set the global http propagator. Use a CompositePropagator
-        # to propagate multiple formats.
-        attr_accessor :http
-
-        # Get or set the global text propagator. Use a CompositePropagator
-        # to propagate multiple formats.
-        attr_accessor :text
-
-        def initialize
-          @http = @text = Propagator.new(NoopInjector.new, NoopExtractor.new)
-        end
-      end
-    end
-  end
-end