Configuring the diagnostics data collector

If you are a user of Cloud APM, Advanced, you can continue to configure the data collector for diagnostics data. Diagnostics data collection is disabled by default in the data collector configuration file.

• To modify the data collector settings of a specific application that is running:
  1. Navigate to the install_dir/install-images/kkm/dchome/appClassName/config directory, where appClassName is the Ruby application class name, and install_dir is the installation directory of Ruby agent. The default installation directory is /opt/ibm/apm/agent.
  2. Open instrumenter_settings.rb in a text editor.
  3. Modify the data collector settings:

     :instrumentation_enabled

     To enable support for the collection of diagnostics data, set :instrumentation_enabled => true.

     To disable support for the collection of diagnostics data, set :instrumentation_enabled => false.

     :sample_frequency

     To modify the sampling frequency of requests, enter the number of requests between samplings.

     The data collector collects diagnostic data only for sampled requests. If you set :sample_frequency => 10, for example, data is collected for 1 in every 10 requests.

     :max_methods_to_instrument

     To disable method trace collection or to enable method trace collection and limit the number of methods that are traced, set the value to zero, or enter the maximum number of methods to trace.

     To disable the collection of method traces, set :max_methods_to_instrument => 0.

     To enable the collection of method traces, set :max_methods_to_instrument => 10000. The value can be higher, but a much higher value might cause performance issues. When method data is collected, calls to methods are included in the Request Traces dashboard's Method Trace widget, which shows all the request instances and their nested requests.

     :min_wallclock_to_include_in_trace

     To modify the threshold that determines whether the request or method should be traced, set the minimum response time. If you set :min_wallclock_to_include_in_trace => 0.001, for example, only the requests and methods whose response times are longer than 1 millisecond are traced.

     Remember: From the Request Trace diagnostic dashboard, you can drill down to a specific request instance from the Request Stack Trace group widget. The response times totals for the instance might be incorrect due to the filters set for :min_wallclock_to_include_in_trace and :min_wallclock_to_include_stacks, which can exclude some data.

     :min_wallclock_to_include_stacks

     To modify the threshold that determines whether the stacktrace information should be collected for a request or a method, set the minimum response time.

     If you set :min_wallclock_to_include_stacks => 0.1, for example, the stacktrace information is collected for all the requests and methods whose response time is longer than 100 milliseconds.

     :include_subclasses_of_these_modules

     The Request Traces diagnostics dashboard helps you to identify the sequence of calls to nested requests and methods for a request instance. The data collector preemptively filters out methods from classes that are not included in the filter list. If operations that you want to trace are not included in the method stack traces, you can add them here.

     To specify the methods to trace, add their class names.

     Consider, for example, that you want to trace the Moped APIs in the following kind of Ruby code:

     session = Moped::Session.new(['ip:27017'])
     session.use(:HR)
     session[:profiles].insert({......})
     session[:profiles].find({...}).remove
     
     

     Add the module names of these Moped APIs to the property:

     :include_subclasses_of_these_modules => {"
     ActionController" => true,
                          "ERB" => true,
                          "erb" => true,
                          "Arel" => true,
                          "Mongoid" => true,
                          "Moped" => true
                         },
     

     Restriction: The method traces do not include class methods and private methods (methods defined in a class that have implicit or explicit private access specifiers).

     :include_sql_text

     To collect context data for methods, set this property to true.

     :num_samples_per_file

     To modify the maximum number of traced requests to store in each file, enter a value such as :num_samples_per_file => 1000. After the limit set here is reached, a new file is created.

     Consider setting :num_samples_per_file to a lesser value if you adjust the configuration in a way that causes more data to be collected. For example, setting :include_subclasses_of_these_modules to trace more classes and methods can increase data collection. Setting any of the following properties to a lower value can also increase data collection: :sample_frequency, :min_wallclock_to_include_in_trace, and :min_wallclock_to_include_stacks.

     :verbose_request_instrumentation

     :verbose_class_instrumentation

     :verbose_method_instrumentation

     To increase the logging level of the diagnostics data collector, set these properties to true.

     Tip: If operations that you specifically want to trace are not included in the method stacktraces, set :verbose_class_instrumentation => true and check the log to find out whether the class that you want to trace is instrumented. If it is not instrumented, add the class name of the module name of the class to the :include_subclasses_of_these_modules property.

  4. If you edited any of the following properties, restart the corresponding Ruby on Rails application to have your changes take effect:

     :include_subclasses_of_these_modules
     :max_methods_to_instrument 
     

     The restart is necessary because these properties are used only when an application is launched to determine which class or method is to be instrumented by the Ruby data collector.
• To modify the data collector settings of all Ruby on Rails applications, complete these steps:
  1. Stop any Ruby on Rails applications that are currently running.
  2. Remove the instrumer_settings.rb from the install_dir/install-images/kkm/dchome/application_name/config directory.
  3. Modify the data collector settings in Gem_dir/gems/stacktracer-version/config/instrumenter_settings_template.rb where version is the version number, such as 01.00.05.00, and Gem_dir is the installation directory of stacktracer-version.gem, such as /usr/local/rvm/gems/ruby-2.1.4/. For more information, see step 3 in the procedure for modifying the data collector settings of a specific application.
  4. Restart any Ruby on Rails applications that are currently running.