opentelemetry-api 0.14.0 → 1.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23c4a8602afe2513fff72ec29784b696ae41eccee8c3b25eb4cf48081856b22b
-  data.tar.gz: 17507ad2d0dbb697e6f1bb8cbf133d0baa01234d7383d9bb726b0d5fb11c4cb3
+  metadata.gz: 87cc02bff4251a383a6bd5ea88b50f0c47b6aeb206d2585a6ddccbc9811aa503
+  data.tar.gz: 1ce534ee66ea666a853e2625563c515f7a7439c791401997c3a35c7515849fcd
 SHA512:
-  metadata.gz: 5c37bb2d8a469bda44a121bfca1218380553cbc66d24e8001df4c2e67d93f9b474335962095b77a28e6de3c53f34af98ea18b12a3335cdd45d0b04d50510b2be
-  data.tar.gz: 3980934cdfdb34e96eb8215a9ebb26eb0b3d096be3e545837ee9d6595ff5e114ea680e692ccc7d0af2d89d8a4550e180671e4d92c5266b6a445c45fc991e0602
+  metadata.gz: 7ea3d7eca27eda27dd1954cd9056ba3567a3d68ccafda1a55f9683acc381ef18e37ef319d12124ef11fe4b75af528c7d4157b8b7ed15d7dbde81487e36565c70
+  data.tar.gz: 878d7960e8b69e8d02a5e9354b8737250f7abacd9656b09b3ccd72d493abcdbd20aae4a76e5ff63d9dd8050a6714b410d948ad81cb489c5af8a44856316f4e35

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Release History: opentelemetry-api
 
+### v1.0.0.rc2 / 2021-06-23
+
+* BREAKING CHANGE: Remove optional parent_context from in_span [729](https://github.com/open-telemetry/opentelemetry-ruby/pull/729)
+* BREAKING CHANGE: Refactor Baggage to remove Noop* [800](https://github.com/open-telemetry/opentelemetry-ruby/pull/800)
+  - The noop baggage manger has been removed.
+  - The baggage management methods are now available through OpenTelemetry::Baggage#method, previously OpenTelemetry.baggage#method
+* BREAKING CHANGE: Total order constraint on span.status= [805](https://github.com/open-telemetry/opentelemetry-ruby/pull/805)
+  - The OpenTelemetry::Trace::Util::HttpToStatus module has been removed as it was incorrectly setting the span status to OK for codes codes in the range 100..399
+  - The HttpToStatus module can be replaced inline as follows `span.status = OpenTelemetry::Trace::Status.error unless (100..399).include?(response_code.to_i)`
+  - The `Status.new(code, description:)` initializer has been hidden in favour of simpler constructors for each status code: `Status.ok`, `Status.error` and `Status.unset`. Each constructor takes an optional description.
+
+* ADDED: Add Tracer.non_recording_span to API [799](https://github.com/open-telemetry/opentelemetry-ruby/pull/799)
+* FIXED: Reduce span allocation in API [795](https://github.com/open-telemetry/opentelemetry-ruby/pull/795)
+* FIXED: Return early if carrier is nil [835](https://github.com/open-telemetry/opentelemetry-ruby/pull/835)
+* FIXED: Update context to match spec [807](https://github.com/open-telemetry/opentelemetry-ruby/pull/807)
+  - The `Context.current` setter has been removed and the previously private attach/detach methods are now available as class methods on the context module.
+
+### v1.0.0.rc1 / 2021-05-21
+
+* BREAKING CHANGE: Remove optional parent_context from in_span 
+
+* FIXED: Remove optional parent_context from in_span
+
+### v0.17.0 / 2021-04-22
+
+* BREAKING CHANGE: Replace TextMapInjector/TextMapExtractor pairs with a TextMapPropagator.
+
+  [Check the propagator documentation](https://open-telemetry.github.io/opentelemetry-ruby/) for the new usage.
+* BREAKING CHANGE: Remove metrics API.
+
+  `OpenTelemetry::Metrics` and all of its behavior removed until spec stabilizes.
+* BREAKING CHANGE: Extract instrumentation base from api (#698).
+
+  To take advantage of a base instrumentation class to create your own auto-instrumentation, require and use the `opentelemetry-instrumentation-base` gem.
+
+* ADDED: Default noop tracer for instrumentation 
+* FIXED: Refactor propagators to add #fields 
+* FIXED: Remove metrics API 
+* FIXED: Dynamically upgrade global tracer provider 
+
+### 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 

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
 
@@ -63,4 +63,4 @@ The `opentelemetry-api` gem is distributed under the Apache 2.0 license. See [LI
 [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

@@ -9,9 +9,8 @@ require 'logger'
 require 'opentelemetry/error'
 require 'opentelemetry/context'
 require 'opentelemetry/baggage'
-require_relative './opentelemetry/instrumentation'
-require 'opentelemetry/metrics'
 require 'opentelemetry/trace'
+require 'opentelemetry/internal'
 require 'opentelemetry/version'
 
 # OpenTelemetry is an open source observability framework, providing a
@@ -22,8 +21,10 @@ require 'opentelemetry/version'
 module OpenTelemetry
   extend self
 
-  attr_writer :tracer_provider, :meter_provider, :propagation, :baggage,
-              :logger, :error_handler
+  @mutex = Mutex.new
+  @tracer_provider = Internal::ProxyTracerProvider.new
+
+  attr_writer :propagation, :logger, :error_handler
 
   # @return [Object, Logger] configured Logger or a default STDOUT Logger.
   def logger
@@ -44,36 +45,28 @@ module OpenTelemetry
     error_handler.call(exception: exception, message: message)
   end
 
+  # Register the global tracer provider.
+  #
+  # @param [TracerProvider] provider A tracer provider to register as the
+  #   global instance.
+  def tracer_provider=(provider)
+    @mutex.synchronize do
+      if @tracer_provider.instance_of? Internal::ProxyTracerProvider
+        logger.debug("Upgrading default proxy tracer provider to #{provider.class}")
+        @tracer_provider.delegate = provider
+      end
+      @tracer_provider = provider
+    end
+  end
+
   # @return [Object, Trace::TracerProvider] registered tracer provider or a
   #   default no-op implementation of the tracer provider.
   def tracer_provider
-    @tracer_provider ||= Trace::TracerProvider.new
-  end
-
-  # @return [Object, Metrics::MeterProvider] registered meter provider or a
-  #   default no-op implementation of the meter provider.
-  def meter_provider
-    @meter_provider ||= Metrics::MeterProvider.new
-  end
-
-  # @return [Instrumentation::Registry] registry containing all known
-  #  instrumentation
-  def instrumentation_registry
-    @instrumentation_registry ||= Instrumentation::Registry.new
-  end
-
-  # @return [Object, Baggage::Manager] registered
-  #   baggage manager or a default no-op implementation of the
-  #   manager.
-  def baggage
-    @baggage ||= Baggage::Manager.new
+    @mutex.synchronize { @tracer_provider }
   end
 
   # @return [Context::Propagation::Propagator] a propagator instance
   def propagation
-    @propagation ||= Context::Propagation::Propagator.new(
-      Context::Propagation::NoopInjector.new,
-      Context::Propagation::NoopExtractor.new
-    )
+    @propagation ||= Context::Propagation::NoopTextMapPropagator.new
   end
 end

data/lib/opentelemetry/baggage.rb

@@ -4,13 +4,106 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry/baggage/builder'
-require 'opentelemetry/baggage/manager'
 require 'opentelemetry/baggage/propagation'
+require 'opentelemetry/baggage/builder'
+require 'opentelemetry/baggage/entry'
 
 module OpenTelemetry
   # The Baggage module provides functionality to record and propagate
   # baggage in a distributed trace
   module Baggage
+    extend self
+
+    BAGGAGE_KEY = OpenTelemetry::Baggage::Propagation::ContextKeys.baggage_key
+    EMPTY_BAGGAGE = {}.freeze
+    private_constant(:BAGGAGE_KEY, :EMPTY_BAGGAGE)
+
+    # Used to chain modifications to baggage. The result is a
+    # context with an updated baggage. If only a single
+    # modification is being made to baggage, use the other
+    # methods on +Baggage+, if multiple modifications are being made, use
+    # this one.
+    #
+    # @param [optional Context] context The context to update with with new
+    #   modified baggage. Defaults to +Context.current+
+    # @return [Context]
+    def build(context: Context.current)
+      builder = Builder.new(baggage_for(context).dup)
+      yield builder
+      context.set_value(BAGGAGE_KEY, builder.entries)
+    end
+
+    # Returns a new context with empty baggage
+    #
+    # @param [optional Context] context Context to clear baggage from. Defaults
+    #   to +Context.current+
+    # @return [Context]
+    def clear(context: Context.current)
+      context.set_value(BAGGAGE_KEY, EMPTY_BAGGAGE)
+    end
+
+    # Returns the corresponding baggage.entry (or nil) for key
+    #
+    # @param [String] key The lookup key
+    # @param [optional Context] context The context from which to retrieve
+    #   the key.
+    #   Defaults to +Context.current+
+    # @return [String]
+    def value(key, context: Context.current)
+      baggage_for(context)[key]&.value
+    end
+
+    # Returns the baggage
+    #
+    # @param [optional Context] context The context from which to retrieve
+    #   the baggage.
+    #   Defaults to +Context.current+
+    # @return [Hash]
+    def values(context: Context.current)
+      baggage_for(context).transform_values(&:value)
+    end
+
+    # @api private
+    def raw_entries(context: Context.current)
+      baggage_for(context).dup.freeze
+    end
+
+    # Returns a new context with new key-value pair
+    #
+    # @param [String] key The key to store this value under
+    # @param [String] value String value to be stored under key
+    # @param [optional String] metadata This is here to store properties
+    #   received from other W3C Baggage impelmentations but is not exposed in
+    #   OpenTelemetry. This is condsidered private API and not for use by
+    #   end-users.
+    # @param [optional Context] context The context to update with new
+    #   value. Defaults to +Context.current+
+    # @return [Context]
+    def set_value(key, value, metadata: nil, context: Context.current)
+      new_baggage = baggage_for(context).dup
+      new_baggage[key] = Entry.new(value, metadata)
+      context.set_value(BAGGAGE_KEY, new_baggage)
+    end
+
+    # Returns a new context with value at key removed
+    #
+    # @param [String] key The key to remove
+    # @param [optional Context] context The context to remove baggage
+    #   from. Defaults to +Context.current+
+    # @return [Context]
+    def remove_value(key, context: Context.current)
+      baggage = baggage_for(context)
+      return context unless baggage.key?(key)
+
+      new_baggage = baggage.dup
+      new_baggage.delete(key)
+      context.set_value(BAGGAGE_KEY, new_baggage)
+    end
+
+    private
+
+    def baggage_for(context)
+      context.value(BAGGAGE_KEY) || EMPTY_BAGGAGE
+    end
   end
 end

data/lib/opentelemetry/baggage/builder.rb

@@ -6,13 +6,39 @@
 
 module OpenTelemetry
   module Baggage
-    # No op implementation of Baggage::Builder
+    # Operational implementation of Baggage::Builder
     class Builder
-      def set_value(key, value); end
+      # @api private
+      attr_reader :entries
 
-      def remove_value(key); end
+      # @api private
+      def initialize(entries)
+        @entries = entries
+      end
 
-      def clear; end
+      # Set key-value in the to-be-created baggage
+      #
+      # @param [String] key The key to store this value under
+      # @param [String] value String value to be stored under key
+      # @param [optional String] metadata This is here to store properties
+      #   received from other W3C Baggage impelmentations but is not exposed in
+      #   OpenTelemetry. This is condsidered private API and not for use by
+      #   end-users.
+      def set_value(key, value, metadata: nil)
+        @entries[key] = OpenTelemetry::Baggage::Entry.new(value, metadata)
+      end
+
+      # Removes key from the to-be-created baggage
+      #
+      # @param [String] key The key to remove
+      def remove_value(key)
+        @entries.delete(key)
+      end
+
+      # Clears all baggage from the to-be-created baggage
+      def clear
+        @entries.clear
+      end
     end
   end
 end

data/lib/opentelemetry/baggage/entry.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  # OpenTelemetry Baggage Implementation
+  module Baggage
+    # Read-only representation of a baggage entry
+    class Entry
+      attr_reader :value, :metadata
+
+      def initialize(value, metadata = nil)
+        @value = value
+        @metadata = metadata
+      end
+    end
+  end
+end

data/lib/opentelemetry/baggage/propagation.rb

@@ -5,32 +5,23 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require 'opentelemetry/baggage/propagation/context_keys'
-require 'opentelemetry/baggage/propagation/text_map_injector'
-require 'opentelemetry/baggage/propagation/text_map_extractor'
+require 'opentelemetry/baggage/propagation/text_map_propagator'
 
 module OpenTelemetry
   module Baggage
-    # The Baggage::Propagation module contains injectors and
-    # extractors for sending and receiving baggage over the wire
+    # The Baggage::Propagation module contains a text map propagator for
+    # sending and receiving baggage over the wire.
     module Propagation
       extend self
 
-      BAGGAGE_KEY = 'baggage'
-      TEXT_MAP_EXTRACTOR = TextMapExtractor.new
-      TEXT_MAP_INJECTOR = TextMapInjector.new
+      TEXT_MAP_PROPAGATOR = TextMapPropagator.new
 
-      private_constant :BAGGAGE_KEY, :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR
+      private_constant :TEXT_MAP_PROPAGATOR
 
-      # Returns an extractor that extracts context using the W3C Baggage
-      # format
-      def text_map_injector
-        TEXT_MAP_INJECTOR
-      end
-
-      # Returns an injector that injects context using the W3C Baggage
-      # format
-      def text_map_extractor
-        TEXT_MAP_EXTRACTOR
+      # Returns a text map propagator that propagates context using the
+      # W3C Baggage format.
+      def text_map_propagator
+        TEXT_MAP_PROPAGATOR
       end
     end
   end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'cgi'
+
+module OpenTelemetry
+  module Baggage
+    module Propagation
+      # Propagates baggage using the W3C Baggage format
+      class TextMapPropagator
+        # Maximums according to W3C Baggage spec
+        MAX_ENTRIES = 180
+        MAX_ENTRY_LENGTH = 4096
+        MAX_TOTAL_LENGTH = 8192
+
+        BAGGAGE_KEY = 'baggage'
+        FIELDS = [BAGGAGE_KEY].freeze
+
+        private_constant :BAGGAGE_KEY, :FIELDS, :MAX_ENTRIES, :MAX_ENTRY_LENGTH, :MAX_TOTAL_LENGTH
+
+        # Inject in-process baggage into the supplied carrier.
+        #
+        # @param [Carrier] carrier The mutable carrier to inject baggage into
+        # @param [Context] context The context to read baggage from
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   text map setter will be used.
+        def inject(carrier, context: Context.current, setter: Context::Propagation.text_map_setter)
+          baggage = OpenTelemetry::Baggage.raw_entries(context: context)
+
+          return if baggage.nil? || baggage.empty?
+
+          encoded_baggage = encode(baggage)
+          setter.set(carrier, BAGGAGE_KEY, encoded_baggage) unless encoded_baggage&.empty?
+          nil
+        end
+
+        # Extract remote baggage from the supplied carrier.
+        # If extraction fails, the original context will be returned
+        #
+        # @param [Carrier] carrier The carrier to get the header from
+        # @param [optional Context] context Context to be updated with the baggage
+        #   extracted from the carrier. Defaults to +Context.current+.
+        # @param [optional Getter] getter If the optional getter is provided, it
+        #   will be used to read the header from the carrier, otherwise the default
+        #   text map getter will be used.
+        #
+        # @return [Context] context updated with extracted baggage, or the original context
+        #   if extraction fails
+        def extract(carrier, context: Context.current, getter: Context::Propagation.text_map_getter)
+          header = getter.get(carrier, BAGGAGE_KEY)
+          return context unless header
+
+          entries = header.gsub(/\s/, '').split(',')
+
+          OpenTelemetry::Baggage.build(context: context) do |builder|
+            entries.each do |entry|
+              # Note metadata is currently unused in OpenTelemetry, but is part
+              # the W3C spec where it's referred to as properties. We preserve
+              # the properties (as-is) so that they can be propagated elsewhere.
+              kv, meta = entry.split(';', 2)
+              k, v = kv.split('=').map!(&CGI.method(:unescape))
+              builder.set_value(k, v, metadata: meta)
+            end
+          end
+        rescue StandardError => e
+          OpenTelemetry.logger.debug "Error extracting W3C baggage: #{e.message}"
+          context
+        end
+
+        # Returns the predefined propagation fields. If your carrier is reused, you
+        # should delete the fields returned by this method before calling +inject+.
+        #
+        # @return [Array<String>] a list of fields that will be used by this propagator.
+        def fields
+          FIELDS
+        end
+
+        private
+
+        def encode(baggage)
+          result = +''
+          encoded_count = 0
+          baggage.each_pair do |key, entry|
+            break unless encoded_count < MAX_ENTRIES
+
+            encoded_entry = encode_value(key, entry)
+            next unless encoded_entry.size <= MAX_ENTRY_LENGTH &&
+                        encoded_entry.size + result.size <= MAX_TOTAL_LENGTH
+
+            result << encoded_entry << ','
+            encoded_count += 1
+          end
+          result.chop!
+        end
+
+        def encode_value(key, entry)
+          result = +"#{CGI.escape(key.to_s)}=#{CGI.escape(entry.value.to_s)}"
+          # We preserve metadata recieved on extract and assume it's already formatted
+          # for transport. It's sent as-is without further processing.
+          result << ";#{entry.metadata}" if entry.metadata
+          result
+        end
+      end
+    end
+  end
+end