WHERE DO I START?
You are here:Integrations > Ruby
  • Top ↑

Ruby

Summary

The Netuitive Ruby agent comprises three Ruby gems—netuitived, netuitive_ruby_api, and netuitive_rails_agent—that work in tandem to monitor the performance of your Ruby applications.

  • netuitived is a daemon that allows metrics to be exported to the Netuitive API.
  • netuitive_ruby_api is a gem that allows for easy integration with netuitived.
  • netuitive_rails_agent is a gem that provides default Ruby on Rails metrics and sends them to netuitived using netuitive_ruby_api.

The Netuitive Ruby agent can also be tuned to help application performance and used to read garbage collection metrics. The flow-chart below details the flow of data from your application to Netuitive.

Configuration

Note   If you need to disable an existing Ruby integration or view the unique API key assigned to your account, navigate to the Integrations page under the user account drop-down menu and click the integration designated as Ruby under the Integration column.

Installation

Setting up the Ruby agent is a two-step process:

  1. Copy the unique API key from the Ruby integration in your account.
  2. Install the three gems on your system.

Step 1: Copy the API key from the Ruby integration in your account

  1. From the top navigation menu, select Integrations.
  2. Select the Ruby card. The name should be already populated, and Data Collection should be enabled. A unique API key for your account has already been generated.

Step 2: Install the Gems

Note   You'll need to have RubyGems installed to install the Ruby agent gems.
  1. Install the netuitived gem using the below command:
    gem install netuitived
    Important   For busier Rails applications, you'll want to avoid running the daemon on the same server as your application.
  2. Run the start script once the gem has been installed:
    netuitived start
  3. Enter the desired element name into the prompt, then type into the prompt the unique API key generated for your account that you copied in step 1. If you're unsure what to name your element, you should use the name of your ruby application.
    Example(s)   Below is a sample prompt generated by the Ruby agent. A sample element name and API key are highlighted.
    admin:~$ netuitived start
    please enter an element name:
    sample_app
    please enter an api key:
    cb73834fa800f987s84sffas767f11b2c
    
  4. Optionally, edit the netuitived config/agent.yml file if you wish to update the caching interval, use environment variables, change the host location instead of using the default, or want to adjust the logging configuration options.
  5. Add the following line to the Gemfile in your rails application:
    gem 'netuitive_rails_agent'
    Important   The netuitived gem must be running before you install the netuitive_rails_agent gem.
  6. Inside your rails application project directory run the following code snippet to install both the netuitive_rails_agent and netuitive_ruby_api gems:
    bundle install
    Important    You'll need the netuitive_ruby_api gem If you're not using a rails application or if you are using a rails application and want to create your own custom metrics.
  7. Optionally, edit the netuitive_rails_agent config/agent.yml file if you want to adjust the default settings. Check out the performance tuning section to learn more about the different options.
  8. Optionally, edit the netuitive_ruby_api config/agent.yml file if you want to adjust the default settings. Check out the performance tuning section to learn more about the different options.
  9. Restart your rails application and begin monitoring your data with Netuitive.
    Note   This integration's package (computed metrics, dashboards, and policies that will give you important events and alerts) will be automatically enabled and provisioned to your account as soon as Netuitive receives data from the integration. The PACKAGES button on the integration setup page will become active once data is received, so you'll be able to disable and re-enable the package at will.

Additional Configuration Options

Performance Tuning

The Netuitive Ruby agent is capable of several thousand hits per minute on a basic setup and comes with a wealth of logging, event, metric, error tracking, and caching options. The cache acts as a buffer, batching requests to the daemon. The larger the cache, the larger the memory footprint, but less CPU and network time will be spent sending errors and metrics to the daemon. Depending on your preferences, you can tune the agent to help with CPU / network usage or memory usage.

Important   If you have a very busy server and do not set the cache to be large enough, it is possible to run out of open threads and / or file handles.

Netuitive Rails Agent configuration options

Section Details
Log config options
  • logLocation: The absolute path of the log file. Leave this option blank to use the default location in the gem directory.
  • logAge: Specify either the number of log files to keep or the frequency of rotation (daily, weekly, or monthly).
  • logSize: Specify the maximum log file size (in bytes).
  • debugLevel: Options include (in ascending order of severity) error, info, and debug.
Active support notifications

The active support notifications are a pub-sub model that trigger active support notifications when certain actions are performed within your rails application(s). Each flag is toggling a certain set of active support notifications for a subset of metrics in Netuitive.

  • actionControllerEnabled: Set to true to enable action_conroller metric collection.
  • activeRecordEnabled: Set to true to enable active_record metric collection.
  • actionViewEnabled: Set to true to enable action_view metric collection.
  • actionMailerEnabled: Set to true to enable action_mailer metric collection.
  • activeSupportEnabled: Set to true to enable active_support metric collection.
  • activeJobEnabled: Set to true to enable active_job metric collection.
Injected instrumentation
  • requestWrapperEnabled: Set to true to enable the queue time metric, which is the time (in ms) taken after a request enters your system and before it reaches your application. Netuitive takes either the X-Queue-Start or X-Request-Start headers to calculate the queue time, but time unit types won't be automatically converted.
  • actionErrorsEnabled: Set to true to inject code into the action controller which will silently track exceptions. Exceptions will be sent to Netuitive as an external event. An errors metric will also be available on the Metrics page under the action_controller branch for the element that tracks the number of exceptions seen.
Interpreter metrics
  • gcEnabled: Set to true to enable garbage collection metric collection.
  • objectSpaceEnabled: Set to true to enable object space metric collection.
3rd party
  • sidekiqEnabled: Set to true to enable sidekiq metric and error collection.
    • Sidekiq metrics include number of jobs per queue, number of jobs ran per queue, and number of jobs ran per job.
    • Errors will be sent to Netuitive as an external event. An errors metric will also be available on the Metrics page under the sidekiq branch for the element that tracks the number of exceptions seen.
Error tracking features
  • sendErrorEvents: Set to true to send exceptions from sidekiq and action_controller as events to Netuitive. If this setting is set to false, but actionErrorsEnabled and sidekiqEnabled are set to true, errors will not be sent to Netuitive as events but all metrics will still be collected.
Feature configs
  • queueTimeUnits: The divisor required to convert the queue time metric into seconds (e.g., seconds = 1, milliseconds = 1000, microseconds = 1000000).
  • ignoredErrors: List of exceptions to ignore. List should be provided in one of the following formats:
    • yaml format
      ignoredErrors:
      - Runtime Error
      - Argument Error
    • environment variable format
      NETUITIVE_RAILS_IGNORED_ERRORS=RuntimeError,ArgumentError
    Tip    You can ignore exceptions that match agains an ancestor using a ^, so NETUITIVE_RAILS_IGNORED_ERRORS=RuntimeError^ would ignore all errors that inherit from RuntimeError.

Netuitive Ruby API configuration options

Section Details
Log properties
  • logLocation: The absolute path of the log file. Leave this option blank to use the default location in the gem directory.
  • logAge: Specify either the number of log files to keep or the frequency of rotation (daily, weekly, or monthly).
  • logSize: Specify the maximum log file size (in bytes).
  • debugLevel: Options include (in ascending order of severity) error, info, and debug.
Netuitived connection properties Netuitived address and port information.
Cache properties

The cache settings are related to the threads and events on your host ruby application. It allows for a small buffer to limit the amount of calls made to the daemon. The main purpose is to cache enough data to not have excessive thread growth when making calls to the daemon.

Important   Owners of busy rails applications may have to adjust the settings; otherwise, the default settings should be fine for most applications. If you find you're receiving a lot of errors, you may want to turn the error cache on.
  • sampleCacheEnabled: Set to true to enable the sample cache.
  • sampleCacheSize: The maximum number of samples cached before the samples are sent to Netuitived.
  • SampleCacheInterval: Interval (in seconds) at which the cached samples are sent to Netuitived.
  • eventCacheEnabled: Set to true to enable the sample cache.
  • eventCacheSize: The maximum number of events cached before the events are sent to Netuitived.
  • eventCacheInterval: Interval (in seconds) at which the cached events are sent to Netuitived.

Enabling Garbage Collection Metrics

The garbage collector attempts to return memory consumed by objects no longer in use by your application. Netuitive can be used to collect metrics on how much time is spent in garbage collection for your Ruby applications. You should have Matz's Ruby Intepreter (MRI) version 1.9.2 or greater or Ruby Enterprise Edition installed before enabling garbage collection metrics.

  1. Navigate to your application's initialization file.
  2. Add the following call (depending on your Ruby version) to the file:
    • For MRI v1.9.2 or greater:
      GC::Profiler.enable
    • For Ruby Enterprise Edition:
      GC.enable_stats
    Note   If you have a Rails application, you can add one of the calls above to an initializer in config/initializers or directly to your config/application.rb.
  3. Save the file and restart your application.

Interpreting Exception External Events

If you have the sendErrorEvents setting enabled in the netuitive_rails_agent config/agent.yaml file and the actionErrorsEnabled and/or sidekiqEnabled settings are set to true, exceptions will be sent to Netuitive as external events. A Ruby Exception external event has the following tags to help you dissect the exception:

Tag Description
Action The action the error originated from.
Controller The name of the controller that the exception came from.
Exception The type of exception.
Sidekiq If true, this exception comes from sidekiq. If false, this exception comes from elsewhere.
URI The resource identifier that names the resource the exception came from.

Because these tags are located within the message body, you can create a policy matching against the body of the message.

Dependencies

Miscellaneous

Matz's Ruby Interpreter (MRI) > v. 1.9.0

Metrics

Note   In the following tables, the BASE column indicates whether there's a baseline band available for the metric, the CORR column indicates whether there's a contextual band available for the metric, and the UTIL column indicates whether the metric can be used as a utilization metric in the Utilization and Utilization Boxplot Reports.

Collected

Fully Qualified Name (FQN) Statistic Units Min Max Sparse Data Strategy (SDS) BASE CORR UTIL
action_controller.halted_callback sum count 0 none zero
action_controller.redirect sum count 0 none zero
action_controller.total_requests sum count 0 none zero
action_controller.*.total_requests sum count 0 none zero
action_controller.*.*.request.query_time average milliseconds 0 none zero
action_controller.*.*.request.total_duration average milliseconds 0 none zero
action_controller.*.*.request.view_time average milliseconds 0 none zero
action_controller.*.*.total_requests sum count 0 none zero
action_controller.*.request.queue_time average milliseconds 0 none        
action_controller.errors average count 0 none        
action_view.render_partial sum count 0 none zero
action_view.render_template sum count 0 none zero
action_record.instantiation sum count 0 none zero
action_record.sql.statement sum count 0 none zero
GC.profiler.total_time                
GC.stat.count                
GC.stat.heap_allocatable_pages                
GC.stat.heap_allocated_pages                
GC.stat.heap_available_slots                
GC.stat.heap_eden_pages                
GC.stat.heap_final_slots                
GC.stat.heap_free_slots                
GC.stat.heap_live_slots                
GC.stat.heap_marked_slots                
GC..stat.heap_sorted_length                
GC.stat.heap_swept_slots                
GC.stat.heap_tomb_pages                
GC.stat.major_gc_count                
GC.stat.malloc_increase_bytes                
GC.stat.malloc_increase_bytes_limit                
GC.stat.minor_gc_count                
GC.stat.old_objects                
GC.stat.old_objects_limit                
GC.stat.oldmalloc_increase_bytes                
GC.stat.oldmalloc_increase_bytes_limit                
GC.stat.remembered_wb_unprotected_objects                
GC.stat.remembered_wb_unprotected_objects_limit                
GC.stat.total_allocated_objects                
GC.stat.total_allocated_pages                
GC.stat.total_freed_objects                
GC.stat.total_freed_pages                
ObjectSpace.count_objects.* average count 0 none zero
sidekiq.*.job.count average count 0 none        
sidekiq.default.*.job.count average count 0 none        
sidekiq.default.job.count average count 0 none        
sidekiq.errors average count 0 none        

Computed

Fully Qualified Name (FQN) Description Statistic Units Min Max BASE CORR UTIL Related Default policies
netuitive.ruby.action_controller.*.total_duration

The total time spent on requests to a specific controller.

Computation:
data.sum('action_controller.${1}.*.request.total_duration')

average ms 0 none