splunk-tracer 0.1.0

data/lib/splunktracing/scope.rb

@@ -0,0 +1,23 @@
+module SplunkTracing
+  # 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(SplunkTracing::Error, 'already closed') if @closed
+      @closed = true
+      @span.finish if @finish_on_close
+      @manager.deactivate
+    end
+  end
+end

data/lib/splunktracing/scope_manager.rb

@@ -0,0 +1,54 @@
+module SplunkTracing
+  # 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
+      SplunkTracing::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/splunktracing/span.rb

@@ -0,0 +1,191 @@
+require 'concurrent'
+require 'splunktracing/span_context'
+
+module SplunkTracing
+  # Span represents an OpenTracer Span
+  #
+  # See http://www.opentracing.io for more information.
+  class Span
+    # Part of the OpenTracing API
+    attr_writer :operation_name
+
+    # Internal use only
+    # @private
+    attr_reader :start_micros, :end_micros, :tags, :operation_name, :context
+
+    # To keep backwards compatibility
+    alias_method :span_context, :context
+
+    # Creates a new {Span}
+    #
+    # @param tracer [Tracer] the tracer that created this span
+    # @param operation_name [String] the operation name of this span. If it's
+    #        not a String it will be encoded with to_s.
+    # @param child_of [SpanContext] the parent SpanContext (per child_of)
+    # @param references [Array<SpanContext>] An array of SpanContexts
+    #   that identify what Spans this Span follows from causally. Presently
+    #   only one reference is supported, and cannot be provided in addition to
+    #   a child_of.
+    # @param start_micros [Numeric] start time of the span in microseconds
+    # @param tags [Hash] initial key:value tags (per set_tag) for the Span
+    # @param max_log_records [Numeric] maximum allowable number of log records
+    #        for the Span
+    # @return [Span] a started Span
+    def initialize(
+      tracer:,
+      operation_name:,
+      child_of: nil,
+      references: [],
+      start_micros:,
+      tags: nil,
+      max_log_records:
+    )
+
+      @tags = Concurrent::Hash.new
+      @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
+
+      @tracer = tracer
+      self.operation_name = operation_name.to_s
+      self.start_micros = start_micros
+
+      ref = child_of ? child_of : references
+      ref = ref[0] if (Array === ref)
+      ref = ref.context if (Span === ref)
+
+      if SpanContext === ref
+        @context = SpanContext.new(id: SplunkTracing.guid, trace_id: ref.trace_id, parent_id: ref.id)
+        set_baggage(ref.baggage)
+        # set_tag(:parent_span_guid, ref.id)
+      else
+        @context = SpanContext.new(id: SplunkTracing.guid, trace_id: SplunkTracing.guid)
+      end
+    end
+
+    # Set a tag value on this span
+    # @param key [String] the key of the tag
+    # @param value [String] the value of the tag. If it's not a String
+    # it will be encoded with to_s
+    def set_tag(key, value)
+      tags[key] = value.to_s
+      self
+    end
+
+    # TODO(ngauthier@gmail.com) baggage keys have a restricted format according
+    # to the spec: http://opentracing.io/documentation/pages/spec#baggage-vs-span-tags
+
+    # Set a baggage item on the span
+    # @param key [String] the key of the baggage item
+    # @param value [String] the value of the baggage item
+    def set_baggage_item(key, value)
+      @context = SpanContext.new(
+        id: context.id,
+        trace_id: context.trace_id,
+        parent_id: context.parent_id,
+        baggage: context.baggage.merge({key => value})
+      )
+      self
+    end
+
+    # 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 = {})
+      @context = SpanContext.new(
+        id: context.id,
+        trace_id: context.trace_id,
+        parent_id: context.parent_id,
+        baggage: baggage
+      )
+    end
+
+    # Get a baggage item
+    # @param key [String] the key of the baggage item
+    # @return Value of the baggage item
+    def get_baggage_item(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
+    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
+
+    def log_kv(timestamp: Time.now, **fields)
+      return unless tracer.enabled?
+
+      fields = {} if fields.nil?
+      record = {
+        timestamp_micros: SplunkTracing.micros(timestamp),
+        fields: fields,
+      }
+
+      log_records.push(record)
+      if log_records.size > @max_log_records
+        log_records.shift
+        dropped_logs.increment
+      end
+    end
+
+    # Finish the {Span}
+    # @param end_time [Time] custom end time, if not now
+    def finish(end_time: Time.now)
+      if end_micros.nil?
+        self.end_micros = SplunkTracing.micros(end_time)
+      end
+      tracer.finish_span(self)
+      self
+    end
+
+    # Hash representation of a span
+    def to_h
+      if end_micros.nil?
+        self.end_micros = SplunkTracing.micros(Time.now)
+      end
+      {
+        guid: tracer.guid,
+        span_id: context.id,
+        trace_id: context.trace_id,
+        parent_span_id: context.parent_id,
+        operation_name: operation_name,
+        tags: tags,
+        timestamp: start_micros/1000000.0,
+        duration: end_micros-start_micros,
+        error_flag: false,
+        dropped_logs: dropped_logs_count,
+        log_records: log_records,
+        baggage: context.baggage
+      }
+    end
+
+    # Internal use only
+    # @private
+    def dropped_logs_count
+      dropped_logs.value
+    end
+
+    # Internal use only
+    # @private
+    def logs_count
+      log_records.size
+    end
+
+    private
+
+    attr_reader :tracer, :dropped_logs, :log_records
+    attr_writer :start_micros, :end_micros
+  end
+end

data/lib/splunktracing/span_context.rb

@@ -0,0 +1,13 @@
+module SplunkTracing
+  # SpanContext holds the data for a span that gets inherited to child spans
+  class SpanContext
+    attr_reader :id, :trace_id, :parent_id, :baggage
+
+    def initialize(id:, trace_id:, parent_id: nil, baggage: {})
+      @id = id.freeze
+      @trace_id = trace_id.freeze
+      @parent_id = parent_id.freeze
+      @baggage = baggage.freeze
+    end
+  end
+end

data/lib/splunktracing/tracer.rb

@@ -0,0 +1,321 @@
+require 'json'
+require 'concurrent'
+
+require 'opentracing'
+
+require 'splunktracing/span'
+require 'splunktracing/reporter'
+require 'splunktracing/transport/http_json'
+require 'splunktracing/transport/nil'
+require 'splunktracing/transport/callback'
+
+module SplunkTracing
+  class Tracer
+    class Error < SplunkTracing::Error; end
+    class ConfigurationError < SplunkTracing::Tracer::Error; end
+
+    attr_reader :access_token, :guid
+
+    # Initialize a new tracer. Either an access_token or a transport must be
+    # provided. A component_name is always required.
+    # @param component_name [String] Component name to use for the tracer
+    # @param access_token [String] The project access token when pushing to SplunkTracing
+    # @param transport [SplunkTracing::Transport] How the data should be transported
+    # @param tags [Hash] Tracer-level tags
+    # @return SplunkTracing::Tracer
+    # @raise SplunkTracing::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)
+    end
+
+    def max_log_records
+      @max_log_records ||= DEFAULT_MAX_LOG_RECORDS
+    end
+
+    def max_log_records=(max)
+      @max_log_records = [MIN_MAX_LOG_RECORDS, max].max
+    end
+
+    def max_span_records
+      @max_span_records ||= DEFAULT_MAX_SPAN_RECORDS
+    end
+
+    def max_span_records=(max)
+      @max_span_records = [MIN_MAX_SPAN_RECORDS, max].max
+      @reporter.max_span_records = @max_span_records
+    end
+
+    # Set the report flushing period. If set to 0, no flushing will be done, you
+    # must manually call flush.
+    def report_period_seconds=(seconds)
+      @reporter.period = seconds
+    end
+
+    # 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 ||= SplunkTracing::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 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] 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?
+          yield scope
+          scope.close
+        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
+    # @param child_of [SpanContext] SpanContext that acts as a parent to
+    #        the newly-started Span. If a Span instance is provided, its
+    #        .span_context is automatically substituted.
+    # @param references [Array<SpanContext>] An array of SpanContexts that
+    #         identify any parent SpanContexts of newly-started Span. If Spans
+    #         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
+    # @param ignore_active_scope [Boolean] whether to create an implicit
+    #   References#CHILD_OF reference to the ScopeManager#active.
+    # @return [Span]
+    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(
+        tracer: self,
+        operation_name: operation_name,
+        child_of: child_of,
+        references: references,
+        start_micros: start_time.nil? ? SplunkTracing.micros(Time.now) : SplunkTracing.micros(start_time),
+        tags: tags,
+        max_log_records: max_log_records,
+      )
+    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
+    end
+
+    # Extract a SpanContext from a carrier
+    # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
+    # @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
+    end
+
+    # @return true if the tracer is enabled
+    def enabled?
+      return @enabled if defined?(@enabled)
+      @enabled = true
+    end
+
+    # Enables the tracer
+    def enable
+      @enabled = true
+    end
+
+    # Disables the tracer
+    # @param discard [Boolean] whether to discard queued data
+    def disable(discard: true)
+      @enabled = false
+      @reporter.clear if discard
+      @reporter.flush
+    end
+
+    # Flush to the Transport
+    def flush
+      return unless enabled?
+      @reporter.flush
+    end
+
+    # Internal use only.
+    # @private
+    def finish_span(span)
+      return unless enabled?
+      @reporter.add_span(span)
+    end
+
+    protected
+
+    def configure(component_name:, access_token: nil, transport: nil, tags: {})
+      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?
+        transport = Transport::HTTPJSON.new(access_token: access_token)
+      end
+
+      raise ConfigurationError, "you must provide an access token or a transport" if transport.nil?
+      raise ConfigurationError, "#{transport} is not a SplunkTracing transport class" if !(SplunkTracing::Transport::Base === transport)
+
+      @guid = SplunkTracing.guid
+
+      @reporter = SplunkTracing::Reporter.new(
+        max_span_records: max_span_records,
+        transport: transport,
+        guid: guid,
+        component_name: component_name,
+        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.to_s.gsub(/^HTTP_/, '').tr('_', '-').downcase
+
+        memo[header] = value if header.start_with?(CARRIER_TRACER_STATE_PREFIX, CARRIER_BAGGAGE_PREFIX)
+        memo
+      })
+    end
+  end
+end