The parts of a plugin

A plugin contains four key parts:

  • GUID
  • Plugin agent
  • Metrics being recorded
  • Dashboards reporting on these metrics

This is a high level overview of what these parts are and how they work together with New Relic Plugins. Detailed information is available in separate sections.

GUID

The plugin needs a Globally Unique Identifier (GUID), which is a character string limited to no less than 4 and no more than 255 characters. The GUID for a published plugin must be unique for each plugin across New Relic Plugins. When creating a plugin, you are responsible for monitoring your own GUIDs to avoid naming conflicts. For more information, see Metric data for the Plugin API.

The summary metrics and dashboards in the user interface, as well as customer data, are associated with this GUID in New Relic Plugins. You will use the same GUID for the life of your plugin, so choose a meaningful name.

GUIDs are case insensitive. Do NOT use upper and lower case characters to discriminate between different GUIDs.

GUIDs are written in a format similar to a reverse DNS name. The preferred format is to include first the company name, then the plugin name. The plugin name can be made up of more than one node.

GUIDs can contain only alphanumeric symbols and/or any of the following symbols: periods (.), hyphens (-), or underscores (_). No other symbols, including whitespace, are allowed.

The regular expression below describes what comprises a valid GUID:

^[a-zA-Z0-9\.\-_]{4,255}$

Pattern:

com.mycompany.pluginname
com.mycompany.plugincategory.pluginname

Examples:

com.newrelic.an_example
com.printingpress.paper.sheafcounter
com.redsecret.FF0000.secret

The last part of the GUID (pluginname) is the plugin name that appears in the New Relic Plugins menu bar. The entire GUID appears on the title of the plugin page. Both names can be customized through the New Reilc user interface. For more information, see Changing plugin settings.

Do not use an unpublished plugin agent to report metrics to more than one account. The New Relic Plugins product does not prevent you from using conflicting GUIDs for unpublished plugins. The first account to publish a plugin with a specific GUID will succeed, and subsequent accounts will fail. The conflicting accounts will never get the user interface portion (summary metrics and dashboards) associated with the published plugin's GUID. If you need to migrate dashboards between GUIDs, get help at Platform & Plugins.

Plugin agent

The plugin agent is the software that runs on the user's app server or is provided for them as SaaS. From the user's perspective, running a published plugin agent will cause the plugin user interface, which is stored on the New Relic collector, to appear in the configured account's New Relic Plugins interface. The agent handles three tasks:

  • Collecting data from monitored hosts, services, or devices
  • Processing data into aggregated metrics
  • Reporting metrics to New Relic Plugins

The collected metric data can be any non-negative value which can be represented as an integer or a floating-point number. New Relic Plugins will not perform any computational work beyond typical statistical aggregation: max, min, average, count, and standard deviation. All calculations to be applied to your metrics must be completed by the plugin agent before being reported to New Relic Plugins.

Each plugin agent can report metrics for multiple GUIDs which appear with separate plugin summaries in the user interface for New Relic Plugins. Plugin agents can also report data for multiple instances (components) of a GUID, which will appear listed together on the summary page for the plugin.

New Relic Plugins provides software development kits (SDKs) for agents. You can also report metrics directly for any arbitrary language by using the API for New Relic Plugins. For more information, see the specific plugin agent SDK documentation, or see SaaS developer plugins.

Plugin metrics

New Relic Plugins will store metrics in a specialized key/value store where the value represents statistically aggregated data. Keys are referred to as metric names and include units for both the value and count of the stored metrics. Metrics names including units may be up to 255 characters in length.

All metric names stored by plugins are prefixed with Component/. Metric names may be broken up into categories divided by the forward slash (/) character. Using segments to create namespaces help make creating customized dashboards easy. Metrics names follow this pattern:

PREFIX/CATEGORY/LABEL[UNITS]

For example, the metric representing the latency of cache hits reported by a plugin collecting data for a caching load balancer named "Varnish East" might look like this:

Component/varnish_east/cache/hits[hits|lookup]

Well planned metric names are critical for success when creating the intended visualizations of plugin data. For more information, see Metric naming reference.

Plugin summary metrics and dashboard

Once data has been reported to New Relic Plugins by a plugin agent, plugin authors use summary metrics and customized dashboards to visualize that data. Each plugin includes a default dashboard with a list of associated Caution events and Critical alerts. Plugin authors can define additional customized dashboards which include charts and tables of metric data as needed.

Published plugins must include at least one summary metric. Plugin authors may choose to define up to five summary metrics to appear on their plugin's summary page. Summary metrics report the current state of the system monitored by the plugin and are the basis for triggering Caution events and Critical alerts.

For more information, see:

For more help

Recommendations for learning more: