Using the Ruby SDK

This is a guide for developers to get started with writing a Ruby plugin agent for New Relic Plugins that generates example metric data.

This document is for New Relic Plugins. If you are using New Relic APM with the Ruby agent, see Guide to using the Ruby agent API.

Ruby prerequisites

Before you build a Ruby SDK plugin, make sure you meet these requirements:

  • New Relic account
  • Ruby 1.8.7 or higher
  • Rubygems 1.8 or higher
  • Bundler 1.3.0 or higher
  • Git 1.8
  • Your license key

Installing the Ruby plugin agent

These directions are based on the Ruby plugin example for New Relic Plugins. The example already contains the current version of the Ruby SDK within the Gemfile for New Relic Plugins. If you want to download the SDK separately, the full source code for the SDK is in the newrelic_plugin Github repository.

  1. Download the latest release tag from the newrelic_example_plugin Github repository.
  2. Extract the archive to the location where you want to develop the plugin.
  3. Change the directory to where you extracted the example archive and execute the bundle install command to install the required dependencies.
  4. Inside the config directory, copy the template_newrelic_plugin.yml file to newrelic_plugin.yml.
  5. Edit newrelic_plugin.yml, replacing the string YOUR_LICENSE_KEY_HERE with the license key for your New Relic account.

Assigning a Globally Unique Identifier (GUID)

Your Ruby plugin will need a Globally Unique Identifier (GUID). Your GUID should be similar to the reverse of a DNS name; for example, com.some_company.some_plugin_name. The last part of the GUID (some_plugin_name) will be the plugin name that appears in the New Relic Plugins menu bar.

Note: Keep the same name for your GUID for the life of your plugin, because the user interface and customer data are associated with this GUID.

  1. Choose a Globally Unique Identifier (GUID) for your plugin.
  2. In a text editor, open newrelic_example_agent, and replace the text _TYPE_YOUR_GUID_HERE_ in the file with your chosen GUID.

Starting the Ruby plugin agent

After replacing the generic newrelic_example_agent text with your GUID, start the Ruby plugin agent.

  1. Execute the agent to begin reporting data to New Relic Plugins with ./newrelic_example_plugin or bundle exec ./newrelic_example_plugin.
  2. Look for error-free startup messages on stdout, such as "Sent 3 metrics to New Relic Plugins," as well as diagnostic output that periodically shows the names and values of metrics sent back to New Relic Plugins.
  3. If you see any 401 or 403 errors:
    • Double-check that you have recorded your New Relic license key correctly in the newrelic_plugin.yml file.
    • Run bundle update to make sure your Ruby SDK has the latest version, and then try sending metrics again.
  4. Wait a few minutes for New Relic Plugins to begin processing the data sent from your agent.
  5. Sign in to your New Relic account.
  6. From the New Relic Plugins menu bar, look for the name of the agent that you just created (the some_plugin_name part of your GUID).
  7. To view your plugin's summary page, select the plugin's name ("example").

Using GitHub forks and versioning

If you retain your source code on GitHub, users can easily fork, modify, and deploy the metrics that your plugin agent reports to New Relic Plugins. However, users cannot fork and modify your plugin agent's dashboard. If a user runs a modified plugin agent (with a new GUID), they will see a blank dashboard, and they will need to recreate any previously existing dashboards manually.

To avoid this situation, New Relic recommends that you create different versions of your plugin; for example, one for a development environment and one for production.

If you need to migrate dashboards between GUIDs, get support at

For more help

Additional documentation resources include:

Recommendations for learning more: