instana 0.15.0 → 1.0.1

data/lib/instana/tracing/processor.rb

@@ -147,21 +147,20 @@ module Instana
     # are traces that have completed but may have outstanding
     # asynchronous spans.
     #
-    # @param ids [Hash] the Trace ID and Span ID in the form of
-    #   :trace_id => 12345
-    #   :span_id => 12345
+    # @param trace_id [Integer] the Trace ID to be searched for
     #
-    def staged_trace(ids)
+    def staged_trace(trace_id)
       candidate = nil
       @staging_lock.synchronize {
         @staging_queue.each do |trace|
-          if trace.id == ids[:trace_id]
+          if trace.id == trace_id
             candidate = trace
+            break
           end
         end
       }
       unless candidate
-        ::Instana.logger.trace("Couldn't find staged trace with trace_id: #{ids[:trace_id]}")
+        ::Instana.logger.trace("Couldn't find staged trace with trace_id: #{trace_id}")
       end
       candidate
     end

data/lib/instana/tracing/span.rb

@@ -1,19 +1,187 @@
 module Instana
   class Span
+    REGISTERED_SPANS = [ :rack, :'net-http', :excon ].freeze
+    ENTRY_SPANS = [ :rack ].freeze
+    EXIT_SPANS = [ :'net-http', :excon ].freeze
+    HTTP_SPANS = ENTRY_SPANS + EXIT_SPANS
+
     attr_accessor :parent
+    attr_accessor :baggage
+
+    def initialize(name, trace_id, parent_id: nil, start_time: Time.now)
+      @data = {}
+      @data[:t] = trace_id                    # Trace ID
+      @data[:s] = ::Instana::Util.generate_id # Span ID
+      @data[:p] = parent_id if parent_id      # Parent ID
+      @data[:ta] = :ruby                      # Agent
+      @data[:data] = {}
+
+      # Entity Source
+      @data[:f] = { :e => ::Instana.agent.report_pid,
+                    :h => ::Instana.agent.agent_uuid }
+      # Start time
+      @data[:ts] = ::Instana::Util.time_to_ms(start_time)
+
+      @baggage = {}
+
+      # For entry spans, add a backtrace fingerprint
+      add_stack(limit: 2) if ENTRY_SPANS.include?(name)
+
+      # Attach a backtrace to all exit spans
+      add_stack if EXIT_SPANS.include?(name)
+
+      # Check for custom tracing
+      if REGISTERED_SPANS.include?(name.to_sym)
+        @data[:n] = name.to_sym
+      else
+        configure_custom(name)
+      end
+    end
+
+    # Adds a backtrace to this span
+    #
+    # @param limit [Integer] Limit the backtrace to the top <limit> frames
+    #
+    def add_stack(limit: nil, stack: Kernel.caller)
+      frame_count = 0
+      @data[:stack] = []
+
+      stack.each do |i|
+        # If the stack has the full instana gem version in it's path
+        # then don't include that frame. Also don't exclude the Rack module.
+        if !i.match(/instana\/instrumentation\/rack.rb/).nil? ||
+          (i.match(::Instana::VERSION_FULL).nil? && i.match('lib/instana/').nil?)
+
+          break if limit && frame_count >= limit
+
+          x = i.split(':')
+
+          @data[:stack] << {
+            :f => x[0],
+            :n => x[1],
+            :m => x[2]
+          }
+         frame_count = frame_count + 1 if limit
+        end
+      end
+    end
+
+    # Log an error into the span
+    #
+    # @param e [Exception] The exception to be logged
+    #
+    def add_error(e)
+      @data[:error] = true
+
+      if @data.key?(:ec)
+        @data[:ec] = @data[:ec] + 1
+      else
+        @data[:ec] = 1
+      end
+
+      # If a valid exception has been passed in, log the information about it
+      # In case of just logging an error for things such as HTTP client 5xx
+      # responses, an exception/backtrace may not exist.
+      if e
+        if e.backtrace.is_a?(Array)
+          add_stack(stack: e.backtrace)
+        end
+
+        if HTTP_SPANS.include?(@data[:n])
+          set_tags(:http => { :error => "#{e.class}: #{e.message}" })
+        else
+          set_tags(:log => { :message => e.message, :parameters => e.class })
+        end
+        e.instance_variable_set(:@instana_logged, true)
+      end
+      self
+    end
+
+
+    # Configure this span to be a custom span per the
+    # SDK generic span type.
+    #
+    # @param name [String] name of the span
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def configure_custom(name)
+      @data[:n] = :sdk
+      @data[:data] = { :sdk => { :name => name.to_sym } }
 
-    def initialize(data)
-      @data = data
+      #if kvs.is_a?(Hash)
+      #  @data[:data][:sdk][:type] = kvs.key?(:type) ? kvs[:type] : :local
+#
+#        if kvs.key?(:arguments)
+#          @data[:data][:sdk][:arguments] = kvs[:arguments]
+#        end
+#
+#        if kvs.key?(:return)
+#          @data[:data][:sdk][:return] = kvs[:return]
+#        end
+#        @data[:data][:sdk][:custom] = kvs unless kvs.empty?
+#      end
+      self
     end
 
+    # Closes out the span.  This difference between this and
+    # the finish method tells us how the tracing is being
+    # performed (with OpenTracing or Instana default)
+    #
+    # @param end_time [Time] custom end time, if not now
+    # @return [Span]
+    #
+    def close(end_time = Time.now)
+      unless end_time.is_a?(Time)
+        ::Instana.logger.debug "span.close: Passed #{end_time.class} instead of Time class"
+      end
+
+      @data[:d] = (::Instana::Util.time_to_ms(end_time) - @data[:ts])
+      self
+    end
+
+    #############################################################
+    # Accessors
+    #############################################################
+
+    # Retrieve the context of this span.
+    #
+    # @return [Instana::SpanContext]
+    #
+    def context
+      @context ||= ::Instana::SpanContext.new(@data[:t], @data[:s], @baggage)
+    end
+
+    # Retrieve the ID for this span
+    #
+    # @return [Integer] the span ID
     def id
       @data[:s]
     end
 
+    # Retrieve the Trace ID for this span
+    #
+    # @return [Integer] the Trace ID
+    def trace_id
+      @data[:t]
+    end
+
+    # Retrieve the parent ID of this span
+    #
+    # @return [Integer] parent span ID
     def parent_id
       @data[:p]
     end
 
+    # Set the parent ID of this span
+    #
+    # @return [Integer] parent span ID
+    def parent_id=(id)
+      @data[:p] = id
+    end
+
+    # Get the name (operation) of this Span
+    #
+    # @return [String] or [Symbol] representing the span name
     def name
       if custom?
         @data[:data][:sdk][:name]
@@ -22,32 +190,184 @@ module Instana
       end
     end
 
+    # Set the name (operation) for this Span
+    #
+    # @params name [String] or [Symbol]
+    #
+    def name=(n)
+      if custom?
+        @data[:data][:sdk][:name] = n
+      else
+        @data[:n] = n
+      end
+    end
+
+    # Get the duration value for this Span
+    #
+    # @return [Integer] the duration in milliseconds
     def duration
       @data[:d]
     end
 
+    # Indicates whether this span in the root span
+    # in the Trace
+    #
+    # @return [Boolean]
+    #
     def is_root?
       @data[:s] == @data[:t]
     end
 
+    # Hash accessor to the internal @data hash
+    #
     def [](key)
       @data[key.to_sym]
     end
 
+    # Hash setter to the internal @data hash
+    #
     def []=(key, value)
       @data[key.to_sym] = value
     end
 
+    # Hash key query to the internal @data hash
+    #
     def key?(k)
       @data.key?(k.to_sym)
     end
 
+    # Get the raw @data hash that summarizes this span
+    #
     def raw
       @data
     end
 
+    # Indicates whether this span is a custom or registered Span
     def custom?
       @data[:n] == :sdk
     end
+
+    #############################################################
+    # OpenTracing Compatibility Methods
+    #############################################################
+
+    # Set the name of the operation
+    # Spec: OpenTracing API
+    #
+    # @params name [String] or [Symbol]
+    #
+    def operation_name=(name)
+      @data[:n] = name
+    end
+
+    # Set a tag value on this span
+    # Spec: OpenTracing API
+    #
+    # @param key [String] the key of the tag
+    # @param value [String, Numeric, Boolean] the value of the tag. If it's not
+    # a String, Numeric, or Boolean it will be encoded with to_s
+    #
+    def set_tag(key, value)
+      if custom?
+        @data[:data][:sdk][:custom] ||= {}
+        @data[:data][:sdk][:custom][key] = value
+      else
+        if !@data[:data].key?(key)
+          @data[:data][key] = value
+        elsif value.is_a?(Hash) && self[:data][key].is_a?(Hash)
+          @data[:data][key].merge!(value)
+        else
+          @data[:data][key] = value
+        end
+      end
+      self
+    end
+
+    # Helper method to add multiple tags to this span
+    #
+    # @params tags [Hash]
+    # @return [Span]
+    #
+    def set_tags(tags)
+      return unless tags.is_a?(Hash)
+      tags.each do |k,v|
+        set_tag(k, v)
+      end
+      self
+    end
+
+    # Set a baggage item on the span
+    # Spec: OpenTracing API
+    #
+    # @param key [String] the key of the baggage item
+    # @param value [String] the value of the baggage item
+    def set_baggage_item(key, value)
+      @baggage ||= {}
+      @baggage[key] = value
+
+      # Init/Update the SpanContext item
+      if @context
+        @context.baggage = @baggage
+      else
+        @context ||= ::Instana::SpanContext.new(@data[:t], @data[:s], @baggage)
+      end
+      self
+    end
+
+    # Get a baggage item
+    # Spec: OpenTracing API
+    #
+    # @param key [String] the key of the baggage item
+    # @return Value of the baggage item
+    #
+    def get_baggage_item(key)
+      @baggage[key]
+    end
+
+    # Retrieve the hash of tags for this span
+    #
+    def tags(key = nil)
+      if custom?
+        tags = @data[:data][:sdk][:custom]
+      else
+        tags = @data[:data][key]
+      end
+      key ? tags[key] : tags
+    end
+
+    # Add a log entry to this span
+    # Spec: OpenTracing API
+    #
+    # @param event [String] event name for the log
+    # @param timestamp [Time] time of the log
+    # @param fields [Hash] Additional information to log
+    #
+    def log(event = nil, _timestamp = Time.now, **fields)
+      set_tags(:log => { :message => event, :parameters => fields })
+    end
+
+    # Finish the {Span}
+    # Spec: OpenTracing API
+    #
+    # @param end_time [Time] custom end time, if not now
+    #
+    def finish(end_time = Time.now)
+      unless end_time.is_a?(Time)
+        ::Instana.logger.debug "span.finish: Passed #{end_time.class} instead of Time class"
+      end
+
+      if ::Instana.tracer.current_span.id != id
+        ::Instana.logger.tracing "Closing a span that isn't active. This will result in a broken trace: #{self.inspect}"
+      end
+
+      if is_root?
+        # This is the root span for the trace.  Call log_end to close
+        # out and queue the trace
+        ::Instana.tracer.log_end(name, {}, end_time)
+      else
+        ::Instana.tracer.current_trace.end_span({}, end_time)
+      end
+      self
+    end
   end
 end

data/lib/instana/tracing/span_context.rb

@@ -0,0 +1,31 @@
+module Instana
+  class SpanContext
+    attr_accessor :trace_id
+    attr_accessor :span_id
+    attr_accessor :baggage
+
+    # Create a new SpanContext
+    #
+    # @param tid [Integer] the trace ID
+    # @param sid [Integer] the span ID
+    # @param baggage [Hash] baggage applied to this trace
+    #
+    def initialize(tid, sid, baggage = nil)
+      @trace_id = tid
+      @span_id = sid
+      @baggage = baggage
+    end
+
+    def trace_id_header
+      ::Instana::Util.id_to_header(@trace_id)
+    end
+
+    def span_id_header
+      ::Instana::Util.id_to_header(@span_id)
+    end
+
+    def to_hash
+      { :trace_id => @trace_id, :span_id => @span_id }
+    end
+  end
+end

data/lib/instana/tracing/trace.rb

@@ -1,10 +1,5 @@
 module Instana
   class Trace
-    REGISTERED_SPANS = [ :rack, :'net-http', :excon ].freeze
-    ENTRY_SPANS = [ :rack ].freeze
-    EXIT_SPANS = [ :'net-http', :excon ].freeze
-    HTTP_SPANS = ENTRY_SPANS + EXIT_SPANS
-
     # @return [Integer] the ID for this trace
     attr_reader :id
 
@@ -22,13 +17,13 @@ module Instana
     #     :span_id the ID of the parent span (must be an unsigned hex-string)
     #     :level specifies data collection level (optional)
     #
-    def initialize(name, kvs = {}, incoming_context = {})
+    def initialize(name, kvs = nil, incoming_context = {}, start_time = Time.now)
       # The collection of spans that make
       # up this trace.
       @spans = Set.new
 
       # Generate a random 64bit ID for this trace
-      @id = generate_id
+      @id = ::Instana::Util.generate_id
 
       # Indicates the time when this trace was started.  Used to timeout
       # traces that have asynchronous spans that never close out.
@@ -39,29 +34,14 @@ module Instana
 
       # This is a new trace so open the first span with the proper
       # root span IDs.
-      @current_span = Span.new({
-        :s => @id,         # Span ID
-        :ts => ts_now,     # Timestamp
-        :ta => :ruby,      # Agent
-        :f => { :e => ::Instana.agent.report_pid, :h => ::Instana.agent.agent_uuid } # Entity Source
-      })
-
-      # For entry spans, add a backtrace fingerprint
-      add_stack(2) if ENTRY_SPANS.include?(name)
-
-      # Check for custom tracing
-      if !REGISTERED_SPANS.include?(name.to_sym)
-        configure_custom_span(nil, name, kvs)
-      else
-        @current_span[:n]    = name.to_sym
-        @current_span[:data] = kvs
-      end
+      @current_span = Span.new(name, @id, start_time: start_time)
+      @current_span.set_tags(kvs) if kvs
 
       # Handle potential incoming context
-      if incoming_context.empty?
+      if !incoming_context || incoming_context.empty?
         # No incoming context. Set trace ID the same
         # as this first span.
-        @current_span[:t] = @id
+        @current_span[:s] = @id
       else
         @id = incoming_context[:trace_id]
         @current_span[:t] = incoming_context[:trace_id]
@@ -76,32 +56,22 @@ module Instana
     # @param name [String] the name of the span to start
     # @param kvs [Hash] list of key values to be reported in the span
     #
-    def new_span(name, kvs = {})
+    def new_span(name, kvs = nil, start_time = Time.now, child_of = nil)
       return unless @current_span
 
-      new_span = Span.new({
-        :s => generate_id,          # Span ID
-        :t => @id,                  # Trace ID (same as :s for root span)
-        :p => @current_span.id,     # Parent ID
-        :ts => ts_now,              # Timestamp
-        :ta => :ruby,               # Agent
-        :f => { :e => Process.pid, :h => :agent_id } # Entity Source
-      })
-
-      new_span.parent = @current_span
-      @spans.add(new_span)
-      @current_span = new_span
-
-      # Check for custom tracing
-      if !REGISTERED_SPANS.include?(name.to_sym)
-        configure_custom_span(nil, name, kvs)
+      if child_of && child_of.is_a?(::Instana::Span)
+        new_span = Span.new(name, @id, parent_id: child_of.id, start_time: start_time)
+        new_span.parent = child_of
+        new_span.baggage = child_of.baggage.dup
       else
-        @current_span[:n]    = name.to_sym
-        @current_span[:data] = kvs
+        new_span = Span.new(name, @id, parent_id: @current_span.id, start_time: start_time)
+        new_span.parent = @current_span
+        new_span.baggage = @current_span.baggage.dup
       end
+      new_span.set_tags(kvs) if kvs
 
-      # Attach a backtrace to all exit spans
-      add_stack if EXIT_SPANS.include?(name)
+      @spans.add(new_span)
+      @current_span = new_span
     end
 
     # Add KVs to the current span
@@ -139,33 +109,8 @@ module Instana
       # Return if we've already logged this exception and it
       # is just propogating up the spans.
       return if e && e.instance_variable_get(:@instana_logged)
-
       span ||= @current_span
-
-      span[:error] = true
-
-      if span.key?(:ec)
-        span[:ec] = span[:ec] + 1
-      else
-        span[:ec] = 1
-      end
-
-      # If a valid exception has been passed in, log the information about it
-      # In case of just logging an error for things such as HTTP client 5xx
-      # responses, an exception/backtrace may not exist.
-      if e
-        if e.backtrace.is_a?(Array)
-          add_backtrace_to_span(e.backtrace, nil, span)
-        end
-
-        if HTTP_SPANS.include?(span.name)
-          add_info(:http => { :error => "#{e.class}: #{e.message}" })
-        else
-          add_info(:log => { :message => e.message, :parameters => e.class })
-        end
-        e.instance_variable_set(:@instana_logged, true)
-      end
-
+      span.add_error(e)
     end
 
     # Close out the current span and set the parent as
@@ -173,20 +118,20 @@ module Instana
     #
     # @param kvs [Hash] list of key values to be reported in the span
     #
-    def end_span(kvs = {})
-      @current_span[:d] = ts_now - @current_span[:ts]
+    def end_span(kvs = {}, end_time = Time.now)
+      @current_span.close(end_time)
       add_info(kvs) if kvs && !kvs.empty?
       @current_span = @current_span.parent unless @current_span.is_root?
     end
 
     # Closes out the final span in this trace and runs any finalizer
     # steps required.
-    # This should be called only on the root span to end the trace.
+    # This should be called only when on the root span to end the trace.
     #
     # @param kvs [Hash] list of key values to be reported in the span
     #
-    def finish(kvs = {})
-      end_span(kvs)
+    def finish(kvs = {}, end_time = Time.now)
+      end_span(kvs, end_time)
     end
 
     ###########################################################################
@@ -202,77 +147,47 @@ module Instana
     # @param name [String] the name of the span to start
     # @param kvs [Hash] list of key values to be reported in the span
     #
-    def new_async_span(name, kvs)
-
-      new_span = Span.new({
-        :s => generate_id,          # Span ID
-        :t => @id,                  # Trace ID (same as :s for root span)
-        :p => @current_span.id,     # Parent ID
-        :ts => ts_now,              # Timestamp
-        :ta => :ruby,               # Agent
-        :async => true,             # Asynchonous
-        :f => { :e => Process.pid, :h => :agent_id } # Entity Source
-      })
-
+    def new_async_span(name, kvs = {})
+      new_span = Span.new(name, @id, parent_id: @current_span.id)
+      new_span.set_tags(kvs) unless kvs.empty?
       new_span.parent = @current_span
-      @has_async = true
-
-      # Check for custom tracing
-      if !REGISTERED_SPANS.include?(name.to_sym)
-        configure_custom_span(new_span, name, kvs)
-      else
-        new_span[:n]    = name.to_sym
-        new_span[:data] = kvs
-      end
-
-      # Attach a backtrace to all exit spans
-      add_stack(nil, new_span) if EXIT_SPANS.include?(name)
+      new_span[:async] = @has_async = true
 
       # Add the new span to the span collection
       @spans.add(new_span)
-
-      { :trace_id => new_span[:t], :span_id => new_span.id }
+      new_span
     end
 
     # Log info into an asynchronous span
     #
     # @param kvs [Hash] list of key values to be reported in the span
-    # @param span [Span] the span to configure
+    # @param span [Span] the span of this Async op (previously returned
+    #   from `log_async_entry`)
     #
-    def add_async_info(kvs, ids)
-      @spans.each do |span|
-        if span.id == ids[:span_id]
-          add_info(kvs, span)
-        end
-      end
+    def add_async_info(kvs, span)
+      span.set_tags(kvs)
     end
 
     # Log an error into an asynchronous span
     #
-    # @param span [Span] the span to configure
     # @param e [Exception] Add exception to the current span
+    # @param span [Span] the span of this Async op (previously returned
+    #   from `log_async_entry`)
     #
-    def add_async_error(e, ids)
-      @spans.each do |span|
-        add_error(e, span) if span.id == ids[:span_id]
-      end
+    def add_async_error(e, span)
+      span.add_error(e)
     end
 
     # End an asynchronous span
     #
     # @param name [Symbol] the name of the span
     # @param kvs [Hash] list of key values to be reported in the span
-    # @param ids [Hash] the Trace ID and Span ID in the form of
-    #   :trace_id => 12345
-    #   :span_id => 12345
+    # @param span [Span] the span of this Async op (previously returned
+    #   from `log_async_entry`)
     #
-    def end_async_span(kvs = {}, ids)
-      @spans.each do |span|
-        if span.id == ids[:span_id]
-          span[:d] = ts_now - span[:ts]
-          add_info(kvs, span) unless kvs.empty?
-        end
-      end
+    def end_async_span(kvs = {}, span)
+      span.set_tags(kvs) unless kvs.empty?
+      span.close
     end
 
     ###########################################################################
@@ -290,6 +205,7 @@ module Instana
           return false
         end
       end
+      true
     end
 
     # Indicates if every span of this trace has completed.  Useful when
@@ -327,6 +243,14 @@ module Instana
       false
     end
 
+    # Get the current span.
+    #
+    # @return [Span]
+    #
+    def current_span
+      @current_span
+    end
+
     # Get the ID of the current span for this trace.
     # Used often to place in HTTP response headers.
     #
@@ -379,53 +303,7 @@ module Instana
     #
     def configure_custom_span(span, name, kvs = {})
       span ||= @current_span
-
-      span[:n] = :sdk
-      span[:data] = { :sdk => { :name => name.to_sym } }
-      span[:data][:sdk][:type] = kvs.key?(:type) ? kvs[:type] : :local
-
-      if kvs.key?(:arguments)
-        span[:data][:sdk][:arguments] = kvs[:arguments]
-      end
-
-      if kvs.key?(:return)
-        span[:data][:sdk][:return] = kvs[:return]
-      end
-      span[:data][:sdk][:custom] = kvs unless kvs.empty?
-      #span[:data][:sdk][:custom][:tags] = {}
-      #span[:data][:sdk][:custom][:logs] = {}
-    end
-
-    # Locates the span in the current_trace or
-    # in the staging queue.  This is generally used by async
-    # operations.
-    #
-    # @param ids [Hash] the Trace ID and Span ID in the form of
-    #   :trace_id => 12345
-    #   :span_id => 12345
-    #
-    # @return [Span]
-    #
-    def find_span(ids)
-      if ids[:trace_id] == @id
-        @spans.each do |s|
-          return s if s[:s] == ids[:span_id]
-        end
-      else
-        #::Instana.processor.staged_trace(
-      end
-    end
-
-    # Adds a backtrace to the passed in span or on @current_span if not.
-    #
-    # @param limit [Integer] Limit the backtrace to the top <limit> frames
-    # @param span [Span] the span to add the backtrace to or if unspecified
-    #   the current span
-    #
-    def add_stack(limit = nil, span = nil)
-      span ||= @current_span
-
-      add_backtrace_to_span(Kernel.caller, limit, span)
+      span.configure_custom(name, kvs)
     end
 
     # Adds the passed in backtrace to the specified span.  Backtrace can be one
@@ -459,22 +337,5 @@ module Instana
         end
       end
     end
-
-    # Get the current time in milliseconds
-    #
-    # @return [Integer] the current time in milliseconds
-    #
-    def ts_now
-      (Time.now.to_f * 1000).floor
-    end
-
-    # Generate a random 64bit ID
-    #
-    # @return [Integer] a random 64bit integer
-    #
-    def generate_id
-      # Max value is 9223372036854775807 (signed long in Java)
-      rand(-2**63..2**63-1)
-    end
   end
 end