opentelemetry-api 0.5.0 → 0.9.0

data/lib/opentelemetry/trace/link.rb

@@ -18,7 +18,7 @@ module OpenTelemetry
       # Returns the {SpanContext} for this link
       #
       # @return [SpanContext]
-      attr_reader :context
+      attr_reader :span_context
 
       # Returns the frozen attributes for this link.
       #
@@ -33,13 +33,13 @@ module OpenTelemetry
       #   frozen during Link initialization.
       # @return [Link]
       def initialize(span_context, attributes = nil)
-        @context = span_context
+        @span_context = span_context
         @attributes = attributes.freeze || EMPTY_ATTRIBUTES
       end
 
       # Returns true if two {Link}s are equal.
       def ==(other)
-        other.context == @context && other.attributes == @attributes
+        other.span_context == @span_context && other.attributes == @attributes
       end
     end
   end

data/lib/opentelemetry/trace/propagation.rb

@@ -4,7 +4,6 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry/trace/propagation/context_keys'
 require 'opentelemetry/trace/propagation/trace_context'
 
 module OpenTelemetry

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

@@ -5,8 +5,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require 'opentelemetry/trace/propagation/trace_context/trace_parent'
-require 'opentelemetry/trace/propagation/trace_context/text_extractor'
-require 'opentelemetry/trace/propagation/trace_context/text_injector'
+require 'opentelemetry/trace/propagation/trace_context/text_map_extractor'
+require 'opentelemetry/trace/propagation/trace_context/text_map_injector'
 
 module OpenTelemetry
   module Trace
@@ -16,30 +16,30 @@ module OpenTelemetry
       module TraceContext
         extend self
 
-        TEXT_EXTRACTOR = TextExtractor.new
-        TEXT_INJECTOR = TextInjector.new
-        RACK_EXTRACTOR = TextExtractor.new(
+        TEXT_MAP_EXTRACTOR = TextMapExtractor.new
+        TEXT_MAP_INJECTOR = TextMapInjector.new
+        RACK_EXTRACTOR = TextMapExtractor.new(
           traceparent_key: 'HTTP_TRACEPARENT',
           tracestate_key: 'HTTP_TRACESTATE'
         )
-        RACK_INJECTOR = TextInjector.new(
+        RACK_INJECTOR = TextMapInjector.new(
           traceparent_key: 'HTTP_TRACEPARENT',
           tracestate_key: 'HTTP_TRACESTATE'
         )
 
-        private_constant :TEXT_INJECTOR, :TEXT_EXTRACTOR,
+        private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR,
                          :RACK_INJECTOR, :RACK_EXTRACTOR
 
         # Returns an extractor that extracts context using the W3C Trace Context
         # format
-        def text_extractor
-          TEXT_EXTRACTOR
+        def text_map_extractor
+          TEXT_MAP_EXTRACTOR
         end
 
         # Returns an injector that injects context using the W3C Trace Context
         # format
-        def text_injector
-          TEXT_INJECTOR
+        def text_map_injector
+          TEXT_MAP_INJECTOR
         end
 
         # Returns an extractor that extracts context using the W3C Trace Context

data/lib/opentelemetry/trace/propagation/trace_context/{text_extractor.rb → text_map_extractor.rb}

@@ -8,15 +8,15 @@ module OpenTelemetry
     module Propagation
       module TraceContext
         # Extracts context from carriers in the W3C Trace Context format
-        class TextExtractor
+        class TextMapExtractor
           include Context::Propagation::DefaultGetter
 
-          # Returns a new TextExtractor that extracts context using the
+          # Returns a new TextMapExtractor that extracts context using the
           # specified header keys
           #
           # @param [String] traceparent_key The traceparent header key used in the carrier
           # @param [String] tracestate_key The tracestate header key used in the carrier
-          # @return [TextExtractor]
+          # @return [TextMapExtractor]
           def initialize(traceparent_key: 'traceparent',
                          tracestate_key: 'tracestate')
             @traceparent_key = traceparent_key
@@ -47,7 +47,8 @@ module OpenTelemetry
                                                   trace_flags: tp.flags,
                                                   tracestate: tracestate,
                                                   remote: true)
-            context.set_value(ContextKeys.extracted_span_context_key, span_context)
+            span = Trace::Span.new(span_context: span_context)
+            OpenTelemetry::Trace.context_with_span(span)
           rescue OpenTelemetry::Error
             context
           end

data/lib/opentelemetry/trace/propagation/trace_context/{text_injector.rb → text_map_injector.rb}

@@ -8,15 +8,15 @@ module OpenTelemetry
     module Propagation
       module TraceContext
         # Injects context into carriers using the W3C Trace Context format
-        class TextInjector
+        class TextMapInjector
           include Context::Propagation::DefaultSetter
 
-          # Returns a new TextInjector that injects context using the
+          # Returns a new TextMapInjector that injects context using the
           # specified header keys
           #
           # @param [String] traceparent_key The traceparent header key used in the carrier
           # @param [String] tracestate_key The tracestate header key used in the carrier
-          # @return [TextInjector]
+          # @return [TextMapInjector]
           def initialize(traceparent_key: 'traceparent',
                          tracestate_key: 'tracestate')
             @traceparent_key = traceparent_key
@@ -36,7 +36,7 @@ module OpenTelemetry
             return carrier unless (span_context = span_context_from(context))
 
             setter ||= DEFAULT_SETTER
-            setter.call(carrier, @traceparent_key, TraceParent.from_context(span_context).to_s)
+            setter.call(carrier, @traceparent_key, TraceParent.from_span_context(span_context).to_s)
             setter.call(carrier, @tracestate_key, span_context.tracestate) unless span_context.tracestate.nil?
 
             carrier
@@ -45,8 +45,7 @@ module OpenTelemetry
           private
 
           def span_context_from(context)
-            context[ContextKeys.current_span_key]&.context ||
-              context[ContextKeys.extracted_span_context_key]
+            OpenTelemetry::Trace.current_span(context).context
           end
         end
       end

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

@@ -25,15 +25,15 @@ module OpenTelemetry
           REGEXP = /^(?<version>[A-Fa-f0-9]{2})-(?<trace_id>[A-Fa-f0-9]{32})-(?<span_id>[A-Fa-f0-9]{16})-(?<flags>[A-Fa-f0-9]{2})(?<ignored>-.*)?$/.freeze
           private_constant :REGEXP
 
-          INVALID_TRACE_ID = OpenTelemetry::Trace::INVALID_TRACE_ID.unpack1('H*')
-          INVALID_SPAN_ID = OpenTelemetry::Trace::INVALID_SPAN_ID.unpack1('H*')
+          INVALID_TRACE_ID = OpenTelemetry::Trace::SpanContext::INVALID.hex_trace_id
+          INVALID_SPAN_ID = OpenTelemetry::Trace::SpanContext::INVALID.hex_span_id
           private_constant :INVALID_TRACE_ID, :INVALID_SPAN_ID
 
           class << self
             # Creates a new {TraceParent} from a supplied {Trace::SpanContext}
-            # @param [SpanContext] ctx The context
+            # @param [SpanContext] ctx The span context
             # @return [TraceParent] a trace parent
-            def from_context(ctx)
+            def from_span_context(ctx)
               new(trace_id: ctx.trace_id, span_id: ctx.span_id, flags: ctx.trace_flags)
             end
 

data/lib/opentelemetry/trace/span.rb

@@ -50,7 +50,7 @@ module OpenTelemetry
       # 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,44 +58,36 @@ 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/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 [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. This argument should only be used when passing in a name.
+      #   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 error during the execution of this span. Multiple errors
+      # Record an exception during the execution of this span. Multiple exceptions
       # can be recorded on a span.
       #
-      # @param [Exception] error The error to recorded
+      # @param [Exception] exception The exception to recorded
       #
       # @return [void]
-      def record_error(error); end
+      def record_exception(exception); end
 
       # Sets the Status to the Span
       #

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

@@ -9,15 +9,15 @@ 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.
+    # status 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.
+      # Retrieve the status code of this Status.
       #
       # @return [Integer]
-      attr_reader :canonical_code
+      attr_reader :code
 
       # Retrieve the description of this Status.
       #
@@ -26,10 +26,10 @@ 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] code One of the status codes below
       # @param [String] description
-      def initialize(canonical_code, description: '')
-        @canonical_code = canonical_code
+      def initialize(code, description: '')
+        @code = code
         @description = description
       end
 
@@ -37,78 +37,20 @@ module OpenTelemetry
       #
       # @return [Boolean]
       def ok?
-        @canonical_code == OK
+        @code != ERROR
       end
 
-      # The following represents the canonical set of status codes of a
-      # finished {Span}, following the standard gRPC codes:
-      # https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
+      # The following represents the set of status codes of a
+      # finished {Span}
 
       # The operation completed successfully.
       OK = 0
 
-      # The operation was cancelled (typically by the caller).
-      CANCELLED = 1
+      # The default status.
+      UNSET = 1
 
-      # An unknown error.
-      UNKNOWN_ERROR = 2
-
-      # Client specified an invalid argument. Note that this differs from
-      # {FAILED_PRECONDITION}. {INVALID_ARGUMENT} indicates arguments that are
-      # problematic regardless of the state of the system.
-      INVALID_ARGUMENT = 3
-
-      # Deadline expired before operation could complete. For operations that
-      # change the state of the system, this error may be returned even if the
-      # operation has completed successfully.
-      DEADLINE_EXCEEDED = 4
-
-      # Some requested entity (e.g., file or directory) was not found.
-      NOT_FOUND = 5
-
-      # Some entity that we attempted to create (e.g., file or directory)
-      # already exists.
-      ALREADY_EXISTS = 6
-
-      # The caller does not have permission to execute the specified operation.
-      # {PERMISSION_DENIED} must not be used if the caller cannot be identified
-      # (use {UNAUTHENTICATED} instead for those errors).
-      PERMISSION_DENIED = 7
-
-      # Some resource has been exhausted, perhaps a per-user quota, or perhaps
-      # the entire file system is out of space.
-      RESOURCE_EXHAUSTED = 8
-
-      # Operation was rejected because the system is not in a state required
-      # for the operation's execution.
-      FAILED_PRECONDITION = 9
-
-      # The operation was aborted, typically due to a concurrency issue like
-      # sequencer check failures, transaction aborts, etc.
-      ABORTED = 10
-
-      # Operation was attempted past the valid range. E.g., seeking or reading
-      # past end of file. Unlike {INVALID_ARGUMENT}, this error indicates a
-      # problem that may be fixed if the system state changes.
-      OUT_OF_RANGE = 11
-
-      # Operation is not implemented or not supported/enabled in this service.
-      UNIMPLEMENTED = 12
-
-      # Internal errors. Means some invariants expected by underlying system
-      # has been broken.
-      INTERNAL_ERROR = 13
-
-      # The service is currently unavailable. This is a most likely a transient
-      # condition and may be corrected by retrying with a backoff.
-      UNAVAILABLE = 14
-
-      # Unrecoverable data loss or corruption.
-      DATA_LOSS = 15
-
-      # The request does not have valid authentication credentials for the
-      # operation.
-      UNAUTHENTICATED = 16
+      # An error.
+      ERROR = 2
     end
   end
 end

data/lib/opentelemetry/trace/tracer.rb

@@ -8,35 +8,6 @@ module OpenTelemetry
   module Trace
     # No-op implementation of Tracer.
     class Tracer
-      EXTRACTED_SPAN_CONTEXT_KEY = Propagation::ContextKeys.extracted_span_context_key
-      CURRENT_SPAN_KEY = Propagation::ContextKeys.current_span_key
-
-      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.
       #
       # With this helper:
@@ -45,34 +16,24 @@ module OpenTelemetry
       #
       # Equivalent without helper:
       #
-      #   OpenTelemetry.tracer.with_span(OpenTelemetry.tracer.start_span('do-the-thing')) do ... end
+      #   OpenTelemetry::Trace.with_span(tracer.start_span('do-the-thing')) do ... end
       #
       # 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 }
+      def in_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil, with_parent: nil)
+        span = nil
+        span = start_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind, with_parent: with_parent)
+        Trace.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}")
+        span&.record_exception(e)
+        span&.status = Status.new(Status::ERROR,
+                                  description: "Unhandled exception of type: #{e.class}")
         raise e
       ensure
-        span.finish
-      end
-
-      # Activates/deactivates the Span within the current Context, which makes the "current span"
-      # 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_value(CURRENT_SPAN_KEY, span) { |c, s| yield s, c }
+        span&.finish
       end
 
       def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
@@ -84,14 +45,12 @@ module OpenTelemetry
       #
       # Parent context can be either passed explicitly, or inferred from currently activated span.
       #
-      # @param [optional Span] with_parent Explicitly managed parent Span, overrides
-      #   +with_parent_context+.
-      # @param [optional Context] with_parent_context Explicitly managed. Overridden by
-      #   +with_parent+.
+      # @param [optional Context] with_parent Explicitly managed parent context
       #
       # @return [Span]
-      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)
+      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
+
         if span_context.valid?
           Span.new(span_context: span_context)
         else