oboe 1.3.0

data/init.rb

@@ -0,0 +1,4 @@
+# Copyright (c) 2012 by Tracelytics, Inc.
+# All rights reserved.
+
+require 'oboe'

data/install.rb

@@ -0,0 +1 @@
+#Install hooks here

data/lib/oboe.rb

@@ -0,0 +1,13 @@
+# Copyright (c) 2012 by Tracelytics, Inc.
+# All rights reserved.
+          
+begin
+  require 'oboe_metal.so'
+  require 'rbconfig'
+  require 'oboe_metal'
+  require 'oboe/config'
+  require 'oboe/loading'
+
+rescue LoadError
+  puts "Unsupported Tracelytics environment (no libs).  Going No-op."
+end

data/lib/oboe/api.rb

@@ -0,0 +1,20 @@
+# Copyright (c) 2012 by Tracelytics, Inc.
+# All rights reserved.
+
+module Oboe
+  module API
+    def self.extend_with_tracing
+      extend Oboe::API::Logging
+      extend Oboe::API::Tracing
+      extend Oboe::API::LayerInit
+    end
+
+    def self.extend_with_noop
+      extend Oboe::API::LoggingNoop
+      extend Oboe::API::TracingNoop
+      extend Oboe::API::LayerInitNoop
+    end
+    
+    extend Oboe::API::Util
+  end
+end

data/lib/oboe/api/layerinit.rb

@@ -0,0 +1,37 @@
+module Oboe
+  module API
+    module LayerInit
+      # Internal: Report that instrumentation for the given layer has been
+      # installed, as well as the version of instrumentation and version of
+      # layer.
+      #
+      def report_init(layer)
+        platform_info                  = { '__Init' => 1 }
+        platform_info['RubyVersion']   = RUBY_VERSION
+        platform_info['RailsVersion']  = Rails.version if defined?(Rails)
+        platform_info['OboeVersion']   = Gem.loaded_specs['oboe'].try(:version).to_s
+
+        force_trace do
+          start_trace(layer, nil, platform_info) { }
+        end
+      end
+
+      def force_trace
+        saved_mode = Oboe::Config[:tracing_mode]
+        Oboe::Config[:tracing_mode] = 'always'
+        yield
+      ensure
+        Oboe::Config[:tracing_mode] = saved_mode
+      end
+    end
+
+    module LayerInitNoop
+      def report_init(layer)
+      end
+
+      def force_trace
+        yield
+      end
+    end
+  end
+end

data/lib/oboe/api/logging.rb

@@ -0,0 +1,145 @@
+# Copyright (c) 2012 by Tracelytics, Inc.
+# All rights reserved.
+
+module Oboe
+  module API
+    module Logging
+
+      # Public: Report an event in an active trace.
+      #
+      # layer - The layer the reported event belongs to
+      # label - The label for the reported event. See API documentation for
+      #         reserved labels and usage.
+      # opts - A hash containing key/value pairs that will be reported along
+      #        with this event (optional).
+      #
+      # Example
+      #
+      #   log('logical_layer', 'entry')
+      #   log('logical_layer', 'info', { :list_length => 20 })
+      #   log('logical_layer', 'exit')
+      #
+      # Returns nothing.
+      def log(layer, label, opts={})
+        log_event(layer, label, Oboe::Context.createEvent, opts)
+      end
+  
+      # Public: Report an exception.
+      #
+      # layer - The layer the reported event belongs to
+      # exn - The exception to report
+      #
+      # Example
+      #
+      #   begin
+      #     function_without_oboe()
+      #   rescue Exception => e
+      #     log_exception('rails', e)
+      #     raise
+      #   end
+      #
+      # Returns nothing.
+      def log_exception(layer, exn)
+        log(layer, 'error', {
+          :ErrorClass => exn.class.name,
+          :Message => exn.message,
+          :ErrorBacktrace => exn.backtrace.join("\r\n")
+        })
+      end
+  
+      # Public: Decide whether or not to start a trace, and report an event
+      # appropriately.
+      #
+      # layer - The layer the reported event belongs to
+      # xtrace - An xtrace metadata string, or nil.
+      # opts - A hash containing key/value pairs that will be reported along
+      #        with this event (optional).
+      #
+      # Returns nothing.
+      def log_start(layer, xtrace, opts={})
+        return if Oboe::Config.never?
+  
+        if xtrace
+          Oboe::Context.fromString(xtrace)
+        end
+  
+        if Oboe::Config.tracing?
+          log_entry(layer, opts)
+        elsif Oboe::Config.always? or Oboe::Config.sample?
+          log_event(layer, 'entry', Oboe::Context.startTrace, opts)
+        end
+      end
+  
+      # Public: Report an exit event.
+      #
+      # layer - The layer the reported event belongs to
+      #
+      # Returns an xtrace metadata string
+      def log_end(layer, opts={})
+        log_event(layer, 'exit', Oboe::Context.createEvent, opts)
+        xtrace = Oboe::Context.toString
+        Oboe::Context.clear
+        xtrace
+      end
+  
+      def log_entry(layer, opts={})
+        log_event(layer, 'entry', Oboe::Context.createEvent, opts)
+      end
+
+      def log_exit(layer, opts={})
+        log_event(layer, 'exit', Oboe::Context.createEvent, opts)
+      end
+  
+      # Internal: Report an event.
+      #
+      # layer - The layer the reported event belongs to
+      # label - The label for the reported event. See API documentation for
+      #         reserved labels and usage.
+      # opts - A hash containing key/value pairs that will be reported along
+      #        with this event (optional).
+      #
+      # Examples
+      #
+      #   entry = Oboe::Context.createEvent
+      #   log_event('rails', 'entry', exit, { :controller => 'user', :action => 'index' })
+      #   exit = Oboe::Context.createEvent
+      #   exit.addEdge(entry.getMetadata)
+      #   log_event('rails', 'exit', exit)
+      #
+      # Returns nothing.
+      def log_event(layer, label, event, opts={})
+        event.addInfo('Layer', layer.to_s)
+        event.addInfo('Label', label.to_s)
+  
+        opts.each do |k, v|
+          event.addInfo(k.to_s, v.to_s) if valid_key? k
+        end if !opts.nil? and opts.any?
+  
+        Oboe.reporter.sendReport(event)
+      end
+    end
+
+    module LoggingNoop
+      def log(layer, label, opts={})
+      end
+
+      def log_exception(layer, exn)
+      end
+
+      def log_start(layer, xtrace, opts={})
+      end
+
+      def log_end(layer, opts={})
+      end
+
+      def log_entry(layer, opts={})
+      end
+
+      def log_exit(layer, opts={})
+      end
+
+      def log_event(layer, label, event, opts={})
+      end
+    end
+  end 
+end

data/lib/oboe/api/memcache.rb

@@ -0,0 +1,29 @@
+# Copyright (c) 2012 by Tracelytics, Inc.
+# All rights reserved.
+#
+module Oboe
+  module API
+    module Memcache
+      MEMCACHE_OPS = %w{add append cas decr decrement delete fetch get get_multi incr increment prepend replace set}
+
+      def memcache_hit?(result)
+        result.nil? ? 0 : 1
+      end
+
+      def remote_host(key)
+        return unless defined?(Lib.memcached_server_by_key)\
+          and defined?(@struct) and defined?(is_unix_socket?)
+
+        server_as_array = Lib.memcached_server_by_key(@struct, args[0].to_s)
+        if server_as_array.is_a?(Array)
+          server = server_as_array.first
+          if is_unix_socket?(server)
+            return "localhost"
+          elsif defined?(server.hostname)
+            return server.hostname
+          end
+        end
+      end
+    end
+  end
+end

data/lib/oboe/api/tracing.rb

@@ -0,0 +1,146 @@
+# Copyright (c) 2012 by Tracelytics, Inc.
+# All rights reserved.
+
+module Oboe
+  module API
+    module Tracing
+
+      # Public: Trace a given block of code. Detect any exceptions thrown by
+      # the block and report errors.
+      #
+      # layer - The layer the block of code belongs to.
+      # opts - A hash containing key/value pairs that will be reported along
+      #        with the first event of this layer (optional).
+      #
+      # Example
+      #
+      #   def computation(n)
+      #     fib(n)
+      #     raise Exception.new
+      #   end
+      #
+      #   def computation_with_oboe(n)
+      #     trace('fib', { :number => n }) do
+      #       computation(n)
+      #     end
+      #   end
+      #
+      #   result = computation_with_oboe(1000)
+      #
+      # Returns the result of the block.
+      def trace(layer, opts={})
+        log_entry(layer, opts)
+        begin 
+          yield
+        rescue Exception => e
+          log_exception(layer, e)
+          raise
+        ensure
+          log_exit(layer)
+        end
+      end
+  
+      # Public: Trace a given block of code which can start a trace depending
+      # on configuration and probability. Detect any exceptions thrown by the
+      # block and report errors.
+      #
+      # When start_trace returns control to the calling context, the oboe
+      # context will be cleared.
+      #
+      # layer - The layer the block of code belongs to.
+      # opts - A hash containing key/value pairs that will be reported along
+      #        with the first event of this layer (optional).
+      #
+      # Example
+      #
+      #   def handle_request(request, response)
+      #     # ... code that modifies request and response ...
+      #   end
+      #
+      #   def handle_request_with_oboe(request, response)
+      #     result, xtrace = start_trace('rails', request['X-Trace']) do
+      #       handle_request(request, response)
+      #     end
+      #     result
+      #   rescue Exception => e
+      #     xtrace = e.xtrace
+      #   ensure
+      #     response['X-trace'] = xtrace
+      #   end
+      #
+      # Returns a list of length two, the first element of which is the result
+      # of the block, and the second element of which is the oboe context that
+      # was set when the block completed execution.
+      def start_trace(layer, xtrace, opts={})
+        log_start(layer, xtrace, opts)
+        begin
+          result = yield
+        rescue Exception => e
+          log_exception(layer, e)
+          e.instance_variable_set(:@xtrace, log_end(layer))
+          raise
+        end
+        xtrace = log_end(layer)
+
+        [result, xtrace]
+      end
+
+      # Public: Trace a given block of code which can start a trace depending
+      # on configuration and probability. Detect any exceptions thrown by the
+      # block and report errors. Insert the oboe metadata into the provided for
+      # later user.
+      # 
+      # The motivating use case for this is HTTP streaming in rails3. We need
+      # access to the exit event's trace id so we can set the header before any
+      # work is done, and before any headers are sent back to the client.
+      #
+      # layer - The layer the block of code belongs to.
+      # target - The target object in which to place the oboe metadata.
+      # opts - A hash containing key/value pairs that will be reported along
+      #        with the first event of this layer (optional).
+      #
+      # Example:
+      #
+      #   def handle_request(request, response)
+      #     # ... code that does something with request and response ...
+      #   end
+      #
+      #   def handle_request_with_oboe(request, response)
+      #     start_trace_with_target('rails', request['X-Trace'], response) do
+      #       handle_request(request, response)
+      #     end
+      #   end
+      #
+      # Returns the result of the block.
+      def start_trace_with_target(layer, xtrace, target, opts={})
+        log_start(layer, xtrace, opts)
+        exit_evt = Oboe::Context.createEvent
+        begin
+          target['X-Trace'] = exit_evt.metadataString() if Oboe::Config.tracing?
+          yield
+        rescue Exception => e
+          log_exception(layer, e)
+          raise
+        ensure
+          exit_evt.addEdge(Oboe::Context.get())
+          log_event(layer, 'exit', exit_evt)
+          Oboe::Context.clear
+        end
+      end
+    end
+
+    module TracingNoop
+      def trace(layer, opts={})
+        yield
+      end
+
+      def start_trace(layer, xtrace, opts={})
+        [yield, xtrace]
+      end
+
+      def start_trace_with_target(layer, xtrace, target, opts={})
+        yield
+      end
+    end
+  end
+end

data/lib/oboe/api/util.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2012 by Tracelytics, Inc.
+# All rights reserved.
+
+module Oboe
+  module API
+    module Util
+      BACKTRACE_CUTOFF = 100
+
+      # Internal: Check whether the provided key is reserved or not. Reserved
+      # keys are either keys that are handled by liboboe calls or the oboe gem.
+      #
+      # key - the key to check.
+      #
+      # Return a boolean indicating whether or not key is reserved.
+      def valid_key?(key)
+        !%w[ Label Layer Edge Timestamp Timestamp_u ].include? key.to_s
+      end
+
+      # Internal: Get the current backtrace.
+      #
+      # ignore - Number of frames to ignore at the end of the backtrace. Use
+      #          when you know how many layers deep in oboe the call is being
+      #          made.
+      #
+      # Returns a string with each frame of the backtrace separated by '\r\n'.
+      def backtrace(ignore=1)
+        frames = Kernel.caller
+        frames_len = frames.size
+        if frames_len - ignore > BACKTRACE_CUTOFF
+          frames[ignore, BACKTRACE_CUTOFF + ignore].unshift("...")
+        else
+          frames.drop(ignore)
+        end.join("\r\n")
+      end
+    end
+  end
+end

data/lib/oboe/config.rb

@@ -0,0 +1,39 @@
+# Copyright (c) 2012 by Tracelytics, Inc.
+# All rights reserved.
+
+module Oboe
+  # The following is done for compatability with older versions of oboe and
+  # oboe_fu (0.2.x)
+  if not defined?(Oboe::Config)
+    Config = {
+        :tracing_mode => "through",
+        :reporter_host => "127.0.0.1",
+        :sample_rate => 3e5
+    }
+  end
+
+  class << Config 
+    def always?
+      self[:tracing_mode].to_s == "always"
+    end
+  
+    def never?
+      self[:tracing_mode].to_s == "never"
+    end
+  
+    def tracing?
+      Oboe::Context.isValid and not never?
+    end
+  
+    def start?
+      not Oboe::Context.isValid and always?
+    end
+
+    def sample?
+      # Note that this the only point in the code that currently does and
+      # should ever read the sample rate. When autopilot is released, modify
+      # the line below and that line only.
+      self[:sample_rate].to_i < rand(1e6)
+    end
+  end
+end