opentelemetry-api 0.2.0 → 0.3.0

data/lib/opentelemetry/trace/span.rb

@@ -45,7 +45,7 @@ module OpenTelemetry
       # Set attribute
       #
       # Note that the OpenTelemetry project
-      # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/semantic-conventions.md
+      # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md
       # documents} certain "standard attributes" that have prescribed semantic
       # meanings.
       #
@@ -71,16 +71,16 @@ module OpenTelemetry
       #   span.add_event { tracer.create_event(name: 'event', attributes: {'eager' => false}) }
       #
       # Note that the OpenTelemetry project
-      # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/semantic-conventions.md
+      # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md
       # documents} certain "standard event names and keys" which have
       # prescribed semantic meanings.
       #
       # @param [optional String] name Optional name of the event. This is
       #   required if a block is not given.
-      # @param [optional Hash<String, Object>] attributes One or more key:value
-      #   pairs, where the keys must be strings and the values may be string,
-      #   boolean or numeric type. This argument should only be used when
-      #   passing in a name.
+      # @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. This argument should only be used when passing in a name.
       # @param [optional Time] timestamp Optional timestamp for the event.
       #   This argument should only be used when passing in a name.
       #
@@ -89,6 +89,14 @@ module OpenTelemetry
         self
       end
 
+      # Record an error during the execution of this span. Multiple errors
+      # can be recorded on a span.
+      #
+      # @param [Exception] error The error to recorded
+      #
+      # @return [void]
+      def record_error(error); end
+
       # Sets the Status to the Span
       #
       # If used, this will override the default Span status. Default is OK.

data/lib/opentelemetry/trace/status.rb

@@ -4,11 +4,16 @@
 #
 # 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
     # canonical code in conjunction with an optional descriptive message.
     class Status
+      # Convenience utility, not in API spec:
+      extend Util::HttpToStatus
+
       # Retrieve the canonical code of this Status.
       #
       # @return [Integer]
@@ -21,7 +26,7 @@ module OpenTelemetry
 
       # Initialize a Status.
       #
-      # @param [Integer] canonical_code One of the standard GRPC codes: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
+      # @param [Integer] canonical_code One of the standard gRPC codes: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
       # @param [String] description
       def initialize(canonical_code, description: '')
         @canonical_code = canonical_code
@@ -36,7 +41,7 @@ module OpenTelemetry
       end
 
       # The following represents the canonical set of status codes of a
-      # finished {Span}, following the standard GRPC codes:
+      # finished {Span}, following the standard gRPC codes:
       # https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
 
       # The operation completed successfully.

data/lib/opentelemetry/trace/tracer.rb

@@ -8,11 +8,33 @@ module OpenTelemetry
   module Trace
     # No-op implementation of Tracer.
     class Tracer
-      CONTEXT_SPAN_KEY = :__span__
-      private_constant(:CONTEXT_SPAN_KEY)
+      EXTRACTED_SPAN_CONTEXT_KEY = Propagation::ContextKeys.extracted_span_context_key
+      CURRENT_SPAN_KEY = Propagation::ContextKeys.current_span_key
 
-      def current_span
-        Context.get(CONTEXT_SPAN_KEY) || Span::INVALID
+      private_constant :EXTRACTED_SPAN_CONTEXT_KEY, :CURRENT_SPAN_KEY
+
+      # Returns the current span from the current or provided context
+      #
+      # @param [optional Context] context The context to lookup the current
+      #   {Span} from. Defaults to Context.current
+      def current_span(context = Context.current)
+        context.value(CURRENT_SPAN_KEY) || Span::INVALID
+      end
+
+      # Returns the the active span context from the given {Context}, or current
+      # if one is not explicitly passed in. The active span context may refer to
+      # a {SpanContext} that has been extracted. If both a current {Span} and an
+      # extracted, {SpanContext} exist, the context of the current {Span} will be
+      # returned.
+      #
+      # @param [optional Context] context The context to lookup the active
+      #   {SpanContext} from.
+      #
+      def active_span_context(context = nil)
+        context ||= Context.current
+        context.value(CURRENT_SPAN_KEY)&.context ||
+          context.value(EXTRACTED_SPAN_CONTEXT_KEY) ||
+          SpanContext::INVALID
       end
 
       # This is a helper for the default use-case of extending the current trace with a span.
@@ -25,10 +47,19 @@ module OpenTelemetry
       #
       #   OpenTelemetry.tracer.with_span(OpenTelemetry.tracer.start_span('do-the-thing')) do ... end
       #
-      # On exit, the Span that was active before calling this method will be reactivated.
-      def in_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil, sampling_hint: nil, with_parent: nil, with_parent_context: nil)
-        span = start_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind, sampling_hint: sampling_hint, with_parent: with_parent, with_parent_context: with_parent_context)
-        with_span(span) { |s| yield s }
+      # On exit, the Span that was active before calling this method will be reactivated. If an
+      # exception occurs during the execution of the provided block, it will be recorded on the
+      # 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, with_parent_context: nil)
+        span = start_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind, with_parent: with_parent, with_parent_context: with_parent_context)
+        with_span(span) { |s, c| yield s, c }
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        span.record_error(e)
+        span.status = Status.new(Status::UNKNOWN_ERROR,
+                                 description: "Unhandled exception of type: #{e.class}")
+        raise e
       ensure
         span.finish
       end
@@ -37,11 +68,14 @@ module OpenTelemetry
       # available implicitly.
       #
       # On exit, the Span that was active before calling this method will be reactivated.
+      #
+      # @param [Span] span the span to activate
+      # @yield [span, context] yields span and a context containing the span to the block.
       def with_span(span)
-        Context.with(CONTEXT_SPAN_KEY, span) { |s| yield s }
+        Context.with_value(CURRENT_SPAN_KEY, span) { |c, s| yield s, c }
       end
 
-      def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil, sampling_hint: nil)
+      def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
         Span.new
       end
 
@@ -52,12 +86,12 @@ module OpenTelemetry
       #
       # @param [optional Span] with_parent Explicitly managed parent Span, overrides
       #   +with_parent_context+.
-      # @param [optional SpanContext] with_parent_context Explicitly managed. Overridden by
+      # @param [optional Context] with_parent_context Explicitly managed. Overridden by
       #   +with_parent+.
       #
       # @return [Span]
-      def start_span(name, with_parent: nil, with_parent_context: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil, sampling_hint: nil)
-        span_context = with_parent&.context || with_parent_context || current_span.context
+      def start_span(name, with_parent: nil, with_parent_context: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+        span_context = with_parent&.context || active_span_context(with_parent_context)
         if span_context.valid?
           Span.new(span_context: span_context)
         else

data/lib/opentelemetry/trace/tracer_provider.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # No-op implementation of a tracer provider.
+    class TracerProvider
+      # 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)
+        @tracer ||= Tracer.new
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/util/http_to_status.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    module Util
+      # Convenience methods, not necessarily required by the API specification.
+      module HttpToStatus
+        # Implemented according to
+        # https://github.com/open-telemetry/opentelemetry-specification/issues/306
+        # https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-http.md#status
+        #
+        # @param code Numeric HTTP status
+        # @return Status
+        def http_to_status(code) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+          case code.to_i
+          when 100..399
+            new(const_get(:OK))
+          when 401
+            new(const_get(:UNAUTHENTICATED))
+          when 403
+            new(const_get(:PERMISSION_DENIED))
+          when 404
+            new(const_get(:NOT_FOUND))
+          when 429
+            new(const_get(:RESOURCE_EXHAUSTED))
+          when 400..499
+            new(const_get(:INVALID_ARGUMENT))
+          when 501
+            new(const_get(:UNIMPLEMENTED))
+          when 503
+            new(const_get(:UNAVAILABLE))
+          when 504
+            new(const_get(:DEADLINE_EXCEEDED))
+          when 500..599
+            new(const_get(:INTERNAL_ERROR))
+          else
+            new(const_get(:UNKNOWN_ERROR))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/version.rb

@@ -6,5 +6,5 @@
 
 module OpenTelemetry
   ## Current OpenTelemetry version
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-13 00:00:00.000000000 Z
+date: 2020-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ipsa
@@ -143,36 +143,56 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE
+- OVERVIEW.md
+- lib/opentelemetry-api.rb
 - lib/opentelemetry.rb
 - lib/opentelemetry/context.rb
-- lib/opentelemetry/distributed_context.rb
-- lib/opentelemetry/distributed_context/distributed_context.rb
-- lib/opentelemetry/distributed_context/entry.rb
-- lib/opentelemetry/distributed_context/manager.rb
-- lib/opentelemetry/distributed_context/propagation.rb
-- lib/opentelemetry/distributed_context/propagation/binary_format.rb
-- lib/opentelemetry/distributed_context/propagation/text_format.rb
-- lib/opentelemetry/distributed_context/propagation/trace_parent.rb
+- 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/correlation_context.rb
+- lib/opentelemetry/correlation_context/builder.rb
+- lib/opentelemetry/correlation_context/manager.rb
+- lib/opentelemetry/correlation_context/propagation.rb
+- lib/opentelemetry/correlation_context/propagation/context_keys.rb
+- lib/opentelemetry/correlation_context/propagation/text_extractor.rb
+- lib/opentelemetry/correlation_context/propagation/text_injector.rb
 - lib/opentelemetry/error.rb
+- lib/opentelemetry/instrumentation.rb
+- lib/opentelemetry/instrumentation/adapter.rb
+- lib/opentelemetry/instrumentation/registry.rb
 - lib/opentelemetry/internal.rb
 - lib/opentelemetry/metrics.rb
 - lib/opentelemetry/metrics/handles.rb
 - lib/opentelemetry/metrics/instruments.rb
 - lib/opentelemetry/metrics/meter.rb
-- lib/opentelemetry/metrics/meter_factory.rb
+- lib/opentelemetry/metrics/meter_provider.rb
 - lib/opentelemetry/trace.rb
 - lib/opentelemetry/trace/event.rb
 - lib/opentelemetry/trace/link.rb
-- lib/opentelemetry/trace/sampling_hint.rb
+- lib/opentelemetry/trace/propagation.rb
+- lib/opentelemetry/trace/propagation/context_keys.rb
+- lib/opentelemetry/trace/propagation/trace_context.rb
+- lib/opentelemetry/trace/propagation/trace_context/text_extractor.rb
+- lib/opentelemetry/trace/propagation/trace_context/text_injector.rb
+- lib/opentelemetry/trace/propagation/trace_context/trace_parent.rb
 - lib/opentelemetry/trace/span.rb
 - lib/opentelemetry/trace/span_context.rb
 - lib/opentelemetry/trace/span_kind.rb
 - lib/opentelemetry/trace/status.rb
 - lib/opentelemetry/trace/trace_flags.rb
 - lib/opentelemetry/trace/tracer.rb
-- lib/opentelemetry/trace/tracer_factory.rb
+- lib/opentelemetry/trace/tracer_provider.rb
+- lib/opentelemetry/trace/util/http_to_status.rb
 - lib/opentelemetry/version.rb
 homepage: https://github.com/open-telemetry/opentelemetry-ruby
 licenses:

data/lib/opentelemetry/distributed_context.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright 2019 OpenTelemetry Authors
-#
-# SPDX-License-Identifier: Apache-2.0
-
-require 'opentelemetry/distributed_context/distributed_context'
-require 'opentelemetry/distributed_context/entry'
-require 'opentelemetry/distributed_context/manager'
-require 'opentelemetry/distributed_context/propagation'
-
-module OpenTelemetry
-  # DistributedContext is an abstract data type that represents a collection of entries. Each key of a DistributedContext is
-  # associated with exactly one value. DistributedContext is serializable, to facilitate propagating it not only inside the
-  # process but also across process boundaries. DistributedContext is used to annotate telemetry with the name:value pair
-  # Entry. Those values can be used to add dimensions to the metric or additional context properties to logs and traces.
-  module DistributedContext
-  end
-end

data/lib/opentelemetry/distributed_context/distributed_context.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright 2019 OpenTelemetry Authors
-#
-# SPDX-License-Identifier: Apache-2.0
-
-module OpenTelemetry
-  module DistributedContext
-    # An immutable implementation of the DistributedContext that does not contain any entries.
-    class DistributedContext
-      EMPTY_ENTRIES = [].freeze
-
-      private_constant(:EMPTY_ENTRIES)
-
-      def entries
-        EMPTY_ENTRIES
-      end
-
-      def [](_key)
-        nil
-      end
-    end
-  end
-end

data/lib/opentelemetry/distributed_context/entry.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright 2019 OpenTelemetry Authors
-#
-# SPDX-License-Identifier: Apache-2.0
-
-module OpenTelemetry
-  module DistributedContext
-    # An Entry consists of Entry::Metadata, Entry::Key, and Entry::Value.
-    class Entry
-      attr_reader :metadata, :key, :value
-
-      # Entry::Key is the name of the Entry. Entry::Key along with Entry::Value can be used to aggregate and group stats,
-      # annotate traces and logs, etc.
-      #
-      # Restrictions
-      # - Must contain only printable ASCII (codes between 32 and 126 inclusive)
-      # - Must have length greater than zero and less than 256.
-      # - Must not be empty.
-      class Key
-        attr_reader :name
-
-        def initialize(name)
-          raise ArgumentError unless Internal.printable_ascii?(name) && (1..255).include?(name.length)
-
-          @name = -name
-        end
-      end
-
-      # Entry::Value wraps a string. It MUST contain only printable ASCII (codes between 32 and 126).
-      class Value
-        def initialize(value)
-          raise ArgumentError unless Internal.printable_ascii?(value)
-
-          @value = -value
-        end
-
-        def to_s
-          @value
-        end
-      end
-
-      # Entry::Metadata contains properties associated with an Entry. For now only the property entry_ttl is defined.
-      # In future, additional properties may be added to address specific situations.
-      #
-      # The creator of entries determines metadata of an entry it creates.
-      class Metadata
-        attr_reader :entry_ttl
-
-        # An @see Entry with NO_PROPAGATION is considered to have local scope and is used within the process
-        # where it is created.
-        NO_PROPAGATION = 0
-
-        # An @see Entry with UNLIMITED_PROPAGATION can propagate unlimited hops. However, it is still subject
-        # to outgoing and incoming (on remote side) filter criteria.
-        UNLIMITED_PROPAGATION = -1
-
-        def initialize(entry_ttl)
-          raise ArgumentError unless entry_ttl.is_a?(Integer)
-
-          @entry_ttl = entry_ttl
-        end
-      end
-    end
-  end
-end