opentelemetry-api 0.14.0 → 1.0.0.rc2

data/lib/opentelemetry/internal.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/internal/proxy_tracer'
+require 'opentelemetry/internal/proxy_tracer_provider'
+
+module OpenTelemetry
+  # @api private
+  #
+  # The Internal module provides API internal functionality that is not a part of the
+  # public API.
+  module Internal
+  end
+end

data/lib/opentelemetry/internal/proxy_tracer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Internal
+    # @api private
+    #
+    # {ProxyTracer} is an implementation of {OpenTelemetry::Trace::Tracer}. It is returned from
+    # the ProxyTracerProvider until a delegate tracer provider is installed. After the delegate
+    # tracer provider is installed, the ProxyTracer will delegate to the corresponding "real"
+    # tracer.
+    class ProxyTracer < Trace::Tracer
+      attr_writer :delegate
+
+      # Returns a new {ProxyTracer} instance.
+      #
+      # @return [ProxyTracer]
+      def initialize
+        @delegate = nil
+      end
+
+      def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+        return @delegate.start_root_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind) unless @delegate.nil?
+
+        super
+      end
+
+      def start_span(name, with_parent: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+        return @delegate.start_span(name, with_parent: with_parent, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind) unless @delegate.nil?
+
+        super
+      end
+    end
+  end
+end

data/lib/opentelemetry/internal/proxy_tracer_provider.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Internal
+    # @api private
+    #
+    # {ProxyTracerProvider} is an implementation of {OpenTelemetry::Trace::TracerProvider}.
+    # It is the default global tracer provider returned by OpenTelemetry.tracer_provider.
+    # It delegates to a "real" TracerProvider after the global tracer provider is registered.
+    # It returns {ProxyTracer} instances until the delegate is installed.
+    class ProxyTracerProvider < Trace::TracerProvider
+      Key = Struct.new(:name, :version)
+      private_constant(:Key)
+
+      # Returns a new {ProxyTracerProvider} instance.
+      #
+      # @return [ProxyTracerProvider]
+      def initialize
+        @mutex = Mutex.new
+        @registry = {}
+        @delegate = nil
+      end
+
+      # Set the delegate tracer provider. If this is called more than once, a warning will
+      # be logged and superfluous calls will be ignored.
+      #
+      # @param [TracerProvider] provider The tracer provider to delegate to
+      def delegate=(provider)
+        unless @delegate.nil?
+          OpenTelemetry.logger.warn 'Attempt to reset delegate in ProxyTracerProvider ignored.'
+          return
+        end
+
+        @mutex.synchronize do
+          @delegate = provider
+          @registry.each { |key, tracer| tracer.delegate = provider.tracer(key.name, key.version) }
+        end
+      end
+
+      # Returns a {Tracer} instance.
+      #
+      # @param [optional String] name Instrumentation package name
+      # @param [optional String] version Instrumentation package version
+      #
+      # @return [Tracer]
+      def tracer(name = nil, version = nil)
+        @mutex.synchronize do
+          return @delegate.tracer(name, version) unless @delegate.nil?
+
+          @registry[Key.new(name, version)] ||= ProxyTracer.new
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace.rb

@@ -81,6 +81,16 @@ module OpenTelemetry
     def with_span(span)
       Context.with_value(CURRENT_SPAN_KEY, span) { |c, s| yield s, c }
     end
+
+    # Wraps a SpanContext with an object implementing the Span interface. This is done in order
+    # to expose a SpanContext as a Span in operations such as in-process Span propagation.
+    #
+    # @param [SpanContext] span_context SpanContext to be wrapped
+    #
+    # @return [Span]
+    def non_recording_span(span_context)
+      Span.new(span_context: span_context)
+    end
   end
 end
 

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

@@ -5,8 +5,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require 'opentelemetry/trace/propagation/trace_context/trace_parent'
-require 'opentelemetry/trace/propagation/trace_context/text_map_extractor'
-require 'opentelemetry/trace/propagation/trace_context/text_map_injector'
+require 'opentelemetry/trace/propagation/trace_context/text_map_propagator'
 
 module OpenTelemetry
   module Trace
@@ -15,24 +14,14 @@ 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
+        TEXT_MAP_PROPAGATOR = TextMapPropagator.new
 
-        private_constant :TRACEPARENT_KEY, :TRACESTATE_KEY,
-                         :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR
+        private_constant :TEXT_MAP_PROPAGATOR
 
-        # Returns an extractor that extracts context using the W3C Trace Context
-        # format
-        def text_map_extractor
-          TEXT_MAP_EXTRACTOR
-        end
-
-        # Returns an injector that injects context using the W3C Trace Context
-        # format
-        def text_map_injector
-          TEXT_MAP_INJECTOR
+        # Returns a text map propagator that propagates context using the
+        # W3C Trace Context format.
+        def text_map_propagator
+          TEXT_MAP_PROPAGATOR
         end
       end
     end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    module Propagation
+      module TraceContext
+        # Propagates trace context using the W3C Trace Context format
+        class TextMapPropagator
+          TRACEPARENT_KEY = 'traceparent'
+          TRACESTATE_KEY = 'tracestate'
+          FIELDS = [TRACEPARENT_KEY, TRACESTATE_KEY].freeze
+
+          private_constant :TRACEPARENT_KEY, :TRACESTATE_KEY, :FIELDS
+
+          # Inject trace context into the supplied carrier.
+          #
+          # @param [Carrier] carrier The mutable carrier to inject trace context into
+          # @param [Context] context The context to read trace context 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)
+            span_context = Trace.current_span(context).context
+            return unless span_context.valid?
+
+            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?
+            nil
+          end
+
+          # Extract trace context 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 trace context
+          #   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)
+            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,
+                                                  trace_flags: tp.flags,
+                                                  tracestate: tracestate,
+                                                  remote: true)
+            span = OpenTelemetry::Trace.non_recording_span(span_context)
+            OpenTelemetry::Trace.context_with_span(span)
+          rescue OpenTelemetry::Error
+            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
+        end
+      end
+    end
+  end
+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:

data/lib/opentelemetry/trace/status.rb

@@ -4,15 +4,41 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry/trace/util/http_to_status'
-
 module OpenTelemetry
   module Trace
     # Status represents the status of a finished {Span}. It is composed of a
     # status code in conjunction with an optional descriptive message.
     class Status
-      # Convenience utility, not in API spec:
-      extend Util::HttpToStatus
+      class << self
+        private :new # rubocop:disable Style/AccessModifierDeclarations
+
+        # Returns a newly created {Status} with code == UNSET and an optional
+        # description.
+        #
+        # @param [String] description
+        # @return [Status]
+        def unset(description = '')
+          new(UNSET, description: description)
+        end
+
+        # Returns a newly created {Status} with code == OK and an optional
+        # description.
+        #
+        # @param [String] description
+        # @return [Status]
+        def ok(description = '')
+          new(OK, description: description)
+        end
+
+        # Returns a newly created {Status} with code == ERROR and an optional
+        # description.
+        #
+        # @param [String] description
+        # @return [Status]
+        def error(description = '')
+          new(ERROR, description: description)
+        end
+      end
 
       # Retrieve the status code of this Status.
       #
@@ -24,7 +50,10 @@ module OpenTelemetry
       # @return [String]
       attr_reader :description
 
-      # Initialize a Status.
+      # @api private
+      # The constructor is private and only for use internally by the class.
+      # Users should use the {unset}, {error}, or {ok} factory methods to
+      # obtain a {Status} instance.
       #
       # @param [Integer] code One of the status codes below
       # @param [String] description

data/lib/opentelemetry/trace/tracer.rb

@@ -23,21 +23,20 @@ module OpenTelemetry
       # span and reraised.
       # @yield [span, context] yields the newly created span and a context containing the
       #   span to the block.
-      def in_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil, with_parent: nil)
+      def in_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
         span = nil
-        span = start_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind, with_parent: with_parent)
+        span = start_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind)
         Trace.with_span(span) { |s, c| yield s, c }
       rescue Exception => e # rubocop:disable Lint/RescueException
         span&.record_exception(e)
-        span&.status = Status.new(Status::ERROR,
-                                  description: "Unhandled exception of type: #{e.class}")
+        span&.status = Status.error("Unhandled exception of type: #{e.class}")
         raise e
       ensure
         span&.finish
       end
 
       def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
-        Span.new
+        Span::INVALID
       end
 
       # Used when a caller wants to manage the activation/deactivation and lifecycle of
@@ -49,12 +48,12 @@ module OpenTelemetry
       #
       # @return [Span]
       def start_span(name, with_parent: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
-        span_context = OpenTelemetry::Trace.current_span(with_parent).context
+        span = OpenTelemetry::Trace.current_span(with_parent)
 
-        if span_context.valid?
-          Span.new(span_context: span_context)
+        if span.context.valid?
+          span
         else
-          Span.new
+          Span::INVALID
         end
       end
     end

data/lib/opentelemetry/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-api
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 1.0.0.rc2
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-03 00:00:00.000000000 Z
+date: 2021-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ipsa
@@ -151,36 +151,28 @@ files:
 - lib/opentelemetry.rb
 - lib/opentelemetry/baggage.rb
 - lib/opentelemetry/baggage/builder.rb
-- lib/opentelemetry/baggage/manager.rb
+- lib/opentelemetry/baggage/entry.rb
 - lib/opentelemetry/baggage/propagation.rb
 - lib/opentelemetry/baggage/propagation/context_keys.rb
-- lib/opentelemetry/baggage/propagation/text_map_extractor.rb
-- lib/opentelemetry/baggage/propagation/text_map_injector.rb
+- lib/opentelemetry/baggage/propagation/text_map_propagator.rb
 - lib/opentelemetry/context.rb
 - lib/opentelemetry/context/key.rb
 - lib/opentelemetry/context/propagation.rb
-- lib/opentelemetry/context/propagation/composite_propagator.rb
-- lib/opentelemetry/context/propagation/noop_extractor.rb
-- lib/opentelemetry/context/propagation/noop_injector.rb
-- lib/opentelemetry/context/propagation/propagator.rb
+- lib/opentelemetry/context/propagation/composite_text_map_propagator.rb
+- lib/opentelemetry/context/propagation/noop_text_map_propagator.rb
 - lib/opentelemetry/context/propagation/rack_env_getter.rb
 - lib/opentelemetry/context/propagation/text_map_getter.rb
+- lib/opentelemetry/context/propagation/text_map_propagator.rb
 - lib/opentelemetry/context/propagation/text_map_setter.rb
 - lib/opentelemetry/error.rb
-- lib/opentelemetry/instrumentation.rb
-- lib/opentelemetry/instrumentation/base.rb
-- lib/opentelemetry/instrumentation/registry.rb
-- lib/opentelemetry/metrics.rb
-- lib/opentelemetry/metrics/handles.rb
-- lib/opentelemetry/metrics/instruments.rb
-- lib/opentelemetry/metrics/meter.rb
-- lib/opentelemetry/metrics/meter_provider.rb
+- lib/opentelemetry/internal.rb
+- lib/opentelemetry/internal/proxy_tracer.rb
+- lib/opentelemetry/internal/proxy_tracer_provider.rb
 - lib/opentelemetry/trace.rb
 - lib/opentelemetry/trace/link.rb
 - lib/opentelemetry/trace/propagation.rb
 - lib/opentelemetry/trace/propagation/trace_context.rb
-- lib/opentelemetry/trace/propagation/trace_context/text_map_extractor.rb
-- lib/opentelemetry/trace/propagation/trace_context/text_map_injector.rb
+- lib/opentelemetry/trace/propagation/trace_context/text_map_propagator.rb
 - lib/opentelemetry/trace/propagation/trace_context/trace_parent.rb
 - lib/opentelemetry/trace/span.rb
 - lib/opentelemetry/trace/span_context.rb
@@ -190,16 +182,15 @@ files:
 - lib/opentelemetry/trace/tracer.rb
 - lib/opentelemetry/trace/tracer_provider.rb
 - lib/opentelemetry/trace/tracestate.rb
-- lib/opentelemetry/trace/util/http_to_status.rb
 - lib/opentelemetry/version.rb
 homepage: https://github.com/open-telemetry/opentelemetry-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.14.0/file.CHANGELOG.html
+  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v1.0.0.rc2/file.CHANGELOG.html
   source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/api
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
-  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.14.0
+  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v1.0.0.rc2
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -211,11 +202,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: A stats collection and distributed tracing framework