traceview 3.0.0-java

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/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

data/lib/traceview/api/memcache.rb

@@ -0,0 +1,31 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  module API
+    ##
+    # Utility methods for the Memcache instrumentation
+    module Memcache
+      MEMCACHE_OPS = %w(add append cas decr decrement delete fetch get 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) \
+          && defined?(@struct) && defined?(is_unix_socket?)
+
+        server_as_array = Lib.memcached_server_by_key(@struct, key.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/traceview/api/profiling.rb

@@ -0,0 +1,50 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  module API
+    ##
+    # Module that provides profiling of arbitrary blocks of code
+    module Profiling
+      ##
+      # Public: Profile a given block of code. Detect any exceptions thrown by
+      # the block and report errors.
+      #
+      # profile_name - A name used to identify the block being profiled.
+      # report_kvs - A hash containing key/value pairs that will be reported along
+      #              with the event of this profile (optional).
+      # with_backtrace - Boolean to indicate whether a backtrace should
+      #                  be collected with this trace event.
+      #
+      # Example
+      #
+      #   def computation(n)
+      #     TraceView::API.profile('fib', { :n => n }) do
+      #       fib(n)
+      #     end
+      #   end
+      #
+      # Returns the result of the block.
+      def profile(profile_name, report_kvs = {}, with_backtrace = false)
+        report_kvs[:Language] ||= :ruby
+        report_kvs[:ProfileName] ||= profile_name
+        report_kvs[:Backtrace] = TraceView::API.backtrace if with_backtrace
+
+        TraceView::API.log(nil, 'profile_entry', report_kvs)
+
+        begin
+          yield
+        rescue => e
+          log_exception(nil, e)
+          raise
+        ensure
+          exit_kvs = {}
+          exit_kvs[:Language] = :ruby
+          exit_kvs[:ProfileName] = report_kvs[:ProfileName]
+
+          TraceView::API.log(nil, 'profile_exit', exit_kvs)
+        end
+      end
+    end
+  end
+end

data/lib/traceview/api/tracing.rb

@@ -0,0 +1,135 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  module API
+    ##
+    # Provides the higher-level tracing interface for the 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).
+      # protect_op - specify the operation being traced.  Used to avoid
+      # double tracing between operations that call each other
+      #
+      # 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 = {}, protect_op = nil)
+        log_entry(layer, opts, protect_op)
+        begin
+          yield
+        rescue Exception => e
+          log_exception(layer, e)
+          raise
+        ensure
+          log_exit(layer, {}, protect_op)
+        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 = nil, 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 = TraceView::Context.createEvent
+        begin
+          target['X-Trace'] = TraceView::Event.metadataString(exit_evt) if TraceView.tracing?
+          yield
+        rescue Exception => e
+          log_exception(layer, e)
+          raise
+        ensure
+          exit_evt.addEdge(TraceView::Context.get)
+          log_event(layer, 'exit', exit_evt)
+          TraceView::Context.clear
+        end
+      end
+    end
+  end
+end