opentelemetry-api 0.3.0 → 0.7.0

data/lib/opentelemetry/instrumentation/registry.rb

@@ -7,79 +7,79 @@
 module OpenTelemetry
   module Instrumentation
     # The instrumentation Registry contains information about instrumentation
-    # adapters available and facilitates discovery, installation and
+    # available and facilitates discovery, installation and
     # configuration. This functionality is primarily useful for SDK
     # implementors.
     class Registry
       def initialize
         @lock = Mutex.new
-        @adapters = []
+        @instrumentation = []
       end
 
       # @api private
-      def register(adapter)
+      def register(instrumentation)
         @lock.synchronize do
-          @adapters << adapter
+          @instrumentation << instrumentation
         end
       end
 
-      # Lookup an adapter definition by name. Returns nil if +adapter_name+
+      # Lookup an instrumentation definition by name. Returns nil if +instrumentation_name+
       # is not found.
       #
-      # @param [String] adapter_name A stringified class name for an adapter
-      # @return [Adapter]
-      def lookup(adapter_name)
+      # @param [String] instrumentation_name A stringified class name for an instrumentation
+      # @return [Instrumentation]
+      def lookup(instrumentation_name)
         @lock.synchronize do
-          find_adapter(adapter_name)
+          find_instrumentation(instrumentation_name)
         end
       end
 
-      # Install the specified adapters with optionally specified configuration.
+      # Install the specified instrumentation with optionally specified configuration.
       #
-      # @param [Array<String>] adapter_names An array of adapter names to
+      # @param [Array<String>] instrumentation_names An array of instrumentation names to
       #   install
-      # @param [optional Hash<String, Hash>] adapter_config_map A map of
-      #   adapter_name to config. This argument is optional and config can be
-      #   passed for as many or as few adapters as desired.
-      def install(adapter_names, adapter_config_map = {})
+      # @param [optional Hash<String, Hash>] instrumentation_config_map A map of
+      #   instrumentation_name to config. This argument is optional and config can be
+      #   passed for as many or as few instrumentations as desired.
+      def install(instrumentation_names, instrumentation_config_map = {})
         @lock.synchronize do
-          adapter_names.each do |adapter_name|
-            adapter = find_adapter(adapter_name)
-            OpenTelemetry.logger.warn "Could not install #{adapter_name} because it was not found" unless adapter
+          instrumentation_names.each do |instrumentation_name|
+            instrumentation = find_instrumentation(instrumentation_name)
+            OpenTelemetry.logger.warn "Could not install #{instrumentation_name} because it was not found" unless instrumentation
 
-            install_adapter(adapter, adapter_config_map[adapter.name])
+            install_instrumentation(instrumentation, instrumentation_config_map[instrumentation.name])
           end
         end
       end
 
       # Install all instrumentation available and installable in this process.
       #
-      # @param [optional Hash<String, Hash>] adapter_config_map A map of
-      #   adapter_name to config. This argument is optional and config can be
-      #   passed for as many or as few adapters as desired.
-      def install_all(adapter_config_map = {})
+      # @param [optional Hash<String, Hash>] instrumentation_config_map A map of
+      #   instrumentation_name to config. This argument is optional and config can be
+      #   passed for as many or as few instrumentations as desired.
+      def install_all(instrumentation_config_map = {})
         @lock.synchronize do
-          @adapters.map(&:instance).each do |adapter|
-            install_adapter(adapter, adapter_config_map[adapter.name])
+          @instrumentation.map(&:instance).each do |instrumentation|
+            install_instrumentation(instrumentation, instrumentation_config_map[instrumentation.name])
           end
         end
       end
 
       private
 
-      def find_adapter(adapter_name)
-        @adapters.detect { |a| a.instance.name == adapter_name }
+      def find_instrumentation(instrumentation_name)
+        @instrumentation.detect { |a| a.instance.name == instrumentation_name }
                    &.instance
       end
 
-      def install_adapter(adapter, config)
-        if adapter.install(config)
-          OpenTelemetry.logger.info "Adapter: #{adapter.name} was successfully installed"
+      def install_instrumentation(instrumentation, config)
+        if instrumentation.install(config)
+          OpenTelemetry.logger.info "Instrumentation: #{instrumentation.name} was successfully installed"
         else
-          OpenTelemetry.logger.warn "Adapter: #{adapter.name} failed to install"
+          OpenTelemetry.logger.warn "Instrumentation: #{instrumentation.name} failed to install"
         end
       rescue => e # rubocop:disable Style/RescueStandardError
-        OpenTelemetry.logger.warn "Adapter: #{adapter.name} unhandled exception" \
+        OpenTelemetry.logger.warn "Instrumentation: #{instrumentation.name} unhandled exception" \
                                   "during install #{e}: #{e.backtrace}"
       end
     end

data/lib/opentelemetry/trace.rb

@@ -9,45 +9,42 @@ module OpenTelemetry
   # single logical operation, consolidated across various components of an
   # application.
   module Trace
-    # An invalid trace identifier, a 16-byte array with all zero bytes, encoded
-    # as a hexadecimal string.
-    INVALID_TRACE_ID = ('0' * 32).freeze
+    # An invalid trace identifier, a 16-byte string with all zero bytes.
+    INVALID_TRACE_ID = ("\0" * 16).b
 
-    # An invalid span identifier, an 8-byte array with all zero bytes, encoded
-    # as a hexadecimal string.
-    INVALID_SPAN_ID = ('0' * 16).freeze
+    # An invalid span identifier, an 8-byte string with all zero bytes.
+    INVALID_SPAN_ID = ("\0" * 8).b
 
-    # Generates a valid trace identifier, a 16-byte array with at least one
-    # non-zero byte, encoded as a hexadecimal string.
+    # Generates a valid trace identifier, a 16-byte string with at least one
+    # non-zero byte.
     #
-    # @return [String] a hexadecimal string encoding of a valid trace ID.
+    # @return [String] a valid trace ID.
     def self.generate_trace_id
       loop do
-        id = Random::DEFAULT.bytes(16).unpack1('H*')
+        id = Random::DEFAULT.bytes(16)
         return id unless id == INVALID_TRACE_ID
       end
     end
 
-    # Generates a valid span identifier, an 8-byte array with at least one
-    # non-zero byte, encoded as a hexadecimal string.
+    # Generates a valid span identifier, an 8-byte string with at least one
+    # non-zero byte.
     #
-    # @return [String] a hexadecimal string encoding of a valid span ID.
+    # @return [String] a valid span ID.
     def self.generate_span_id
       loop do
-        id = Random::DEFAULT.bytes(8).unpack1('H*')
+        id = Random::DEFAULT.bytes(8)
         return id unless id == INVALID_SPAN_ID
       end
     end
   end
 end
 
-require 'opentelemetry/trace/event'
 require 'opentelemetry/trace/link'
-require 'opentelemetry/trace/propagation'
 require 'opentelemetry/trace/trace_flags'
 require 'opentelemetry/trace/span_context'
 require 'opentelemetry/trace/span_kind'
 require 'opentelemetry/trace/span'
 require 'opentelemetry/trace/status'
+require 'opentelemetry/trace/propagation'
 require 'opentelemetry/trace/tracer'
 require 'opentelemetry/trace/tracer_provider'

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)
+            context.set_value(ContextKeys.current_span_key, 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
@@ -45,8 +45,7 @@ module OpenTelemetry
           private
 
           def span_context_from(context)
-            context[ContextKeys.current_span_key]&.context ||
-              context[ContextKeys.extracted_span_context_key]
+            context[ContextKeys.current_span_key]&.context
           end
         end
       end

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

@@ -25,6 +25,10 @@ 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::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
@@ -71,17 +75,17 @@ module OpenTelemetry
             end
 
             def parse_trace_id(string)
-              raise InvalidTraceIDError, string if string == OpenTelemetry::Trace::INVALID_TRACE_ID
+              raise InvalidTraceIDError, string if string == INVALID_TRACE_ID
 
               string.downcase!
-              string
+              Array(string).pack('H*')
             end
 
             def parse_span_id(string)
-              raise InvalidSpanIDError, string if string == OpenTelemetry::Trace::INVALID_SPAN_ID
+              raise InvalidSpanIDError, string if string == INVALID_SPAN_ID
 
               string.downcase!
-              string
+              Array(string).pack('H*')
             end
 
             def parse_flags(string)
@@ -102,7 +106,7 @@ module OpenTelemetry
           # converts this object into a string according to the w3c spec
           # @return [String] the serialized trace_parent
           def to_s
-            "00-#{trace_id}-#{span_id}-#{flag_string}"
+            "00-#{trace_id.unpack1('H*')}-#{span_id.unpack1('H*')}-#{flag_string}"
           end
 
           private

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

@@ -26,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 canonical status codes below
       # @param [String] description
       def initialize(canonical_code, description: '')
         @canonical_code = canonical_code
@@ -37,78 +37,20 @@ module OpenTelemetry
       #
       # @return [Boolean]
       def ok?
-        @canonical_code == OK
+        @canonical_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
+      # 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