Creating summary metrics for plugins

Each component or instance for your plugin can have summary metrics, such as average, total, minimum, maximum, standard deviation, rate, or count. The summary metrics appear on your plugin's summary page in the user interface. The summary metric dashboards are also useful as a debugging tool to review all of the metrics sent by your plugin agent to New Relic Plugins. To view dashboard details about any component or instance, select any summary metric value for it.

Note: If you define negative metric values, the charts on your plugin's dashboards will not show them. However, the summary metrics for your plugin will show negative values.

Creating a summary metric

To add a summary metric:

  1. From the New Relic Plugins menu bar, select your plugin.
  2. From the plugin's summary page, select Edit.
  3. From the Summary metrics section of the plugin's editing page, select Add.
  4. On the Create a summary metric page, include the following information:
    • Title: A meaningful name for consumers
    • Metric: Metric name (case sensitive; wildcards are not allowed)
    • Value: Value function to use for the metric
    • Optional: Default alert thresholds
  5. Select Add new summary metric.

Tip: If your plugin contains only one summary metric, you can identify the metric in the chart's title and then hide the legend (colored bars that label the metrics) that normally appears below the chart.

screen summary0618.png
(selected plugin) > Edit > Summary metrics > Add: Here is an example of creating summary metrics for a plugin's components (instances).

When you first create a summary metric for your plugin, this triggers a change to New Relic's collectors. This may cause your running components (instances) to stop showing summary metrics for a short period of time. For example, if you add a new summary metric to your plugin, any components (instances) you are monitoring that use that plugin may have all summary metrics temporarily cleared. This will also close any outstanding related events and alerts. Depending on the components and other factors, you may need to wait 15 minutes or more before summary metrics appear again.

Optional: Identifying summary metric alert conditions (v2)

Note: If you do not want to receive alerts on your summary metrics, skip this section.

Plugin publishers and users can define alert thresholds from the plugin's summary page by selecting the component's gear icon icon-settings.png. When finished, select Save settings. The alerts will be activated when the summary metric's specified values fall above the thresholds.

screen summary alert0618.png
(selected plugin) > (selected component or instance) > (settings) To define alert thresholds for your plugin's components (instances), select the corresponding gear icon.

The Recent events list for the plugin's components (instances) appears on the plugin's summary page. To view additional details about an alert, select its name.

screen summary alert details0618.png
(selected plugin) > Summary > Recent events > (selected alert or event): Here is an example of an alert for a plugin's component (instance).

Sometimes there may be a delay between the time that a summary metric threshold event is triggered and the time that the New Relic Plugins product creates the corresponding incident and sends the alert notification. There are several timing mechanisms at work, such as collector caching, summary metric event timing, delayed job queues, email delivery, etc. Depending on the situation, this delay could be up to ten or fifteen minutes before the alert notification is sent.

Defining time periods for metrics

Metrics that appear in dashboards are reported with a duration. The end time is implied by the time the New Relic Plugins product receives the metric(s). Thus, you cannot define metric values that both start and end in the future, or start and end in the past.

The Plugin API is designed for live metrics only, not historical metric collection. Currently metrics may only be reported for a period starting in the past (no more than a few hours) and ending upon reporting.

The charts on your plugin's dashboards can show any time period you want; for example, 30 minutes, 30 days, etc. You can also deliver data at 1-hour intervals. Be aware that New Relic Plugins does not extrapolate data values between the data points delivered. For example, the New Relic Plugins product aggregates when there is too much data, but it does not extrapolate if there is not enough data. In order for data to appear on a 30-minute chart, make sure at least one data point is within the range, or no data will appear.

Recommendation: Use a 60-second polling interval. Default dashboards show 30 minutes of data, which gives 30 data points for the chart. Or, if you want to show 3 days of data, use a 1-hour polling interval, which provides 24*3=72 data points for your chart.

For more help

Additional documentation resources include:

Recommendations for learning more: