• /
  • Log in
  • Free account

The parts of a plugin

Limited access

Important

For an even better experience than plugins, go to:

  • newrelic.com/integrations: Integrate the on-host and cloud systems you already use with New Relic, so you can filter and analyze data, create dashboards, and set alerts within a single platform.
  • developer.newrelic.com: Use developer tools to collect data from any source, automate workflows, build apps, and use our APIs.

Limited access to legacy plugins

As of December 2, 2020, plugin access has been limited to accounts that have accessed a legacy plugin in the past 30 days. The legacy plugin experience will reach end of life (EoL) as of June 16, 2021. For more information, see our Explorers Hub post.

GUID, agent, metrics, dashboards

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 when developing plugins in New Relic's Plugin Central.

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. When creating a plugin, you are responsible for monitoring your own GUIDs to avoid naming conflicts.

The summary metrics and dashboards in the user interface, as well as customer data, are associated with this GUID. 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 UI The entire GUID appears on the title of the plugin page. You can customize both names in the UI with the plugin settings.

Caution

Do not use an unpublished plugin agent to report metrics to more than one account because there may be 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.

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 Plugins UI. The agent handles three tasks:

  • Collecting data from monitored hosts, services, or devices
  • Processing data into aggregated metrics
  • Reporting metrics

The collected metric data can be any non-negative value which can be represented as an integer or a floating-point number. 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.

Each plugin agent can report metrics for multiple GUIDs which appear with separate plugin summaries in the user interface. 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.

Plugin metrics

Metrics are stored 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.

Plugin summary metrics and dashboard

Once data has been reported 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 help

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

Create issueEdit page
Copyright © 2021 New Relic Inc.