lightstep 0.12.0 → 0.16.1

data/lib/lightstep/reporter.rb

@@ -57,7 +57,10 @@ module LightStep
 
       span_records = @span_records.slice!(0, @span_records.length)
       dropped_spans = 0
-      @dropped_spans.update{|old| dropped_spans = old; 0 }
+      @dropped_spans.update do |old|
+        dropped_spans = old
+        0
+      end
 
       report_request = {
         runtime: @runtime,
@@ -65,9 +68,10 @@ module LightStep
         youngest_micros: now,
         span_records: span_records,
         internal_metrics: {
-	  counts: [
-	    {name: "spans.dropped", int64_value: dropped_spans},
-	  ]
+          counts: [{
+            name: 'spans.dropped',
+            int64_value: dropped_spans
+          }]
         }
       }
 
@@ -75,9 +79,10 @@ module LightStep
 
       begin
         @transport.report(report_request)
-      rescue
-	# an error occurs, add the previous dropped_spans and count of spans
-	# that would have been recorded
+      rescue StandardError => e
+        LightStep.logger.error "LightStep error reporting to collector: #{e.message}"
+        # an error occurs, add the previous dropped_spans and count of spans
+        # that would have been recorded
         @dropped_spans.increment(dropped_spans + span_records.length)
       end
     end
@@ -103,8 +108,8 @@ module LightStep
             sleep(@period)
             flush
           end
-        rescue => ex
-          # TODO: internally log the exception
+        rescue StandardError => e
+          LightStep.logger.error "LightStep failed to report spans: #{e.message}"
         end
       end
     end

data/lib/lightstep/scope.rb

@@ -0,0 +1,23 @@
+module LightStep
+  # Scope represents an OpenTracing Scope
+  #
+  # See http://www.opentracing.io for more information.
+  class Scope
+    attr_reader :span
+
+    def initialize(manager:, span:, finish_on_close: true)
+      @manager = manager
+      @span = span
+      @finish_on_close = finish_on_close
+    end
+
+    # Mark the end of the active period for the current thread and Scope,
+    # updating the ScopeManager#active in the process.
+    def close
+      raise(LightStep::Error, 'already closed') if @closed
+      @closed = true
+      @span.finish if @finish_on_close
+      @manager.deactivate
+    end
+  end
+end

data/lib/lightstep/scope_manager.rb

@@ -0,0 +1,54 @@
+module LightStep
+  # ScopeManager represents an OpenTracing ScopeManager
+  #
+  # See http://www.opentracing.io for more information.
+  #
+  # The ScopeManager interface abstracts both the activation of Span instances
+  # via ScopeManager#activate and access to an active Span/Scope via
+  # ScopeManager#active
+  #
+  class ScopeManager
+    # Make a span instance active.
+    #
+    # @param span [Span] the Span that should become active
+    # @param finish_on_close [Boolean] whether the Span should automatically be
+    #   finished when Scope#close is called
+    # @return [Scope] instance to control the end of the active period for the
+    #  Span. It is a programming error to neglect to call Scope#close on the
+    #  returned instance.
+    def activate(span:, finish_on_close: true)
+      return active if active && active.span == span
+      LightStep::Scope.new(manager: self, span: span, finish_on_close: finish_on_close).tap do |scope|
+        add_scope(scope)
+      end
+    end
+
+    # @return [Scope] the currently active Scope which can be used to access the
+    # currently active Span.
+    #
+    # If there is a non-null Scope, its wrapped Span becomes an implicit parent
+    # (as Reference#CHILD_OF) of any newly-created Span at Tracer#start_active_span
+    # or Tracer#start_span time.
+    def active
+      scopes.last
+    end
+
+    def deactivate
+      scopes.pop
+    end
+
+    private
+
+    def scopes
+      Thread.current[object_id.to_s] || []
+    end
+
+    def add_scope(scope)
+      if Thread.current[object_id.to_s].nil?
+        Thread.current[object_id.to_s] = [scope]
+      else
+        Thread.current[object_id.to_s] << scope
+      end
+    end
+  end
+end

data/lib/lightstep/span.rb

@@ -11,7 +11,10 @@ module LightStep
 
     # Internal use only
     # @private
-    attr_reader :start_micros, :end_micros, :tags, :operation_name, :span_context
+    attr_reader :start_micros, :end_micros, :tags, :operation_name, :context
+
+    # To keep backwards compatibility
+    alias_method :span_context, :context
 
     # Creates a new {Span}
     #
@@ -37,8 +40,9 @@ module LightStep
       tags: nil,
       max_log_records:
     )
+
       @tags = Concurrent::Hash.new
-      @tags.update(tags) unless tags.nil?
+      @tags.update(tags.each { |k, v| tags[k] = v.to_s }) unless tags.nil?
       @log_records = Concurrent::Array.new
       @dropped_logs = Concurrent::AtomicFixnum.new
       @max_log_records = max_log_records
@@ -49,14 +53,18 @@ module LightStep
 
       ref = child_of ? child_of : references
       ref = ref[0] if (Array === ref)
-      ref = ref.span_context if (Span === ref)
+      ref = ref.context if (Span === ref)
 
       if SpanContext === ref
-        @span_context = SpanContext.new(id: LightStep.guid, trace_id: ref.trace_id)
+        @context = SpanContext.new(
+          id: LightStep.guid,
+          trace_id: ref.trace_id,
+          trace_id_upper64: ref.trace_id_upper64,
+          sampled: ref.sampled?)
         set_baggage(ref.baggage)
         set_tag(:parent_span_guid, ref.id)
       else
-        @span_context = SpanContext.new(id: LightStep.guid, trace_id: LightStep.guid)
+        @context = SpanContext.new(id: LightStep.guid, trace_id: LightStep.guid)
       end
     end
 
@@ -76,10 +84,12 @@ module LightStep
     # @param key [String] the key of the baggage item
     # @param value [String] the value of the baggage item
     def set_baggage_item(key, value)
-      @span_context = SpanContext.new(
-        id: span_context.id,
-        trace_id: span_context.trace_id,
-        baggage: span_context.baggage.merge({key => value})
+      @context = SpanContext.new(
+        id: context.id,
+        trace_id: context.trace_id,
+        trace_id_upper64: context.trace_id_upper64,
+        sampled: context.sampled?,
+        baggage: context.baggage.merge({key => value})
       )
       self
     end
@@ -87,9 +97,11 @@ module LightStep
     # Set all baggage at once. This will reset the baggage to the given param.
     # @param baggage [Hash] new baggage for the span
     def set_baggage(baggage = {})
-      @span_context = SpanContext.new(
-        id: span_context.id,
-        trace_id: span_context.trace_id,
+      @context = SpanContext.new(
+        id: context.id,
+        trace_id: context.trace_id,
+        trace_id_upper64: context.trace_id_upper64,
+        sampled: context.sampled?,
         baggage: baggage
       )
     end
@@ -98,25 +110,38 @@ module LightStep
     # @param key [String] the key of the baggage item
     # @return Value of the baggage item
     def get_baggage_item(key)
-      span_context.baggage[key]
+      context.baggage[key]
     end
 
+    # @deprecated Use {#log_kv} instead.
     # Add a log entry to this span
     # @param event [String] event name for the log
     # @param timestamp [Time] time of the log
-    # @param fields [Hash] Additional information to log
+    # @param fields [Hash{Symbol=>Object}] Additional information to log
     def log(event: nil, timestamp: Time.now, **fields)
+      warn 'Span#log is deprecated. Please use Span#log_kv instead.'
       return unless tracer.enabled?
 
       fields = {} if fields.nil?
       unless event.nil?
 	fields[:event] = event.to_s
       end
+
+      log_kv(timestamp: timestamp, **fields)
+    end
+
+    # Add a log entry to this span
+    # @param timestamp [Time] time of the log
+    # @param fields [Hash{Symbol=>Object}] Additional information to log
+    def log_kv(timestamp: Time.now, **fields)
+      return unless tracer.enabled?
+
+      fields = {} if fields.nil?
       record = {
         timestamp_micros: LightStep.micros(timestamp),
-        fields: fields.to_a.map {|key, value|
-          {Key: key.to_s, Value: value.to_s}
-        },
+        fields: fields.to_a.map do |key, value|
+          { Key: key.to_s, Value: value.to_s }
+        end
       }
 
       log_records.push(record)
@@ -140,8 +165,8 @@ module LightStep
     def to_h
       {
         runtime_guid: tracer.guid,
-        span_guid: span_context.id,
-        trace_guid: span_context.trace_id,
+        span_guid: context.id,
+        trace_guid: context.trace_id,
         span_name: operation_name,
         attributes: tags.map {|key, value|
           {Key: key.to_s, Value: value}

data/lib/lightstep/span_context.rb

@@ -1,12 +1,45 @@
+#frozen_string_literal: true
+
 module LightStep
   # SpanContext holds the data for a span that gets inherited to child spans
   class SpanContext
-    attr_reader :id, :trace_id, :baggage
+    attr_reader :id, :trace_id, :trace_id_upper64, :sampled, :baggage
+    alias_method :trace_id64, :trace_id
+    alias_method :sampled?, :sampled
+
+    ZERO_PADDING = '0' * 16
 
-    def initialize(id:, trace_id:, baggage: {})
+    def initialize(id:, trace_id:, trace_id_upper64: nil, sampled: true, baggage: {})
       @id = id.freeze
-      @trace_id = trace_id.freeze
+      @trace_id = truncate_id(trace_id).freeze
+      @trace_id_upper64 = trace_id_upper64 || extended_bits(trace_id).freeze
+      @sampled = sampled
       @baggage = baggage.freeze
     end
+
+    # Lazily initializes and returns a 128-bit representation of a 64-bit trace id
+    def trace_id128
+      @trace_id128 ||= "#{trace_id_upper64 || ZERO_PADDING}#{trace_id}"
+    end
+
+    # Returns true if the original trace_id was 128 bits
+    def id_truncated?
+      !@trace_id_upper64.nil?
+    end
+
+    private
+
+    # Truncates an id to 64 bits
+    def truncate_id(id)
+      return id unless id && id.size == 32
+      id[16..-1]
+    end
+
+    # Returns the most significant 64 bits of a 128 bit id or nil if the id
+    # is 64 bits
+    def extended_bits(id)
+      return unless id && id.size == 32
+      id[0...16]
+    end
   end
 end

data/lib/lightstep/tracer.rb

@@ -5,6 +5,7 @@ require 'opentracing'
 
 require 'lightstep/span'
 require 'lightstep/reporter'
+require 'lightstep/propagation'
 require 'lightstep/transport/http_json'
 require 'lightstep/transport/nil'
 require 'lightstep/transport/callback'
@@ -14,6 +15,11 @@ module LightStep
     class Error < LightStep::Error; end
     class ConfigurationError < LightStep::Tracer::Error; end
 
+    DEFAULT_MAX_LOG_RECORDS = 1000
+    MIN_MAX_LOG_RECORDS = 1
+    DEFAULT_MAX_SPAN_RECORDS = 1000
+    MIN_MAX_SPAN_RECORDS = 1
+
     attr_reader :access_token, :guid
 
     # Initialize a new tracer. Either an access_token or a transport must be
@@ -22,10 +28,20 @@ module LightStep
     # @param access_token [String] The project access token when pushing to LightStep
     # @param transport [LightStep::Transport] How the data should be transported
     # @param tags [Hash] Tracer-level tags
+    # @param propagator [Propagator] Symbol one of :lightstep, :b3 indicating the propagator
+    #   to use
     # @return LightStep::Tracer
     # @raise LightStep::ConfigurationError if the group name or access token is not a valid string.
-    def initialize(component_name:, access_token: nil, transport: nil, tags: {})
-      configure(component_name: component_name, access_token: access_token, transport: transport, tags: tags)
+    def initialize(component_name:,
+                   access_token: nil,
+                   transport: nil,
+                   tags: {},
+                   propagator: :lightstep)
+      configure(component_name: component_name,
+                access_token: access_token,
+                transport: transport,
+                tags: tags,
+                propagator: propagator)
     end
 
     def max_log_records
@@ -53,6 +69,83 @@ module LightStep
 
     # TODO(bhs): Support FollowsFrom and multiple references
 
+    # Creates a scope manager or returns the already-created one.
+    #
+    # @return [ScopeManager] the current ScopeManager, which may be a no-op but
+    #   may not be nil.
+    def scope_manager
+      @scope_manager ||= LightStep::ScopeManager.new
+    end
+
+    # Returns a newly started and activated Scope.
+    #
+    # If ScopeManager#active is not nil, no explicit references are provided,
+    # and `ignore_active_scope` is false, then an inferred References#CHILD_OF
+    # reference is created to the ScopeManager#active's SpanContext when
+    # start_active_span is invoked.
+    #
+    # @param operation_name [String] The operation name for the Span
+    # @param child_of [SpanContext, Span] SpanContext that acts as a parent to
+    #        the newly-started Span. If a Span instance is provided, its
+    #        context is automatically substituted. See [Reference] for more
+    #        information.
+    #
+    #   If specified, the `references` parameter must be omitted.
+    # @param references [Array<Reference>] An array of reference
+    #   objects that identify one or more parent SpanContexts.
+    # @param start_time [Time] When the Span started, if not now
+    # @param tags [Hash] Tags to assign to the Span at start time
+    # @param ignore_active_scope [Boolean] whether to create an implicit
+    #   References#CHILD_OF reference to the ScopeManager#active.
+    # @param finish_on_close [Boolean] whether span should automatically be
+    #   finished when Scope#close is called
+    # @yield [Scope] If an optional block is passed to start_active_span it will
+    #   yield the newly-started Scope. If `finish_on_close` is true then the
+    #   Span will be finished automatically after the block is executed.
+    # @return [Scope, Object] If passed an optional block, start_active_span
+    #   returns the block's return value, otherwise it returns the newly-started
+    #   and activated Scope
+    def start_active_span(operation_name,
+                          child_of: nil,
+                          references: nil,
+                          start_time: Time.now,
+                          tags: nil,
+                          ignore_active_scope: false,
+                          finish_on_close: true)
+      if child_of.nil? && references.nil? && !ignore_active_scope
+        child_of = active_span
+      end
+
+      span = start_span(
+        operation_name,
+        child_of: child_of,
+        references: references,
+        start_time: start_time,
+        tags: tags,
+        ignore_active_scope: ignore_active_scope
+      )
+
+      scope_manager.activate(span: span, finish_on_close: finish_on_close).tap do |scope|
+        if block_given?
+          begin
+            return yield scope
+          ensure
+            scope.close
+          end
+        end
+      end
+    end
+
+    # Returns the span from the active scope, if any.
+    #
+    # @return [Span, nil] the active span. This is a shorthand for
+    #   `scope_manager.active.span`, and nil will be returned if
+    #   Scope#active is nil.
+    def active_span
+      scope = scope_manager.active
+      scope.span if scope
+    end
+
     # Starts a new span.
     #
     # @param operation_name [String] The operation name for the Span
@@ -64,10 +157,21 @@ module LightStep
     #         are provided, their .span_context is automatically substituted.
     # @param start_time [Time] When the Span started, if not now
     # @param tags [Hash] Tags to assign to the Span at start time
-    # @return [Span]
-    def start_span(operation_name, child_of: nil, references: [], start_time: nil, tags: nil)
+    # @param ignore_active_scope [Boolean] whether to create an implicit
+    #   References#CHILD_OF reference to the ScopeManager#active.
+    # @yield [Span] If passed an optional block, start_span will yield the
+    #   newly-created span to the block. The span will be finished automatically
+    #   after the block is executed.
+    # @return [Span, Object] If passed an optional block, start_span will return
+    #  the block's return value, otherwise it returns the newly-started Span
+    #  instance, which has not been automatically registered via the
+    #  ScopeManager
+    def start_span(operation_name, child_of: nil, references: nil, start_time: nil, tags: nil, ignore_active_scope: false)
+      if child_of.nil? && references.nil? && !ignore_active_scope
+        child_of = active_span
+      end
 
-      Span.new(
+      span_options = {
         tracer: self,
         operation_name: operation_name,
         child_of: child_of,
@@ -75,25 +179,27 @@ module LightStep
         start_micros: start_time.nil? ? LightStep.micros(Time.now) : LightStep.micros(start_time),
         tags: tags,
         max_log_records: max_log_records,
-      )
+      }
+
+      Span.new(span_options).tap do |span|
+        if block_given?
+          begin
+            return yield span
+          ensure
+            span.finish
+          end
+        end
+      end
     end
 
+
     # Inject a SpanContext into the given carrier
     #
     # @param spancontext [SpanContext]
     # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY]
     # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
     def inject(span_context, format, carrier)
-      case format
-      when OpenTracing::FORMAT_TEXT_MAP
-        inject_to_text_map(span_context, carrier)
-      when OpenTracing::FORMAT_BINARY
-        warn 'Binary inject format not yet implemented'
-      when OpenTracing::FORMAT_RACK
-        inject_to_rack(span_context, carrier)
-      else
-        warn 'Unknown inject format'
-      end
+      @propagator.inject(span_context, format, carrier)
     end
 
     # Extract a SpanContext from a carrier
@@ -101,18 +207,7 @@ module LightStep
     # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
     # @return [SpanContext] the extracted SpanContext or nil if none could be found
     def extract(format, carrier)
-      case format
-      when OpenTracing::FORMAT_TEXT_MAP
-        extract_from_text_map(carrier)
-      when OpenTracing::FORMAT_BINARY
-        warn 'Binary join format not yet implemented'
-        nil
-      when OpenTracing::FORMAT_RACK
-        extract_from_rack(carrier)
-      else
-        warn 'Unknown join format'
-        nil
-      end
+      @propagator.extract(format, carrier)
     end
 
     # @return true if the tracer is enabled
@@ -149,8 +244,12 @@ module LightStep
 
     protected
 
-    def configure(component_name:, access_token: nil, transport: nil, tags: {})
-      raise ConfigurationError, "component_name must be a string" unless String === component_name
+    def configure(component_name:,
+                  access_token: nil,
+                  transport: nil, tags: {},
+                  propagator: :lightstep)
+
+      raise ConfigurationError, "component_name must be a string" unless component_name.is_a?(String)
       raise ConfigurationError, "component_name cannot be blank"  if component_name.empty?
 
       if transport.nil? and !access_token.nil?
@@ -160,6 +259,8 @@ module LightStep
       raise ConfigurationError, "you must provide an access token or a transport" if transport.nil?
       raise ConfigurationError, "#{transport} is not a LightStep transport class" if !(LightStep::Transport::Base === transport)
 
+      @propagator = Propagation[propagator]
+
       @guid = LightStep.guid
 
       @reporter = LightStep::Reporter.new(
@@ -170,75 +271,5 @@ module LightStep
         tags: tags
       )
     end
-
-    private
-
-    CARRIER_TRACER_STATE_PREFIX = 'ot-tracer-'.freeze
-    CARRIER_BAGGAGE_PREFIX = 'ot-baggage-'.freeze
-
-    CARRIER_SPAN_ID = (CARRIER_TRACER_STATE_PREFIX + 'spanid').freeze
-    CARRIER_TRACE_ID = (CARRIER_TRACER_STATE_PREFIX + 'traceid').freeze
-    CARRIER_SAMPLED = (CARRIER_TRACER_STATE_PREFIX + 'sampled').freeze
-
-    DEFAULT_MAX_LOG_RECORDS = 1000
-    MIN_MAX_LOG_RECORDS = 1
-    DEFAULT_MAX_SPAN_RECORDS = 1000
-    MIN_MAX_SPAN_RECORDS = 1
-
-    def inject_to_text_map(span_context, carrier)
-      carrier[CARRIER_SPAN_ID] = span_context.id
-      carrier[CARRIER_TRACE_ID] = span_context.trace_id unless span_context.trace_id.nil?
-      carrier[CARRIER_SAMPLED] = 'true'
-
-      span_context.baggage.each do |key, value|
-        carrier[CARRIER_BAGGAGE_PREFIX + key] = value
-      end
-    end
-
-    def extract_from_text_map(carrier)
-      # If the carrier does not have both the span_id and trace_id key
-      # skip the processing and just return a normal span
-      if !carrier.has_key?(CARRIER_SPAN_ID) || !carrier.has_key?(CARRIER_TRACE_ID)
-        return nil
-      end
-
-      baggage = carrier.reduce({}) do |baggage, tuple|
-        key, value = tuple
-        if key.start_with?(CARRIER_BAGGAGE_PREFIX)
-          plain_key = key.to_s[CARRIER_BAGGAGE_PREFIX.length..key.to_s.length]
-          baggage[plain_key] = value
-        end
-        baggage
-      end
-      SpanContext.new(
-        id: carrier[CARRIER_SPAN_ID],
-        trace_id: carrier[CARRIER_TRACE_ID],
-        baggage: baggage,
-      )
-    end
-
-    def inject_to_rack(span_context, carrier)
-      carrier[CARRIER_SPAN_ID] = span_context.id
-      carrier[CARRIER_TRACE_ID] = span_context.trace_id unless span_context.trace_id.nil?
-      carrier[CARRIER_SAMPLED] = 'true'
-
-      span_context.baggage.each do |key, value|
-        if key =~ /[^A-Za-z0-9\-_]/
-          # TODO: log the error internally
-          next
-        end
-        carrier[CARRIER_BAGGAGE_PREFIX + key] = value
-      end
-    end
-
-    def extract_from_rack(env)
-      extract_from_text_map(env.reduce({}){|memo, tuple|
-        raw_header, value = tuple
-        header = raw_header.gsub(/^HTTP_/, '').gsub("_", "-").downcase
-
-        memo[header] = value if header.start_with?(CARRIER_TRACER_STATE_PREFIX, CARRIER_BAGGAGE_PREFIX)
-        memo
-      })
-    end
   end
 end