opentelemetry-api 0.13.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42c8e52feabfa3bfc793e0699cbd50b72a1df552be7cffd96d2d80237b34e3e9
-  data.tar.gz: 3e18f329dff954d7b5edeb79a5b7f18f1c24f57af5df9c51cf5d3da2c5d45a63
+  metadata.gz: 8c72d994e97f5c64be4418b271fa7f359899afa493910af615521eb785f671c2
+  data.tar.gz: 11c0b57837eae216f71e63d9d462f28e41fd873b2c33d9ecffe51f15f13a8373
 SHA512:
-  metadata.gz: 0c7f5a046e769ea40092101de2638a418aec4904ea6fec4af72f59e4d4f6f15e23899d31cfbc5c74eb0ca3e63e36b765930e377756f131bccaad5fb20c644fa5
-  data.tar.gz: 8fc31b5c431446a9534b0cf9cee191b0737ff95a2e824c0d1b68947aa1f53f7f4fa58ab145fc7624cbf2d5cf0840ed3f60885e7fcb10b825b332ad8fc73f2724
+  metadata.gz: b162dfbf770ef1a162fe2d6826832d1c51a8a019e5bdcc3632ed6449a832cd3c94d98a627687af22b86b7bcc23956a6e9044834c4010d7ac98a37ae33b204a3e
+  data.tar.gz: aca58a7e39e73ae037429a0ce55b01160d20fdedba2c184dff6c2c34e8f17d2086a963f9e294dcccddea9fe81569ab99c2f28ff0e470dfd52576c4b9e49aad61

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Release History: opentelemetry-api
 
+### 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 
+
+* ADDED: Replace getter and setter callables and remove rack specific propagators 
+
 ### v0.13.0 / 2021-01-29
 
 * ADDED: Add optional attributes to record_exception 

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,7 +21,10 @@ require 'opentelemetry/version'
 module OpenTelemetry
   extend self
 
-  attr_writer :tracer_provider, :meter_provider, :baggage, :logger, :error_handler
+  @mutex = Mutex.new
+  @tracer_provider = Internal::ProxyTracerProvider.new
+
+  attr_writer :propagation, :baggage, :logger, :error_handler
 
   # @return [Object, Logger] configured Logger or a default STDOUT Logger.
   def logger
@@ -43,33 +45,35 @@ 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
+    @mutex.synchronize { @tracer_provider }
   end
 
-  # @return [Object, Baggage::Manager] registered
+  # @return [Object, Baggage::NoopManager] registered
   #   baggage manager or a default no-op implementation of the
   #   manager.
   def baggage
-    @baggage ||= Baggage::Manager.new
+    @baggage ||= Baggage::NoopManager.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::NoopTextMapPropagator.new
   end
 end

data/lib/opentelemetry/baggage.rb

@@ -4,9 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+require 'opentelemetry/baggage/propagation'
 require 'opentelemetry/baggage/builder'
+require 'opentelemetry/baggage/entry'
 require 'opentelemetry/baggage/manager'
-require 'opentelemetry/baggage/propagation'
+require 'opentelemetry/baggage/noop_builder'
+require 'opentelemetry/baggage/noop_manager'
 
 module OpenTelemetry
   # The Baggage module provides functionality to record and propagate

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

@@ -6,35 +6,98 @@
 
 module OpenTelemetry
   module Baggage
-    # No op implementation of Baggage::Manager
+    # Operational Baggage Manager implementation
     class Manager
-      NOOP_BUILDER = Builder.new
-      EMPTY_VALUES = {}.freeze
-      private_constant(:NOOP_BUILDER, :EMPTY_VALUES)
+      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 +Manager+, 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)
-        yield NOOP_BUILDER
-        context
+        builder = Builder.new(baggage_for(context).dup)
+        yield builder
+        context.set_value(BAGGAGE_KEY, builder.entries)
       end
 
-      def set_value(key, value, context: Context.current)
-        context
+      # 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)
-        nil
+        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)
-        EMPTY_VALUES
+        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)
-        context
+        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
 
-      def clear(context: Context.current)
-        context
+      private
+
+      def baggage_for(context)
+        context.value(BAGGAGE_KEY) || EMPTY_BAGGAGE
       end
     end
   end

data/lib/opentelemetry/baggage/noop_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Baggage
+    # No op implementation of Baggage::Builder
+    class NoopBuilder
+      def set_value(key, value, metadata: nil); end
+
+      def remove_value(key); end
+
+      def clear; end
+    end
+  end
+end

data/lib/opentelemetry/baggage/noop_manager.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Baggage
+    # No op implementation of Baggage::Manager
+    class NoopManager
+      NOOP_BUILDER = NoopBuilder.new
+      EMPTY_HASH = {}.freeze
+      private_constant(:NOOP_BUILDER, :EMPTY_HASH)
+
+      def build(context: Context.current)
+        yield NOOP_BUILDER
+        context
+      end
+
+      def set_value(key, value, metadata: nil, context: Context.current)
+        context
+      end
+
+      def value(key, context: Context.current)
+        nil
+      end
+
+      def values(context: Context.current)
+        EMPTY_HASH
+      end
+
+      def raw_entries(context: Context.current)
+        EMPTY_HASH
+      end
+
+      def remove_value(key, context: Context.current)
+        context
+      end
+
+      def clear(context: Context.current)
+        context
+      end
+    end
+  end
+end

data/lib/opentelemetry/baggage/propagation.rb

@@ -5,52 +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
 
-      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'
-      )
+      TEXT_MAP_PROPAGATOR = TextMapPropagator.new
 
-      private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR, :RACK_INJECTOR,
-                       :RACK_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
-      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
+      # Returns a text map propagator that propagates context using the
+      # W3C Baggage format.
+      def text_map_propagator
+        TEXT_MAP_PROPAGATOR
       end
     end
   end