Install from Plugin Central

Each plugin in Plugin Central includes its own procedures for how to install, use, troubleshoot, and uninstall it. In order to use a plugin, first verify that your environment meets the plugin's documented requirements. Then follow the plugin's procedures to install the plugin agent on one or more hosts in your monitored environment, or to configure a SaaS plugin as directed by your SaaS provider.

Requirements

As a standard security measure for data collection, your application server must support SHA-2 (256-bit). We do not support SHA-1.

Plugins in Plugin Central are not supported with accounts that host data in the EU region data center.

Access rights

When using an agent from Plugin Central, deploy the agent giving the fewest possible permissions in order for the plugin agent to function successfully. Unless the plugin publisher gives specific instructions, you should run the plugin agent as a non-privileged user; do not use su or sudo privileges. This applies to both installing and using the agent.

If the plugin agent needs credentials for the component (instance) that it is monitoring, create a custom set of credentials just for the monitoring agent to use. These should be separate from any other production credentials. The custom credentials should grant the fewest possible permissions while still allowing the agent to gather the data it needs.

For example, for most plugin agents, you should only need to grant read-only access to your components or instances so the plugin agent cannot modify your system in any way. Also, with many agents, you should only need to grant access to read performance and administration data, not necessarily end customer or other sensitive data. For more information, see Plugin security.

License key

As part of any plugin installation process, you need your New Relic license key. When you are logged into the Plugins UI, the plugin's installation page in Plugin Central also shows your license key so you can easily copy it to your clipboard.

If plugins have been published by SaaS providers, they must have access to the New Relic license key for each individual account. They can capture this information when provisioning new customers via the New Relic Partner API, or they can provide a mechanism for customers to share their existing New Relic license key.

Typical plugin installation procedures

Installation requirements depend on the type of plugin. For example, a Java plugin agent has different requirements than a Ruby plugin agent. Before you use a plugin, review the documentation that the plugin's publisher provides about the agent's installation requirements.

To install any plugin from Plugin Central:

  1. Go to one.newrelic.com > More > Plugins.
  2. From the Plugin Central directory, select the plugin's title or its Get started button.
  3. From the plugin's details page, select the Download or Continue button.
  4. Follow the plugin's specific instructions to get your plugin installed and running.

After you start running a plugin, it collects and sends data to New Relic, usually within five minutes. The plugin name will automatically appear in the Plugins UI, where you can select and view its summary metrics and dashboards.

Install an NPI-compatible plugin

The New Relic Platform Installer (NPI) is a command line utility that helps you easily download, configure, and manage a plugin by installing it with a single command. After you install the NPI tool, you can use it to install any plugins that are compatible with it.

Install the plugin

Plugins that are compatible with the New Relic Platform Installer include an NPI compatible label. If you have not already installed the NPI tool:

  1. Go to one.newrelic.com > More > Plugins, then select any plugin listed as NPI compatible.
  2. From the selected plugin's Installation page in the UI, click the link that says * Requires New Relic Platform Installer (NPI) - Get it here.
  3. From the dropdown that opens, select your operating system.
  4. Copy the command that appears, then run it in your terminal to install the NPI tool.
  5. Unix-based systems: If you need to set a default user, in your terminal, run:

    ./npi set user <USER NAME>

Once you have installed the NPI tool, you can install any NPI compatible plugin.

  1. Go to one.newrelic.com > More > Plugins, then select any plugin listed as NPI compatible.
  2. From the selected plugin's Installation page in the UI, follow the procedures to copy the specific plugin's installation command.
  3. In your terminal, change to the directory ~/newrelic-npi, then paste and run the install command.
Manage plugins with the NPI tool

To view information that helps you manage NPI-compatible plugins:

  • For usage and commands, help and version flags, and setup examples, run the command --help from the directory ~/newrelic-npi.
  • For a list of plugins that are NPI-compatible, run the command ./npi available.

If you need to include proxy settings in your configuration (for both the NPI tool and the plugin's newrelic.json file), use these commands:

./npi config set proxy_host <HOST>
./npi config set proxy_port <PORT>
./npi config set proxy_username <USER NAME>
./npi config set proxy_password <PASSWORD>

To view the full path for a plugin, run a where command. This is useful for viewing log files or locating a plugin on your filesystem so you can manually configure it.

Troubleshoot NPI-compatible plugins

In addition to the troubleshooting procedures provided by the plugin publisher, follow these troubleshooting guidelines when installing NPI-compatible plugins.

Duplicate plugins

Problem: If you install a plugin and then install the same plugin again through the NPI tool, you will have two versions of the plugin installed.

Solution: Delete the older version of the plugin, and then install the NPI-compatible version using the NPI tool. Procedures to delete plugins typically appear in the README file or in other documentation that the plugin publisher provides.

Error message ./npi: line 1: bin/node: No such file or directory

Problem: The architecture script that you selected when you installed the NPI tool does not match your operating system (for example, x86 instead of x64).

Solution: Install the NPI tool using the correct script for your operating system.

Problem: You cannot run NPI commands.

Solution: You can only access the NPI tool from the location where it was installed. To solve this problem, navigate to the directory ~/newrelic-npi, and run the command again.

Insufficient privileges to run background processes

Problem: If you try to set a plugin to run as a background process, you might see a message that you have insufficient privileges.

Solution: The plugin creates an /etc/init.d script on Linux and a Windows service on Windows, both of which require escalated privileges to run. To solve this problem:

  • Linux: Run the command with sudo in front of it.
  • Windows: Run the command as an administrator.

Install with Chef or Puppet

In addition to standard installation procedures, you can install plugins with Chef and Puppet configuration management tools. These tools automate plugin installation and make it easier to manage plugins with the rest of your server software.

Chef cookbooks

Plugins in Plugin Central may come bundled with a Chef script, or you can write your own. If a Chef script is provided, this does not mean you are required to use it to install the plugin. Before installing a plugin using Chef, add the Chef cookbook for New Relic Plugins:

Then, to install a plugin using Chef:

  1. Configure Chef with the plugin details.
  2. Run Chef to install the plugin.

Chef cookbooks and recipes define roles for specific server configurations. For example, a web server can have the role web_server which includes all of the software and configuration needed for a web server.

Here is an example of creating a Chef role for a server running the Wikipedia Java example plugin:

name "newrelic_wikipedia_example_java_plugin"
description "Server running the New Relic Plugins Wikipedia Example Java Plugin"
run_list(
  "recipe[newrelic_plugins::wikipedia_example_java]"
)
default_attributes(
  "newrelic" => {
    "license_key"            => "NEW_RELIC_LICENSE_KEY",
    "wikipedia_example_java" => {
      "install_path"         => "/path/to/plugin",
      "user"                 => "newrelic"
    }
  }
)
Puppet modules

Plugins in Plugin Central may come bundled with a Puppet script, or you can write your own. If a Puppet script is provided, this does not mean you are required to use it to install the plugin. Before installing a plugin using Puppet, add New Relic's Puppet module for plugins:

Then, to install a plugin using Puppet:

  1. Configure Puppet with the plugin details.
  2. Run Puppet to install the plugin.

Puppet modules contain manifest files that are a collection of classes for configuring a server. For example, a web server can be assigned several classes for the necessary software for a web server.

Here is an example of using a Puppet class for a server running the Wikipedia Java example plugin:

class { 'newrelic_plugins::wikipedia_example_java':
  license_key   => 'NEW_RELIC_LICENSE_KEY',
  install_path  => '/path/to/plugin',
  user          => 'newrelic'
}

For more help

If you need more help, check out these support and learning resources: