The Metricly Ruby agent comprises three Ruby gems—metriclydmetricly_ruby_api, and metricly_rails_agent—that work in tandem to monitor the performance of your Ruby applications.

  • metriclyd is a daemon that allows metrics to be exported to the Metricly API.
  • metricly_ruby_api is a gem that allows for easy integration with metriclyd.
  • metricly_rails_agent is a gem that provides default Ruby on Rails metrics and sends them to metriclyd using metricly_ruby_api.

The Metricly 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 Metricly.


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.


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

You’ll need to have RubyGems installed to install the Ruby agent gems.
  1. Install the metriclyd gem using the below command:
    gem install metriclyd
    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:
    metriclyd 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.

    Below is a sample prompt generated by the Ruby agent. A sample element name and API key are highlighted.

    admin:~$ metriclyd start
    please enter an element name:
    please enter an api key:
  4. Optionally, edit the metriclyd 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 'metricly_rails_agent'
    The metriclyd gem must be running before you install the metricly_rails_agent gem.
  6. Inside your rails application project directory run the following code snippet to install both the metricly_rails_agent and metricly_ruby_apigems:
    bundle install
     You’ll need the metricly_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 metricly_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 metricly_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 Metricly.
    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 Metricly 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 Metricly 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.

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.

Metricly 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 (dailyweekly, or monthly).
  • logSize: Specify the maximum log file size (in bytes).
  • debugLevel: Options include (in ascending order of severity) errorinfo, 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 Metricly.

  • 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. Metricly 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 Metricly 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 Metricly 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 Metricly. If this setting is set to false, but actionErrorsEnabled and sidekiqEnabled are set to true, errors will not be sent to Metricly 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
      - Runtime Error
      - Argument Error
    • environment variable format
    You can ignore exceptions that match agains an ancestor using a ^, so metricly_RAILS_IGNORED_ERRORS=RuntimeError^would ignore all errors that inherit from RuntimeError.

Metricly 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 (dailyweekly, or monthly).
  • logSize: Specify the maximum log file size (in bytes).
  • debugLevel: Options include (in ascending order of severity) errorinfo, and debug.
Metriclyd connection properties Metriclyd 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.

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 Metriclyd.
  • SampleCacheInterval: Interval (in seconds) at which the cached samples are sent to Metriclyd.
  • eventCacheEnabled: Set to true to enable the sample cache.
  • eventCacheSize: The maximum number of events cached before the events are sent to Metriclyd.
  • eventCacheInterval: Interval (in seconds) at which the cached events are sent to Metriclyd.

Enabling Garbage Collection Metrics

The garbage collector attempts to return memory consumed by objects no longer in use by your application. Metricly 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 Interpreter (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:
    • For Ruby Enterprise Edition:
    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 metricly_rails_agent config/agent.yaml file and the actionErrorsEnabled and/or sidekiqEnabled settings are set to true, exceptions will be sent to Metricly 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.


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


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.
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
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
Fully Qualified Name (FQN) Description Statistic Units Min Max BASE CORR UTIL Related Global Policies
metricly.ruby.action_controller.*.total_duration The total time spent on requests to a specific controller.
average ms 0 none