opentelemetry-api 0.11.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b7fecd268c9efe43c452847e831bf1456d502c8531e589691b865bd1264b53f
-  data.tar.gz: d8b33160247e5d8c94b248f607b621333112cda1a6fc7af00ce68ef1caed1cb0
+  metadata.gz: d9a70b684347cdc76e7cc5654e09ad01eb406cb415006b8f9418ff5c421521cf
+  data.tar.gz: 818b8c0cd95656898d0ce0eb4cf44d5fcc15ad7dd86e88b43b8aa1dc920dc05d
 SHA512:
-  metadata.gz: 06e4bda488c11623f710a74288de802c8af5fbb879bb52edbd003dd10159ff443bde7c9d6f511915e0ecdaaf54244f7b8897c4137b466bd11bdc87f51b87d337
-  data.tar.gz: 8466f42436e3e89e0a4339699887b3eae95551dd601f66be5b3f9ffc76f3aaad2075e95cb6aeed945422e0ea998148b769dc2781d3095a67c2051c2cc52068a7
+  metadata.gz: 3823e1d3a42b7cf8fcab40b5d2eb42f1fa312639175f8b57fef4ea5452451d8b358439424dc8da1825dbbb61e38c9a987c5996144d927bf6cb883a38f9dbaba0
+  data.tar.gz: 24365bbb7500da52d4b07ae1a54996d86a4ee98db465f15fe9b93aef4d6911ca072b1f48b1c1977351f0326607c271536b2b2b1df98b4831c70912be5adf0e65

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 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 
+
+* 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 
+
 ### v0.11.0 / 2020-12-11
 
 * BREAKING CHANGE: Implement tracestate 

data/README.md

@@ -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

data/lib/opentelemetry.rb

@@ -22,13 +22,28 @@ require 'opentelemetry/version'
 module OpenTelemetry
   extend self
 
-  attr_writer :tracer_provider, :meter_provider, :baggage, :logger
+  attr_writer :tracer_provider, :meter_provider, :propagation, :baggage,
+              :logger, :error_handler
 
   # @return [Object, Logger] configured Logger or a default STDOUT Logger.
   def logger
     @logger ||= Logger.new(STDOUT, level: ENV['OTEL_LOG_LEVEL'] || Logger::INFO)
   end
 
+  # @return [Callable] configured error handler or a default that logs the
+  #   exception and message at ERROR level.
+  def error_handler
+    @error_handler ||= ->(exception: nil, message: nil) { logger.error("OpenTelemetry error: #{[message, exception&.message].compact.join(' - ')}") }
+  end
+
+  # Handles an error by calling the configured error_handler.
+  #
+  # @param [optional Exception] exception The exception to be handled
+  # @param [optional String] message An error message.
+  def handle_error(exception: nil, message: nil)
+    error_handler.call(exception: exception, message: message)
+  end
+
   # @return [Object, Trace::TracerProvider] registered tracer provider or a
   #   default no-op implementation of the tracer provider.
   def tracer_provider
@@ -54,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,46 @@
+# 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)]
+        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!
+        end
+
+        def from_rack_key(key)
+          start = key.start_with?('HTTP_') ? 5 : 0
+          ret = key[start..-1]
+          ret.tr!('_', '-')
+          ret.downcase!
+        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/instrumentation/registry.rb

@@ -79,8 +79,7 @@ module OpenTelemetry
           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}"
+        OpenTelemetry.handle_error(exception: e, message: "Instrumentation: #{instrumentation.name} unhandled exception during install: #{e.backtrace}")
       end
     end
   end

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)
@@ -85,9 +88,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.11.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.11.0
+  version: 0.15.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-11 00:00:00.000000000 Z
+date: 2021-02-18 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.11.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.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.11.0
+  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.15.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