traceview 3.0.0

data/lib/rails/generators/traceview/install_generator.rb

@@ -0,0 +1,76 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module Oboe
+  class InstallGenerator < ::Rails::Generators::Base
+    source_root File.join(File.dirname(__FILE__), 'templates')
+    desc "Copies an oboe initializer files to your application."
+
+    def copy_initializer
+      # Set defaults
+      @tracing_mode = 'through'
+      @sample_rate = '300000'
+      @verbose = 'false'
+
+      print_header
+
+      while true do
+        print_body
+
+        user_tracing_mode = ask shell.set_color "* Tracing Mode? [through]:", :yellow
+        user_tracing_mode.downcase!
+
+        break if user_tracing_mode.blank?
+        valid = ['always', 'through', 'never'].include?(user_tracing_mode)
+
+        say shell.set_color "Valid values are 'always', 'through' or 'never'", :red, :bold unless valid
+        if valid
+          @tracing_mode = user_tracing_mode
+          break
+        end
+      end
+
+      print_footer
+
+      template "oboe_initializer.rb", "config/initializers/traceview.rb"
+    end
+
+    private
+
+      def print_header
+        say ""
+        say shell.set_color "Welcome to the TraceView Ruby instrumentation setup.", :green, :bold
+        say ""
+        say "To instrument your Rails application, you can setup your tracing strategy here."
+        say ""
+        say shell.set_color "Documentation Links", :magenta
+        say "-------------------"
+        say ""
+        say "Details on configuring your sample rate:"
+        say "https://support.appneta.com/cloud/configuring-sampling"
+        say ""
+        say "More information on instrumenting Ruby applications can be found here:"
+        say "https://support.appneta.com/cloud/installing-ruby-instrumentation"
+      end
+
+      def print_body
+        say ""
+        say shell.set_color "Tracing Mode", :magenta
+        say "------------"
+        say "Tracing Mode determines when traces should be initiated for incoming requests.  Valid"
+        say "options are #{shell.set_color "always", :yellow}, #{shell.set_color "through", :yellow} (when using an instrumented Apache or Nginx) and #{shell.set_color "never", :yellow}."
+        say ""
+        say "If you're not using an instrumented Apache or Nginx, set this directive to #{shell.set_color "always", :yellow} in"
+        say "order to initiate tracing from Ruby."
+        say ""
+      end
+
+      def print_footer
+        say ""
+        say "You can change configuration values in the future by modifying config/initializers/traceview.rb"
+        say ""
+        say "Thanks! Creating the TraceView initializer..."
+        say ""
+      end
+  end
+end

data/lib/rails/generators/traceview/templates/traceview_initializer.rb

@@ -0,0 +1,159 @@
+# AppNeta TraceView Initializer (the oboe gem)
+# http://www.appneta.com/products/traceview/
+#
+# More information on instrumenting Ruby applications can be found here:
+# https://support.appneta.com/cloud/installing-ruby-instrumentation
+
+if defined?(TraceView::Config)
+  # Tracing Mode determines when traces should be initiated for incoming requests.  Valid
+  # options are always, through (when using an instrumented Apache or Nginx) and never.
+  #
+  # If you're not using an instrumented Apache or Nginx, set this directive to always in
+  # order to initiate tracing from Ruby.
+  TraceView::Config[:tracing_mode] = '<%= @tracing_mode %>'
+
+  # Verbose output of instrumentation initialization
+  # TraceView::Config[:verbose] = <%= @verbose %>
+
+  # Logging of outgoing HTTP query args
+  #
+  # This optionally disables the logging of query args of outgoing
+  # HTTP clients such as Net::HTTP, excon, typhoeus and others.
+  #
+  # This flag is global to all HTTP client instrumentation.
+  #
+  # To configure this on a per instrumentation basis, set this
+  # option to true and instead disable the instrumenstation specific
+  # option <tt>log_args</tt>:
+  #
+  #   TraceView::Config[:nethttp][:log_args] = false
+  #   TraceView::Config[:excon][:log_args] = false
+  #   TraceView::Config[:typhoeus][:log_args] = true
+  #
+  TraceView::Config[:include_url_query_params] = true
+
+  # Logging of incoming HTTP query args
+  #
+  # This optionally disables the logging of incoming URL request
+  # query args.
+  #
+  # This flag is global and currently only affects the Rack
+  # instrumentation which reports incoming request URLs and
+  # query args by default.
+  TraceView::Config[:include_remote_url_params] = true
+
+  # The oboe Ruby client has the ability to sanitize query literals
+  # from SQL statements.  By default this is disabled.  Enable to
+  # avoid collecting and reporting query literals to TraceView.
+  # TraceView::Config[:sanitize_sql] = false
+
+  # Do Not Trace
+  # These two values allow you to configure specific URL patterns to
+  # never be traced.  By default, this is set to common static file
+  # extensions but you may want to customize this list for your needs.
+  #
+  # dnt_regexp and dnt_opts is passed to Regexp.new to create
+  # a regular expression object.  That is then used to match against
+  # the incoming request path.
+  #
+  # The path string originates from the rack layer and is retrieved
+  # as follows:
+  #
+  #   req = ::Rack::Request.new(env)
+  #   path = URI.unescape(req.path)
+  #
+  # Usage:
+  #   TraceView::Config[:dnt_regexp] = "lobster$"
+  #   TraceView::Config[:dnt_opts]   = Regexp::IGNORECASE
+  #
+  # This will ignore all requests that end with the string lobster
+  # regardless of case
+  #
+  # Requests with positive matches (non nil) will not be traced.
+  # See lib/oboe/util.rb: TraceView::Util.static_asset?
+  #
+  # TraceView::Config[:dnt_regexp] = "\.(jpg|jpeg|gif|png|ico|css|zip|tgz|gz|rar|bz2|pdf|txt|tar|wav|bmp|rtf|js|flv|swf|ttf|woff|svg|less)$"
+  # TraceView::Config[:dnt_opts]   = Regexp::IGNORECASE
+
+  #
+  # Rails Exception Logging
+  #
+  # In Rails, raised exceptions with rescue handlers via
+  # <tt>rescue_from</tt> are not reported to the TraceView
+  # dashboard by default.  Setting this value to true will
+  # report all raised exception regardless.
+  #
+  # TraceView::Config[:report_rescued_errors] = false
+  #
+
+  #
+  # Enabling/Disabling Instrumentation
+  #
+  # If you're having trouble with one of the instrumentation libraries, they
+  # can be individually disabled here by setting the :enabled
+  # value to false:
+  #
+  # TraceView::Config[:action_controller][:enabled] = true
+  # TraceView::Config[:active_record][:enabled] = true
+  # TraceView::Config[:action_view][:enabled] = true
+  # TraceView::Config[:cassandra][:enabled] = true
+  # TraceView::Config[:dalli][:enabled] = true
+  # TraceView::Config[:excon][:enabled] = true
+  # TraceView::Config[:em_http_request][:enabled] = true
+  # TraceView::Config[:faraday][:enabled] = true
+  # TraceView::Config[:httpclient][:enabled] = true
+  # TraceView::Config[:memcache][:enabled] = true
+  # TraceView::Config[:memcached][:enabled] = true
+  # TraceView::Config[:mongo][:enabled] = true
+  # TraceView::Config[:moped][:enabled] = true
+  # TraceView::Config[:nethttp][:enabled] = true
+  # TraceView::Config[:redis][:enabled] = true
+  # TraceView::Config[:resque][:enabled] = true
+  # TraceView::Config[:rest_client][:enabled] = true
+  # TraceView::Config[:sequel][:enabled] = true
+  # TraceView::Config[:typhoeus][:enabled] = true
+  #
+
+  #
+  # Enabling/Disabling Backtrace Collection
+  #
+  # Instrumentation can optionally collect backtraces as they collect
+  # performance metrics.  Note that this has a negative impact on
+  # performance but can be useful when trying to locate the source of
+  # a certain call or operation.
+  #
+  # TraceView::Config[:action_controller][:collect_backtraces] = true
+  # TraceView::Config[:active_record][:collect_backtraces] = true
+  # TraceView::Config[:action_view][:collect_backtraces] = true
+  # TraceView::Config[:cassandra][:collect_backtraces] = true
+  # TraceView::Config[:dalli][:collect_backtraces] = false
+  # TraceView::Config[:excon][:collect_backtraces] = false
+  # TraceView::Config[:em_http_request][:collect_backtraces] = true
+  # TraceView::Config[:faraday][:collect_backtraces] = false
+  # TraceView::Config[:httpclient][:collect_backtraces] = false
+  # TraceView::Config[:memcache][:collect_backtraces] = false
+  # TraceView::Config[:memcached][:collect_backtraces] = false
+  # TraceView::Config[:mongo][:collect_backtraces] = true
+  # TraceView::Config[:moped][:collect_backtraces] = true
+  # TraceView::Config[:nethttp][:collect_backtraces] = true
+  # TraceView::Config[:redis][:collect_backtraces] = false
+  # TraceView::Config[:resque][:collect_backtraces] = true
+  # TraceView::Config[:rest_client][:collect_backtraces] = true
+  # TraceView::Config[:sequel][:collect_backtraces] = true
+  # TraceView::Config[:typhoeus][:collect_backtraces] = false
+  #
+
+  #
+  # Resque Options
+  #
+  # :link_workers - associates Resque enqueue operations with the jobs they queue by piggybacking
+  #                 an additional argument on the Redis queue that is stripped prior to job
+  #                 processing
+  #                 !!! Note: Make sure both the enqueue side and the Resque workers are instrumented
+  #                 before enabling this or jobs will fail !!!
+  #                 (Default: false)
+  # TraceView::Config[:resque][:link_workers] = false
+  #
+  # Set to true to disable Resque argument logging (Default: false)
+  # TraceView::Config[:resque][:log_args] = false
+end

data/lib/traceview.rb

@@ -0,0 +1,62 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+# Backward compatibility for supported environment variables
+ENV['TRACEVIEW_GEM_VERBOSE'] = ENV['OBOE_GEM_VERBOSE'] if ENV.key?('OBOE_GEM_VERBOSE')
+ENV['TRACEVIEW_GEM_TEST']    = ENV['OBOE_GEM_TEST']    if ENV.key?('OBOE_GEM_TEST')
+
+begin
+  require 'traceview/version'
+  require 'traceview/thread_local'
+  require 'traceview/logger'
+  require 'traceview/util'
+  require 'traceview/xtrace'
+  require 'traceview/support'
+
+  # If OboeHeroku is already defined then we are in a PaaS environment
+  # with an alternate metal (see the oboe-heroku gem)
+  unless defined?(OboeHeroku)
+    require 'traceview/base'
+
+    begin
+      if RUBY_PLATFORM == 'java'
+        require '/usr/local/tracelytics/tracelyticsagent.jar'
+        require 'joboe_metal'
+      else
+        require "oboe_metal.so"
+        require "oboe_metal.rb"
+      end
+    rescue LoadError
+      TraceView.loaded = false
+
+      unless ENV['RAILS_GROUP'] == 'assets' or ENV['IGNORE_TRACEVIEW_WARNING']
+        $stderr.puts '=============================================================='
+        $stderr.puts 'Missing TraceView libraries.  Tracing disabled.'
+        $stderr.puts 'See: http://bit.ly/1DaNOjw'
+        $stderr.puts '=============================================================='
+      end
+    end
+  end
+
+  require 'traceview/config'
+  require 'traceview/loading'
+
+  if TraceView.loaded
+    require 'traceview/method_profiling'
+    require 'traceview/instrumentation'
+
+    # Frameworks
+    require 'traceview/frameworks/rails'
+    require 'traceview/frameworks/sinatra'
+    require 'traceview/frameworks/padrino'
+    require 'traceview/frameworks/grape'
+  end
+
+  # Load Ruby module last.  If there is no framework detected,
+  # it will load all of the Ruby instrumentation
+  require 'traceview/ruby'
+  require 'oboe/backward_compatibility'
+rescue => e
+  $stderr.puts "[traceview/error] Problem loading: #{e.inspect}"
+  $stderr.puts e.backtrace
+end

data/lib/traceview/api.rb

@@ -0,0 +1,18 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  ##
+  # This module implements the TraceView tracing API.
+  # See: https://github.com/appneta/oboe-ruby#the-tracing-api
+  # and/or: http://rdoc.info/gems/oboe/Oboe/API/Tracing
+  module API
+    def self.extend_with_tracing
+      extend TraceView::API::Logging
+      extend TraceView::API::Tracing
+      extend TraceView::API::Profiling
+      extend TraceView::API::LayerInit
+    end
+    extend TraceView::API::Util
+  end
+end

data/lib/traceview/api/layerinit.rb

@@ -0,0 +1,51 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  module API
+    ##
+    # Provides methods related to layer initialization and reporting
+    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 = 'rack')
+        # Don't send __Init in development or test
+        return if %w(development test).include? ENV['RACK_ENV']
+
+        # Don't send __Init if the c-extension hasn't loaded
+        return unless TraceView.loaded
+
+        platform_info = TraceView::Util.build_init_report
+
+        # If already tracing, save and clear the context.  Restore it after
+        # the __Init is sent
+        context = nil
+
+        if TraceView.tracing?
+          context = TraceView::Context.toString
+          TraceView::Context.clear
+        end
+
+        start_trace(layer, nil, platform_info.merge('Force' => true)) {}
+
+        TraceView::Context.fromString(context) if context
+      end
+
+      ##
+      # force_trace has been deprecated and will be removed in a subsequent version.
+      #
+      def force_trace
+        TraceView.logger.warn 'TraceView::API::LayerInit.force_trace has been deprecated and will be ' \
+                         'removed in a subsequent version.'
+
+        saved_mode = TraceView::Config[:tracing_mode]
+        TraceView::Config[:tracing_mode] = 'always'
+        yield
+      ensure
+        TraceView::Config[:tracing_mode] = saved_mode
+      end
+    end
+  end
+end

data/lib/traceview/api/logging.rb

@@ -0,0 +1,209 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  module API
+    ##
+    # This modules provides the X-Trace logging facilities.
+    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 = {})
+        if TraceView.loaded
+          log_event(layer, label, TraceView::Context.createEvent, opts)
+        end
+      end
+
+      # Public: Report an exception.
+      #
+      # layer - The layer the reported event belongs to
+      # exn - The exception to report
+      #
+      # Example
+      #
+      #   begin
+      #     function_without_traceview()
+      #   rescue Exception => e
+      #     log_exception('rails', e)
+      #     raise
+      #   end
+      #
+      # Returns nothing.
+      def log_exception(layer, exn)
+        return if !TraceView.loaded || exn.instance_variable_get(:@oboe_logged)
+
+        kvs = { :ErrorClass => exn.class.name,
+                :ErrorMsg => exn.message,
+                :Backtrace => exn.backtrace.join("\r\n") }
+
+        exn.instance_variable_set(:@oboe_logged, true)
+        log(layer, 'error', kvs)
+      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 = nil, opts = {})
+        return if !TraceView.loaded || TraceView.never? ||
+                  (opts.key?(:URL) && ::TraceView::Util.static_asset?(opts[:URL]))
+
+        TraceView::Context.fromString(xtrace) if TraceView.pickup_context?(xtrace)
+
+        if TraceView.tracing?
+          # Pre-existing context.  Either we inherited context from an
+          # incoming X-Trace request header or under JRuby, Joboe started
+          # tracing before the JRuby code was called (e.g. Tomcat)
+          TraceView.is_continued_trace = true
+
+          if TraceView.has_xtrace_header
+            opts[:TraceOrigin] = :continued_header
+          elsif TraceView.has_incoming_context
+            opts[:TraceOrigin] = :continued_context
+          else
+            opts[:TraceOrigin] = :continued
+          end
+
+          log_entry(layer, opts)
+
+        elsif opts.key?('Force')
+          # Forced tracing: used by __Init reporting
+          opts[:TraceOrigin] = :forced
+          log_event(layer, 'entry', TraceView::Context.startTrace, opts)
+
+        elsif TraceView.sample?(opts.merge(:layer => layer, :xtrace => xtrace))
+          # Probablistic tracing of a subset of requests based off of
+          # sample rate and sample source
+          opts[:SampleRate]        = TraceView.sample_rate
+          opts[:SampleSource]      = TraceView.sample_source
+          opts[:TraceOrigin] = :always_sampled
+
+          log_event(layer, 'entry', TraceView::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 = {})
+        if TraceView.loaded
+          log_event(layer, 'exit', TraceView::Context.createEvent, opts)
+          xtrace = TraceView::Context.toString
+          TraceView::Context.clear unless TraceView.has_incoming_context?
+          xtrace
+        end
+      end
+
+      ##
+      # Public: Log an entry event
+      #
+      # A helper method to create and log an
+      # entry event
+      #
+      # Returns an xtrace metadata string
+      def log_entry(layer, kvs = {}, op = nil)
+        if TraceView.loaded
+          TraceView.layer_op = op if op
+          log_event(layer, 'entry', TraceView::Context.createEvent, kvs)
+        end
+      end
+
+      ##
+      # Public: Log an info event
+      #
+      # A helper method to create and log an
+      # info event
+      #
+      # Returns an xtrace metadata string
+      def log_info(layer, kvs = {})
+        if TraceView.loaded
+          log_event(layer, 'info', TraceView::Context.createEvent, kvs)
+        end
+      end
+
+      ##
+      # Public: Log an exit event
+      #
+      # A helper method to create and log an
+      # exit event
+      #
+      # Returns an xtrace metadata string
+      def log_exit(layer, kvs = {}, op = nil)
+        if TraceView.loaded
+          TraceView.layer_op = nil if op
+          log_event(layer, 'exit', TraceView::Context.createEvent, kvs)
+        end
+      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 = TraceView::Context.createEvent
+      #   log_event('rails', 'entry', exit, { :controller => 'user', :action => 'index' })
+      #   exit = TraceView::Context.createEvent
+      #   exit.addEdge(entry.getMetadata)
+      #   log_event('rails', 'exit', exit)
+      #
+      # Returns nothing.
+      def log_event(layer, label, event, opts = {})
+        if TraceView.loaded
+          event.addInfo('Layer', layer.to_s) if layer
+          event.addInfo('Label', label.to_s)
+
+          TraceView.layer = layer if label == 'entry'
+          TraceView.layer = nil   if label == 'exit'
+
+          opts.each do |k, v|
+            value = nil
+
+            if valid_key? k
+              if [Integer, Float, Fixnum, NilClass, String].include?(v.class)
+                value = v
+              elsif v.class == Set
+                value = v.to_a.to_s
+              else
+                value = v.to_s if v.respond_to?(:to_s)
+              end
+
+              begin
+                event.addInfo(k.to_s, value)
+              rescue ArgumentError => e
+                TraceView.logger.debug "[TraceView/debug] Couldn't add event KV: #{k.to_s} => #{v.class}"
+                TraceView.logger.debug "[TraceView/debug] #{e.message}"
+              end
+            end
+          end if !opts.nil? && opts.any?
+
+          TraceView::Reporter.sendReport(event)
+        end
+      end
+    end
+  end
+end