This is a guide for developers to get started with writing a Java plugin agent for New Relic Plugins that generates example metric data. For detailed information, refer to the README file in Github for the New Relic Plugins Java SDK.
This document is for New Relic Plugins. If you are using New Relic APM with the Java agent, see Guide to using the Java agent API.
Before you build a Java SDK plugin, make sure you meet these requirements:
- New Relic account
- A configured Java Developer Kit (JDK) version 1.6 or higher
- Your license key
Note: Before you begin development, consider what dashboards you want to show for whatever it is you are monitoring in the New Relic Plugins user interface. The metric names you use directly affect how the aggregating data will appear in dashboards.
Installing the Java plugin agent
These directions are based on the Java plugin example for New Relic Plugins. The example already contains the current version of the Java SDK for New Relic Plugins. If you want to download the SDK separately, the full source code to the SDK is in the newrelic_javaSDK Github repository.
To install the example plugin:
- Download the latest release tag from the newrelic-platform GitHub repository.
- Extract the archive to the location where you want to develop the plugin.
Creating your Agent class
Every plugin needs one class that extends the SDK's Agent class. This is the "blueprint" for whatever it is you want to monitor. For example, if you want to create a plugin to monitor MySQL instances, create a single MySQLAgent class that extends from Agent.
Each of your Agent subclasses requires 3 steps:
- Overload the constructor, including the GUID and version.
- Override the getAgentName() method to identify the name that will appear for a given instance in the UI for New Relic Plugins.
- Override the pollCycle() method to gather and report where metric values live. This method will be invoked once for each Agent per polling interval while your plugin is running.
For more information and examples, see the "Create your Agent class" section in the agent SDK README file in Github.
Initializing your Agent instances
A plugin's value comes from the ability to dynamically configure instance information so it can be reused by others to monitor their systems without code changes. This requires instance data to come from a standardized configuration file (plugin.json, which is located in the .\config directory next to your jar).
Every plugin for New Relic Plugins uses the plugin.json file to configure instance-specific information, such as the hostnames you want to monitor or the user/password combinations to access them. The file is standard JSON and only requires that you have a root-level agents property that contains an array of objects.
Each object in the array needs to correspond to an instance of something you are monitoring. Essentially each JSON object in the agents array should have all the fields necessary to initialize an instance of your Agent class. You can pass whatever fields or create as many Agents as you want here.
In addition, the SDK provides an AgentFactory class you can use to automatically turn your JSON configuration into initialized Agents. Simply extend the AgentFactory class and override the CreateConfiguredAgent() method. When the SDK first starts, it will parse the plugin.json file for you and map the JSON options into a dictionary of strings to objects that you can then use to initialize and return an instance of your Agent.
For more information and examples, see the "Initialize your Agent instances" section in the agent SDK README file in Github.
Setting up the Runner
The last coding step is to create an instance of the Runner class and pass it your AgentFactory class. For more information and examples, see the "Set up your Agents with the Runner" section in the agent SDK README file in Github.
Packaging and distributing your plugin
The New Relic Platform Installer (NPI) for New Relic Plugins is a command line utility that allows users to easily download, configure, and manage a plugin by installing it with a single command. If you are a plugin developer, you can follow these steps to meet the NPI requirements for a consistent installation experience, and publish your plugin in Plugin Central as NPI Compatible.
Tip: For additional information about configuration options and logging levels for your plugin, see the agent SDK README file in Github.
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 support.newrelic.com.
For more help
Additional documentation resources include: