System-Level Monitoring for AIX, Linux, OSX/MacOS & Solaris/SunOS

Here. If you are just deploying and not compiling it, please download the release instead of cloning the repo.

• Disclaimer
• Contributing
• Requirements
  • Supported OSes
• Installation & Usage Overview
• plugin.json configuration
  • Global settings
    • Using the EU Data Center? Click here!
  • Agent settings
  • Proxy settings
  • Dashboard deployment
• Other configurations
  • Deploying Dashboards from separate server or desktop
  • Fix for using the WebSphere JDK
  • Enabling Debug Mode

New Relic has Open Sourced this integration to enable monitoring of this technology. This integration is provided AS-IS WITHOUT WARRANTY OR SUPPORT, although you can report issues and contribute to this integration via GitHub. Support for this integration is available with an Expert Services subscription.

We'd love to get your contributions to improve the Unix Monitor! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at [email protected].

• A New Relic account.
  • As this monitor posts 'custom events' to Insights, your account must either have an active Insights trial or be a paid Insights account.
• A Unix server that you want to monitor
• Java JRE/JDK v1.6 or later
• Network access to New Relic (proxies are supported, see details below)
• For Dashboard Installation: curl or wget installed

• AIX 7.x
• HP-UX 11.x
• Linux - All sorts, including on ARM processors (such as Raspberry Pi) and z/Linux
• OSX / MacOS 10.9 ('Mavericks') and above
• Solaris/SunOS 10.x and 11.x

1. Download the latest version of the Unix Monitor here.
2. Copy, gunzip & untar the latest release onto the Unix server that you want to monitor
3. Set account ID, keys and other settings in config/plugin.json
   • Click here for plugin.json config details
4. OPTIONAL: Configure pluginctl.sh to have the correct paths to Java and your plugin location
   • Set PLUGIN_JAVA to the location of Java on your server (including the "java" filename)
   • Set PLUGIN_PATH to the location of the Unix Plugin
5. Run ./pluginctl.sh start from command-line
6. Check logs (in logs directory by default) for errors
7. Login to New Relic UI and find your data in Insights
   • In the data explorer, look for custom event types that start with "unixMonitor:"
   • Possible event types (for out-of-the-box commands): unixMonitor:Disk, unixMonitor:DiskIO, unixMonitor:NetworkIO, unixMonitor:Process, unixMonitor:Stats, unixMonitor:Vmstat

Note: A full example of the possible fields in plugin.json can be found in plugin-full-example.json

• OS (default: auto): Used to determine which commands to run and how to parse them. Leave set to auto to have the plugin figure that out (which normally works).
• account_id: New Relic account ID - the 6- or 7- digit number in the URL when you're logged into the account of your choosing.
• insights_insert_key (under insights): You must create an Insights Insert key, as described here.
• insights_data_center (under insights, default: us): If using the NR EU data center for your account, please change this to eu or EU. Otherwise, you can leave this alone or omit this setting entirely. {#eu-data-center}

These settings are found in the agents object.

• name: If set to auto, the plugin will use that server's hostname. Otherwise, sets the hostname and agentName to whatever is set here.
• static (optional): An object containing static attributes (as name-value pairs) you want to appear in every event from this plugin. For example:

  "agents": [
    {
      "name": "auto",
      "static": {
        "data_center": "Philadelphia",
        "customer": "Eagles",
        "rank": 1
      }
    }
  ]

If using a proxy, the optional proxy object should be added to the global object in plugin.json, if its not there already.

• The available attributes are: proxy_host, proxy_port, proxy_username and proxy_password.
• The only attribute that is required in the proxy object is proxy_host.

The plugin can check for and deploy the latest dashboards to your account when it starts up. This requires the dashboards object in plugin.json to be set up properly:

• admin_api_key: Admin API key, as described here.
• integration_guid: Default is UNIX.Infra.Monitor. DO NOT DELETE OR CHANGE UNLESS OTHERWISE INSTRUCTED.
• dashboard_install: Default is command_line. DO NOT DELETE OR CHANGE UNLESS OTHERWISE INSTRUCTED.
• (Optional) force_deploy: Default is false, see Redeploying dashboards for details.

If you don't want the dashboard deployment to run at start-up, leave admin_api_key blank or remove it entirely.

The plugin can force the dashboards to be redeployed by either of two ways:

• Run ./pluginctl.sh dashboards_redeploy OR
• Set force_deploy to true in the dashboards object in plugin.json and run ./pluginctl.sh dashboards NOTE: Be sure to re-set force_deploy to false once completed. Otherwise, the dashboards will re-deploy every time the ./pluginctl.sh start or ./pluginctl.sh restart is run.

If you want to initiate the dashboard install from a standalone machine (i.e. a tools server or your own mac, linux or cygwin laptop/desktop), you will need the following:

• pluginctl.sh
• config/plugin.json (including path) with the dashboard object filled in as described above.

To install, run ./pluginctl.sh dashboards.

If you are using the JDK that is packaged with WebSphere and see an exception in the logs like below, it is due to attempting to use the WebSphere SSL Factory instead of the IBM JSSE packages.

ERROR com.newrelic.metrics.publish.binding.Request - An error occurred communicating with the New Relic service
java.net.SocketException: java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory

If so, uncomment the following line in pluginctl.sh and restart the plugin.

# USE_IBM_JSSE=true

If you see the following error, it may be because the Bourne shell does not support certain syntax in the installer script.

pluginctl.sh: syntax error at line 240: `admin_api_key=$' unexpected

If so, use the Korn shell or Bash (if available). Both were tested successfully in Solaris 10.

If you are trying to customize the commands that the Unix Monitor is running, or you are not seeing any or all of the data you expect to see, you can put the agent into 'Debug Mode', in which it outputs to the logs all of the commands being run and it's attempts at parsing them.

Note: You will need to restart the Unix Monitor to pick up these changes.

This can be enabled EITHER by:

• Running pluginctl.sh with the debug at the end to start, like so: ./pluginctl.sh start debug or ./pluginctl.sh restart debug OR
• Replacing config/logback.xml with config/logback-debug.xml and restarting the Unix monitor (if using this method, remember to swap the files back when finished)