Ruby support matrix

Ruby versions

JRuby
1.6.8
JRuby
1.7.x
JRuby
9.0.x.x
Ruby
1.8.7
Ruby
1.9.2
Ruby
1.9.3
Ruby
2.0.x
Ruby
2.1.x
Ruby
2.2.x
Ruby
2.3.0

Ruby frameworks

Merb
1.1.0+
Rails
2.3 - 5.x
RailsLTS
2.3+
Grape
Sinatra
Padrino

Ruby background jobs

DelayedJob
3.0.5+
Sidekiq
2.11.2+
Resque

Ruby http clients

curb
0.8.6+
excon
0.17.0+
Faraday
0.7.6+
HTTParty
via Net::HTTP
HTTPClient
2.2.0+
RestClient
1.6.3+
Typhoeus
0.6.2+
Net::HTTP

Ruby RabbitMQ clients

Bunny
0.9.0+

Installing instrumentation

Installing ruby instrumentation

Instrumentation for the ruby language and ruby on rails framework is provided as a gem called ‘traceview’. The traceview gem is hosted on RubyGems, making installation as simple as: gem install traceview. Our ruby extension gets detailed insights out-of-the-box without any code modification. For a list of instrumented components see platform and component support. If you have code or a library that is not on the list, use our public API to customize.

Troubleshooting installation

The message ‘Unsupported TraceView environment. Tracing disabled’ often means that the traceview gem couldn’t load the core c extension that is built on gem install. The traceview gem uses a standard ruby c extension as an interface to liboboe. This is often attributed to missing packages on the host. For each host you wish to generate traces from, make sure to have the liboboe and liboboe-dev packages installed. See the installation overview. After you have confirmed that all of the base packages are installed correctly, you can force the traceview gem to re-link to the new libraries: gem pristine traceview. This will restore the gem to freshly installed state and rebuild the c extension. Make sure to run pristine on the gem that is applicable to your application. For example, if you are using bundler and a local private bundle of gems, run the pristine command from your application directory: bundle exec gem pristine traceview. If you’re seeing this message in unexpected places such as on your development machine, you can disable this message by setting the environment variable IGNORE_TRACEVIEW_WARNING=1..

The message ‘Unsupported TraceView environment (no libs). Going No-op.’ means that the gem was installed in an unsupported environment or Tracelyzer is not installed. When this occurs, your application will function normally, but tracing will be disabled until the TracelyTo remedy this, make sure that your platform is supported and that you have the base TraceView packages installed on that host. See installation overview. Once that is addressed, you can force a rebuild of the traceview gem by running: gem pristine traceview or alternatively if you’re using bundler: bundle exec gem pristine traceview.

Instrumenting ruby on rails

The traceview gem is aware of rails and many rails components. Out-of-box it captures controllers and actions for requests, memcache operations, net-http requests, active record queries, and more.

  • For rails 3 and 4 you can include the instrumentation in your Rails 3 or Rails 4 app by adding gem 'traceview' to the gemfile for bundler and then running bundle install.
  • For rails 2 install the traceview gem and then add the gem config.gem "traceview" to config/environment.rb.

The traceview gem supports the use of a rails initializer for cases where you need to adjust the tracing config but don’t have an instrumented web server in front of your app; see configuring ruby instrumentation for a list of configuration options. This initializer can be generated automatically by running the built-in traceview install generator: bundle exec rails generate traceview:install. It prompts for details about your setup and places a generated initializer in RAILS_ROOT/config/initializers/traceview.rb. If for some reason you can’t run the traceview install generator, you can use this file as a template for your own initializer.

Instrumenting sinatra

You can instrument your sinatra application by adding the following code to your config.ru rackup file. With this, the traceview gem automatically detects sinatra on boot and instruments key components. Make sure that the traceview gem is loaded after sinatra either by listing gem 'traceview' after sinatra in your gemfile or calling the require 'traceview' directive after sinatra is loaded.

 1 # If you're not using Bundler.require.  Make sure this is done
 2 # after the Sinatra require directive.
 3 require 'traceview'
 4 
 5 # When traces should be initiated for incoming requests. Valid options are
 6 # "always", "through" (when the request is initiated with a tracing header
 7 # from upstream) and "never". You must set this directive to "always" in
 8 # order to initiate tracing.
 9 TraceView::Config[:tracing_mode] = 'through'
10 
11 # You may want to replace the TraceView.logger with whichever logger you are using
12 # TraceView.logger = Sinatra.logger

Instrumenting merb

If you have a rackup file, you can instrument your merb app by adding the following code to config.ru. The traceview gem will then automatically detect merb on boot and instrument key components. Make sure that the traceview gem is loaded after merb either by listing gem ‘traceview’ after merb in your gemfile or calling the require ‘traceview’ directive after merb is loaded.

1 require 'traceview'
2 require 'traceview/inst/rack'
3 
4 TraceView::Config[:tracing_mode] = 'always'
5 TraceView::Config[:verbose] = true
6 
7 use ::TraceView::Rack

Instrumenting grape

You can instrument your grape application by adding the following code to your config.ru rackup file. Make sure that the traceview gem is loaded after grape either by listing gem ‘traceview’ after grape in your gemfile or calling the require ‘traceview’ directive after grape is loaded. You must explicitly tell your grape application to use TraceView::Rack for tracing to occur.

 1 # If you're not using Bundler.require.  Make sure this is done
 2 # after the Grape require directive.
 3 require 'traceview'
 4 
 5 # When traces should be initiated for incoming requests. Valid options are
 6 # "always", "through" (when the request is initiated with a tracing header
 7 # from upstream) and "never". You must set this directive to "always" in
 8 # order to initiate tracing.
 9 TraceView::Config[:tracing_mode] = 'through'
10   ...
11 class App < Grape::API
12   use TraceView::Rack
13 end

Instrumenting padrino

As long as the traceview gem is in your gemfile, inserted after the gem 'padrino' directive, and you are calling Bundler.require, the traceview gem automatically instruments padrino applications. If you need to adjust the tracing config on stack boot, you can do so by adding the following to your config/boot.rb file.

1 Padrino.before_load do
2   # When traces should be initiated for incoming requests. Valid options are
3   # "always", "through" (when the request is initiated with a tracing header
4   # from upstream) and "never". You must set this directive to "always" in
5   # order to initiate tracing.
6   TraceView::Config[:tracing_mode] = 'always'
7 end

Instrumenting rails metal controllers

You can instrument your ruby on rails metal controllers by adding the following code to the bottom of your metal controller declaration. Add a profile_method line for every method you want to instrument.

1 class MetalController > ActionController::Metal
2   def index
3     self.response_body = 'Hello Metal!'
4   end
5 end
6 
7 opts = {}
8 opts[:backtrace] = true
9 TraceView::API.profile_method(MetalController, :index, opts)

Instrumenting ruby scripts

To use the traceview gem for non-ruby on rails applications, e.g., ruby scripts and applications not built on rails, run the following code at start-up to load the gem, initialize it, and instrument supported libraries. This code assumes that the traceview gem installed as described above, you’re using bundler and the traceview gem is already added to your gemfile.

1 require 'rubygems'
2 require 'bundler'
3 
4 Bundler.require
5 
6 require 'traceview'

Upgrading instrumentation

Our TraceView ruby library is managed by the gem command regardless of platform. To check for updates to our ruby gem:

  1. Display installed version: gem list traceview.
  2. Check for the latest version online: gem search traceview --remote.
  3. If your version numbers match you’re all up to date! Otherwise upgrade: gem update traceview.

Configuring instrumentation

The TraceView gem uses a nested hash to store configuration values in TraceView::Config. Each key/value pair represents a config option. Most accept only ‘true’ or ‘false’, making config changes a simple operation. For ruby on rails applications, setting these values are usually done in a rails initializer.

This section contains the following sub-sections:

    Disable tracing for static files

    By default, the TraceView gem doesn’t trace routes with extensions for common static files like images, javascript, pdfs, and text files. This is done by testing candidate urls against a regular expression stored in TraceView::Config[:dnt_regexp]. You can update the regular expression string if for example you want your javascript and css files instrumented. In this case, simply remove ‘js’ and ‘css from the pattern.

    1 .(jpg|jpeg|gif|png|ico|zip|tgz|gz|rar|bz2|pdf|txt|tar|wav|bmp|rtf|flv|swf|ttf|woff|svg|less)$

    If you prefer to not instrument any javascript files except for one named show.js, you could put this assignment into your initializer, rackup file, or application.rb.

    1 TraceView::Config[:dnt_regexp] = "(\.js$)(?<!show.js)"

    Our instrumentation uses the standard ruby regexp class so you can use any regexp supported pattern. See the documentation on ruby regexp or reference the TraceView gem source code documentation for this feature.

    Suppress reporting for sensitive data

    The TraceView gem has the ability to sanitize sql database queries in case you don’t want query parameters displayed on your dashboard. By default this functionality is disabled, but set TraceView::Config[:sanitize_sql] to ‘true’ and the instrumentation will stop collecting and reporting query parameters. The strings which become off limits are specified by regular expression that you may customize via TraceView::Config[:sanitize_sql_regexp] and TraceView::Config[:sanitize_sql_opts]. Our instrumentation uses the standard ruby regexp class so you can use any regexp supported pattern. See the documentation on ruby regexp or reference the TraceView gem source code documentation for this feature.

    By default url query args are reported for both incoming urls and outgoing calls to remote services. Set TraceView::Config[:include_url_query_params] to ‘false’ and instrumentation will stop collecting and reporting query args from incoming urls. Set TraceView::Config[:include_remote_url_params] to ‘false’ and instrumentation will stop collecting and reporting query args from outgoing calls to remote services.

    Enable verbose logging

    Enable verbose logging by setting TraceView::Config[:verbose] to true. For rails this is usually done in the TraceView initializer config/initializers/traceview.rb. If you don’t have this file, you can generate one using the built-in generator: bundle exec rails generator traceview:install. For Sinatra and Padrino, this is usually done in the rackup or application file. Once enabled, verbose logging will have output similar to the following. Note that under certain setups, this output may be put into the application log files.

     1 $ bundle exec rails server
     2 => Booting Thin
     3 => Rails 3.2.13 application starting in development on http://0.0.0.0:3000
     4 => Call with -d to detach
     5 => Ctrl-C to shutdown server
     6 [traceview/loading] Instrumenting redis
     7 [traceview/loading] Instrumenting em-http-request
     8 ...
     9 TraceView gem 3.0.0 successfully loaded.
    10 Thin web server (v1.6.3 codename Protein Powder)
    11 Maximum connections set to 1024
    12 Listening on 0.0.0.0:3000, CTRL+C to stop

    Complete config options

    The following is the complete list of ruby instrumentation configuration options. It has been compiled from the TraceView gem source code, which you can find here.


      TraceView::Config[:dnt_regexp]

      config option
      TraceView::Config[:dnt_regexp]
      description
      Turn off tracing for requests containing the specified url pattern. By default, this is set to common static file extensions but you may customize this list. Our instrumentation uses the standard ruby regexp class so you can use any regexp supported pattern. See the documentation on ruby regexp or reference the TraceView gem source code documentation for this feature.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.10.
      example
      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)$"
      related options
      TraceView::Config[:dnt_opts]

      TraceView::Config[:dnt_opts]

      config option
      TraceView::Config[:dnt_opts]
      description
      The dnt_regexp uses the standard regexp class method, which accepts several options; Regexp::IGNORECASE is the default.
      history
      • The namespace changed from oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.10.
      example
      TraceView::Config[:dnt_opts] = Regexp::IGNORECASE
      related options
      TraceView::Config[:dnt_regexp]

      TraceView::Config[:include_remote_url_params]

      config option
      TraceView::Config[:include_remote_url_params]
      description
      Enable/disable reporting for arguments within remote service calls. A remote service all might be curl, thrift, or any other rpc/http transport. This flag is global and affects the following instrumentation, which collect outgoing request urls and arguments by default: nethttp, excon, faraday, rest-client, typhoeus, rack.
      history
      • The namespace changed from oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.17.
      related options
      TraceView::Config[:include_url_query_params]

      TraceView::Config[:include_url_query_params]

      config option
      TraceView::Config[:include_url_query_params]
      description
      Enable/disable reporting of url query arguments. This flag is global and affects the following instrumentation instrumentation, which report request urls and query arguments by default: nethttp, excon, faraday, rest-client, typhoeus, rack.
      history
      • The namespace changed from oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.17.
      related options
      TraceView::Config[:include_remote_url_params]

      TraceView::Config[:report_rescued_errors]

      config option
      TraceView::Config[:report_rescued_errors]
      description
      In rails, raised exceptions with rescue handlers via rescue_from are not reported to TraceView by default. Set to ‘true’ to report all raised exceptions.
      history
      • The namespace changed from ‘Oboe’ to ‘TraceView’ in 3.0.0.
      • Introduced with the original ruby instrumentation.

      TraceView::Config[:sanitize_sql]

      config option
      TraceView::Config[:sanitize_sql]
      description
      The TraceView Ruby gem has the ability to sanitize query literals from sql statements. By default this is disabled. Set to ‘true’ to avoid collecting and reporting query literals to TraceView. See also do not report sql query literals.
      history
      • The namespace changed from ‘Oboe’ to ‘TraceView’ in 3.0.0.
      • Introduced in oboe 2.2.6.
      related options

      TraceView::Config[:sanitize_sql_regexp]

      config option
      TraceView::Config[:sanitize_sql_regexp]
      description
      Customize the regular expression used to sanitize sql statements. See do not report sql query literals.
      history
      Introduced in oboe 3.0.4.
      example
      TraceView::Config[:sanitize_sql_regexp] = '(\'[\s\S][^\']*\'|\d*\.\d+|\d+|NULL)'
      related options

      TraceView::Config[:sanitize_sql_opts]

      config option
      TraceView::Config[:sanitize_sql_opts]
      description
      When set to ‘true’, sanitize_sql avoids collecting and reporting query literals from sql statements. The strings which become off limits are specified as a regular expression via sanitize_sql_regexp. Ruby instrumentation uses the standard regexp class method which accepts several options; Regexp::IGNORECASE is the default.
      history
      Introduced in oboe 3.0.4.
      example
      TraceView::Config[:sanitize_sql_opts] = Regexp::IGNORECASE
      related options

      TraceView::Config[:tracing_mode]

      config option
      TraceView::Config[:tracing_mode]
      description
      Determine when traces should be initiated for incoming requests.
      possible values
      always
      (Default) Continue existing traces, otherwise attempt to start a new one.
      through
      Continue existing traces, but never start them. This mode assumes that a higher layer makes the decision about whether to trace.
      never
      Never continue existing traces or start new ones.
      history
      • The namespace changed from ‘Oboe’ to ‘TraceView’ in 3.0.0.
      • Introduced with the original ruby instrumentation.
      example
      TraceView::Config[:tracing_mode] = 'always'
      notes
      You only need to configure the tracing mode if you are not running an instrumented webserver in front of your application. In this case, set to ‘always’.

      TraceView::Config[:verbose]

      config option
      TraceView::Config[:verbose]
      description
      Output more information than usual during gem initialization, information that could be helpful for investigating configuration issues.
      history
      • The namespace changed from ‘Oboe’ to ‘TraceView’ in 3.0.0.
      • Introduced with the original ruby instrumentation.

      TraceView::Config[:action_controller]

      config option
      TraceView::Config[:action_controller]
      description
      Enable/disable action controller instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from ‘Oboe’ to ‘TraceView’ in 3.0.0.
      • [:collect_backtraces] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:active_record]

      config option
      TraceView::Config[:active_record]
      description
      Enable/disable active record instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from ‘Oboe’ to ‘TraceView’ in 3.0.0.
      • [:collect_backtraces] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:action_view]

      config option
      TraceView::Config[:action_view]
      description
      Enable/disable action view instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from ‘Oboe’ to ‘TraceView’ in 3.0.0.
      • [:collect_backtraces] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:bunnyclient]

      config option
      TraceView::Config[:bunnyclient]
      description
      Enable/disable bunny client instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      Introduced in oboe 3.6.0.

      TraceView::Config[:bunnyconsumer]

      config option
      TraceView::Config[:bunnyconsumer]
      description
      Enable/disable bunny consumer instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:action]
      Bunny instrumentation can optionally report controller/action values so that bunny message handling can be filtered in TraceView. Identify which property of Bunny::MessageProperties to report as the controller. The default is :app_id.
      [:controller]
      Bunny instrumentation can optionally report controller/action values so that bunny message handling can be filtered in TraceView. Identify which property of Bunny::MessageProperties to report as the action. The default is :type.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      Introduced in oboe 3.6.0.

      TraceView::Config[:cassandra]

      config option
      TraceView::Config[:cassandra]
      description
      Enable/disable cassandra driver instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • [:backtrace_collection] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:curb]

      config option
      TraceView::Config[:curb]
      description
      Curb is built on top of libcurl, but TraceView also provides separate libcurl instrumentation. Because of this potential conflict, the curb instrumentation is disabled by default. If libcurl instrumentation is not installed, then use this config option to enable the curb client so that you can trace across external layers. Alternatively, you can install libcurl instrumentation. parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:cross_host]
      Set to ‘true’ to enable cross-host tracing. Default is ‘false’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      Introduced with [:cross_host] in TraceView 3.0.1.

      TraceView::Config[:dalli]

      config option
      TraceView::Config[:dalli]
      description
      Enable/disabled dalli instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from oboe to TraceView in 3.0.0.
      • [:backtrace_collection] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:delayed_jobclient]

      config option
      TraceView::Config[:delayed_jobclient]
      description
      Configure delayedjob client instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      Introduced in TraceView 3.4.0.

      TraceView::Config[:delayed_jobworker]

      config option
      TraceView::Config[:delayed_jobworker]
      description
      Configure delayedjob worker instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      Introduced in TraceView 3.4.0.

      TraceView::Config[:excon]

      config option
      TraceView::Config[:excon]
      description
      Enable/disable excon instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.16.

      TraceView::Config[:em_http_request]

      config option
      TraceView::Config[:em_http_request]
      description
      Enable/disable em-http-request instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.1.

      TraceView::Config[:faraday]

      config option
      TraceView::Config[:faraday]
      description
      Enable/disable faraday instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.2.

      TraceView::Config[:httpclient]

      config option
      TraceView::Config[:httpclient]
      description
      Enable/disable httpclient instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.17.

      TraceView::Config[:memcache]

      config option
      TraceView::Config[:memcache]
      description
      Enable/disable memcache instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • [:backtrace_collection] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:memcached]

      config option
      TraceView::Config[:memcached]
      description
      Enable/disable memcached instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • [:backtrace_collection] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:mongo]

      config option
      TraceView::Config[:mongo]
      description
      Enable/disable mongo driver instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • [:backtrace_collection] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:moped]

      config option
      TraceView::Config[:moped]
      description
      Enable/disable moped instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • [:backtrace_collection] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:nethttp]

      config option
      TraceView::Config[:nethttp]
      description
      Enable/disable nethttp instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • [:backtrace_collection] introduced in oboe 2.3.2.
      • Introduced with [:enabled] in oboe 1.4.0.

      TraceView::Config[:redis]

      config option
      TraceView::Config[:redis]
      description
      Enable/disable redis instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.5.0.

      TraceView::Config[:resqueclient]

      config option
      TraceView::Config[:resqueclient]
      description
      Configure resque client instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • Changed [:resque] to [resqueclient] in TraceView 3.3.3.
      • Removed [:link_workers] in TraceView 3.0.0.
      • The namespace changed from ‘Oboe’ to ‘TraceView’ in 3.0.0.
      • Added [:collect_backtraces] in oboe 2.3.2.
      • Introduced in oboe 1.4.0.

      TraceView::Config[:resqueworker]

      config option
      TraceView::Config[:resqueworker]
      description
      Configure resque worker instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      Introduced in TraceView 3.3.3.

      TraceView::Config[:rest_client]

      config option
      TraceView::Config[:rest_client]
      description
      Enable/disable sequel instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.16.

      TraceView::Config[:sequel]

      config option
      TraceView::Config[:sequel]
      description
      Enable/disable sequel instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.7.

      TraceView::Config[:sidekiqclient]

      config option
      TraceView::Config[:sidekiqclient]
      description
      Enable/disable sidekiq client instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      Introduced in TraceView 3.3.0.

      TraceView::Config[:sidekiqworker]

      config option
      TraceView::Config[:sidekiqworker]
      description
      Enable/disable sidekiq worker instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      Introduced in TraceView 3.3.0.

      TraceView::Config[:typhoeus]

      config option
      TraceView::Config[:typhoeus]
      description
      Enable/disable typhoeus instrumentation.
      parameters
      [:enabled]
      Set to ‘false’ to turn off instrumentation. Default is ‘true’.
      [:collect_backtraces]
      Set to ‘true’ to collect backtraces. Backtraces are displayed on the trace details page. By default this is set to ‘false’.
      [:log_args]
      Set to ‘false’ to disable argument logging. By default this is set to ‘true’.
      history
      • The namespace changed from Oboe to TraceView in 3.0.0.
      • Introduced in oboe 2.7.5.

      Customizing instrumentation

        Ruby partitions

        With hundreds of traces flowing into your dashboard, you need a way to keep them organized. For this, TraceView provides ‘partitions’, a programmatic way of classifying traces. For example, you can place traces into the following classes: anonymous, authenticated, and administrator. On the dashboard, partitions appear as a filter on the same level as urls and controller/action pairs, so in this example you could choose to limit the display to just requests of authenticated users. Traces are not assigned to any partition by default, and you are free to partition requests however you need to feel that your app is logically arranged. To assign a trace to a partition, just fire an info event anywhere within the trace and attach the partition key/value pair. Partition names may have a maximum length of 40 characters, anything longer is truncated to 40. They’re also limited to alphanumeric characters, or underscores. Any characters that don’t fit this criteria are silently converted to underscores.

        1 TraceView::API.log_info(nil, { 'Partition' => :partition_name })

        Ruby custom layers

        By default, the ruby instrumentation creates a layer for the code itself, e.g., ‘rack’, ‘rails’, ‘padrino’. If these layers don’t provide enough visibility, you can further divide your code into sub-layers. How you segment your application modules and sub-systems into layers is entirely up to you. For example the out-of-box instrumentation might not recognize calls to external processes, so you could use the API manually create layers for them. Similarly, multi-threaded apps can have individual layers for each of its asynchronous operations. To create a custom layer, identify the section of code you would like to appear as a layer, and wrap it in a TraceView::API.trace block with two parameters:

        layer_name
        Choose a name for the layer you are initiating, e.g., ‘CandidateQuery’, ‘FlatFileDB’ or ‘APIServiceCall’.
        report_kvs
        A ruby hash. The values within may be any information about the layer that you would like to be reported. The hash may be empty.
        1 report_kvs = { :key => 'value' }
        2 
        3 TraceView::API.trace(:layer_name, report_kvs) do
        4   # Do the work
        5 end

        Ruby function profiling

        Minimum version required: This profiling technique is supported on ruby versions 1.9.3 or newer.

        For most situations where you want to analyze a specific region of code, it will be easiest and more informative to use our function profiling interface. The alternative is custom layers, which should generally be reserved for calls to external services that our instrumentation would not normally recognize as needing their own layer.

        A function profile enables you to drill down on the performance of a specific region of code within the language layer of your app, seeing how often they are hit, in what calls and traces, and how long they take. For example, you might use function profiles to track the performance of different template renders or to profile a particular segment of your critical path.

        The ruby TraceView gem includes an api to easily profile any arbitrary method in your application. This can be used on models, controllers or even ruby native methods such as Array::sort. This can be done by placing the following call in your application initializer, your rackup file, or any place that is called on application startup.

        1 TraceView::API.profile_method(Array, :sort, opts, extra_kvs)

        The preceding example would setup Array::sort to be profiled along with the rest of your application. The parameters for the call are:

        klass
        The class or module that has the method to the profiled.
        method
        The method to profile. Can be a singleton, instance, private, etc.
        opts
        A hash specifying the one or more of the following options:
        :arguments
        Report the arguments passed to ‘method’ on each profile. Default: false.
        :result
        Report the return value of ‘method’ on each profile. Default: false.
        :backtrace
        Report a backtrace of the call stack on each profile. Default: false.
        :name
        Alternate name for the profile reported in the dashboard. Default: the name of the method profiled.
        extra_kvs
        A hash containing any additional key/values you would like reported with the profile. Default: none.

        Method profiling will automatically detect and report controller and action key/values for classes that are derived from AbstractController::Base such as ActionController::Metal.

        Profiling for ruby 1.9.2 and earlier

        Unless you’re running your application with bundler and a gemfile, you’ll need to include a couple of extra modules in order to profile ruby methods. Put these modules anywhere you like.

        1 require 'rubygems'
        2 require 'traceview'

        The decorator pattern is as follows. It’s very important that you use unique profile names within each language layer so as not to mix up your data. As long as the profile name remains the same, you may rename or move around functions without affecting their treatment on the dashboard. Set the store_args and store_return flags as desired.

        1 include TraceViewMethodProfiling
        2 profile_method(method_name, profile_name, store_args=false, store_return=false)

        The syntax for profiling is a little different for class methods and instance methods.

         1 # For instance methods, put the decorator after the method definition.
         2 class Foo
         3     def bar()
         4         ...
         5     end
         6     include TraceViewMethodProfiling
         7     profile_method :bar, 'bar'
         8 end
         9 
        10 # For class methods, put the decorator inside a class singleton.
        11 class Foo
        12     def self.baz()
        13         ...
        14     end
        15     class << self
        16         include TraceViewMethodProfiling
        17         profile_method :baz, 'baz'
        18     end
        19 end

        Instrumenting background jobs

        TraceView comes with support for Sidekiq, DelayedJob, and Resque, but you can also use our API to instrument other background jobs like starling.

        Simply wrap the perform method in a TraceView::API.start_trace block.

         1 class MonthlyCouponEmailJob
         2   def perform(*args)
         3     
         4     # KVs to report to TraceView
         5     report_kvs = {}
         6     report_kvs[:Spec] = :job
         7     report_kvs[:Controller] = :MonthlyEmailJob
         8     report_kvs[:Action] = :CouponEmailer
         9     
        10     # Start tracing this job with start_trace
        11     TraceView::API.start_trace('starling', nil, report_kvs) do
        12       monthly = MonthlyEmail.new(:CouponEmailer)
        13       
        14       # Trace a sub-component of this trace
        15       TraceView::API.trace(self.class.name) do
        16         
        17         # The work to be done
        18         users = User.all
        19         users.each do |u|
        20           monthly.send(u.email)
        21         end
        22         
        23       end
        24     end
        25   end
        26 end

        Some background processing systems such as starling use fork to spawn child workers from the parent process. In such cases, the TraceView gem won’t be able to report traces correctly. To fix this, you must re-initialize the reporter after the fork.

        1 TraceView.reporter = TraceView::UdpReporter.new(TraceView::Config[:reporter_host], TraceView::Config[:reporter_port])

        Where do background jobs show up?

        Resque, Sidekiq, and DelayedJob are instrumented automatically. Push operations are recorded naturally during the course of tracing a normal request, and as such they appear as an extent on trace details page. The consume operation however is actually a totally different trace, as the background worker is a different entry point than the entry point that started the original trace. For example, rather than the entry layer being ‘rails’, it would be something like ‘sidekiq-worker’. These worker traces show up in your default app. To increase visibility, and to make sure you don’t miss out on any insights from background worker instrumentation, we recommend that you define a separate worker app for these traces.

        Real user monitoring for ruby

        Minimum version required: Real user monitoring for Ruby apps requires traceview gem version 1.3.3 or newer.

        Do you have an instrumented webserver? These instructions involve enabling RUM via your layout file. If apache or nginx sits in front of your app, you don’t need to enable RUM here. It’s already provided at the web server level via our auto-rum support.

        TraceView provides optional javascript-based client-side performance data via real user monitoring (RUM). In order to gather real user timing data from the browser, you’ll need to insert two scripts into your application layout file via helper methods that automatically generate the required javascript.

        1. Place traceview_rum_header just after any <meta> tags in your <head> block. It should be the first non-meta tag inside <head>.
        2. Place traceview_rum_footer immediately before the closing </body> tag.
         1 <head>
         2 <meta ... >
         3 <%= traceview_rum_header rescue "" %>
         4 ...
         5 </head>
         6 
         7 <body>
         8 ...
         9 <%= traceview_rum_footer rescue "" %>
        10 </body>

        Report deploy notifications

        You can have Capistrano deploy notifications show up in your dashboard. This allows you to track deploys and additionally see the performance effects deploys have on your application. To add deploy notifications to capistrano, add the following code to your config/deploy.rb.

        Annotating with tlog: The TraceView tlog utility is installed with the base TraceView packages. Its options along with more information on tlog can be found in annotating your graphs.

         1 # replace or remove :app, #{stage}, #{branch} and 'Your App' with values that are valid for your deploy script.
         2 after "deploy", "deploy:notifications"
         3 namespace :deploy do
         4   desc "Notify all services that there was a deploy."
         5   task :notifications do
         6     appneta_deploy
         7   end
         8 
         9   desc "Notify TraceView of a deploy"
        10   task :appneta_deploy, :roles => :app do
        11     set :notification_msg, "Deployed to 'Your App' #{stage} branch #{branch}"
        12     puts "  ** Sending notification to TraceView for 'Your App'"
        13     run "if test -x /usr/bin/tlog; then /usr/bin/tlog -a \"Your app\" -m \"#{notification_msg}\"; else echo \"WARNING: /usr/bin/tlog not found.  TraceView deploy notification not sent.\"; fi"      
        14   end
        15 end