opentelemetry-api 0.2.0 → 0.6.0

data/lib/opentelemetry/trace/span.rb

@@ -45,12 +45,12 @@ 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.
       #
       # @param [String] key
-      # @param [String, Boolean, Numeric] value
+      # @param [String, Boolean, Numeric, Array<String, Numeric, Boolean>] value
       #
       # @return [self] returns itself
       def set_attribute(key, value)
@@ -58,37 +58,37 @@ module OpenTelemetry
       end
       alias []= set_attribute
 
-      # Add an Event to a {Span}. This can be accomplished eagerly or lazily.
-      # Lazy evaluation is useful when the event attributes are expensive to
-      # build and where the cost can be avoided for an unsampled {Span}.
+      # Add an event to a {Span}.
       #
-      # Eager example:
+      # Example:
       #
-      #   span.add_event(name: 'event', attributes: {'eager' => true})
-      #
-      # Lazy example:
-      #
-      #   span.add_event { tracer.create_event(name: 'event', attributes: {'eager' => false}) }
+      #   span.add_event('event', attributes: {'eager' => true})
       #
       # 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 [String] name Name of the event.
+      # @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.
       # @param [optional Time] timestamp Optional timestamp for the event.
-      #   This argument should only be used when passing in a name.
       #
       # @return [self] returns itself
-      def add_event(name: nil, attributes: nil, timestamp: nil)
+      def add_event(name, attributes: nil, timestamp: nil)
         self
       end
 
+      # Record an exception during the execution of this span. Multiple exceptions
+      # can be recorded on a span.
+      #
+      # @param [Exception] exception The exception to recorded
+      #
+      # @return [void]
+      def record_exception(exception); end
+
       # Sets the Status to the Span
       #
       # If used, this will override the default Span status. Default is OK.

data/lib/opentelemetry/trace/span_context.rb

@@ -11,7 +11,7 @@ module OpenTelemetry
     # {TraceFlags}, a system-specific tracestate, and a boolean indicating that the SpanContext was
     # extracted from the wire.
     class SpanContext
-      attr_reader :trace_id, :span_id, :trace_flags, :tracestate
+      attr_reader :trace_flags, :tracestate
 
       # Returns a new {SpanContext}.
       #
@@ -35,6 +35,30 @@ module OpenTelemetry
         @remote = remote
       end
 
+      # Returns the lowercase [hex encoded](https://tools.ietf.org/html/rfc4648#section-8) trace ID.
+      #
+      # @return [String] A 32-hex-character lowercase string.
+      def hex_trace_id
+        @trace_id.unpack1('H*')
+      end
+
+      # Returns the lowercase [hex encoded](https://tools.ietf.org/html/rfc4648#section-8) span ID.
+      #
+      # @return [String] A 16-hex-character lowercase string.
+      def hex_span_id
+        @span_id.unpack1('H*')
+      end
+
+      # Returns the binary representation of the trace ID.
+      #
+      # @return [String] A 16-byte binary string.
+      attr_reader :trace_id
+
+      # Returns the binary representation of the span ID.
+      #
+      # @return [String] An 8-byte binary string.
+      attr_reader :span_id
+
       # Returns true if the {SpanContext} has a non-zero trace ID and non-zero span ID.
       #
       # @return [Boolean]

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_exception(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.6.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.6.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-13 00:00:00.000000000 Z
+date: 2020-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ipsa
@@ -143,36 +143,54 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE
+- OVERVIEW.md
+- lib/opentelemetry-api.rb
 - lib/opentelemetry.rb
+- lib/opentelemetry/baggage.rb
+- lib/opentelemetry/baggage/builder.rb
+- lib/opentelemetry/baggage/manager.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/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/error.rb
-- lib/opentelemetry/internal.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_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_map_extractor.rb
+- lib/opentelemetry/trace/propagation/trace_context/text_map_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:
@@ -186,14 +204,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: A stats collection and distributed tracing framework

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