• /
  • Log in
  • Free account

Use the Plugin API

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.

Before you begin

Using a development language other than Ruby, .NET, or Java for a plugin agent means you do not have an SDK to work with, but you do have some benefits. This is a guide for plugin developers to get started with writing an agent in any language that can work directly with the Plugin API for Plugin Central.

  • You can use any language you want, as long as it supports sending JSON through HTTP POST. This allows for better integration with your systems.
  • For the same reason, it is the best option for SaaS-based plugin agents.

However, if you are not using the Plugins SDK for Java. .NET, or Ruby, you have some additional setup and planning to do in developing a plugin agent. This includes:

  • Error tracking on POST calls
  • A method for tracking and aggregating data when a POST fails
  • Your own support plans if a New Relic SDK for your language or development tools is not available

Any publicly available plugins in the Plugin Central should come bundled with their source code if the executable code is not plain text. This allows you to both try out plugins and to review the code.

Recommendation: Before authoring a plugin, install some existing plugins using the Java SDK, .NET SDK, or Ruby SDK to see how they are written.

Metric data POST

Metric data is sent as an HTTP POST of JSON data using this URI:

https://platform-api.newrelic.com/platform/v1/metrics

The MIME-type for the POST is application/json.

The Plugins feature is designed to receive a continuous stream of metrics at a certain maximum speed, and to present this information on useful charts. The recommended frequency for sending data to Plugins is to send 60 seconds worth of data once a minute. Agents sending data more frequently than twice a minute on average may be subject to enforced limits on the number of metrics being saved.

The following are recommended soft limits. Requests smaller than this will work; requests larger than this are subject to rejection or automatic data aggregation. As a hard cap, the total size of the POST payload should be no larger than 1MB (10^6 bytes).

If the metric is "expensive" to calculate and does not change quickly, consider writing your plugin agent so that it skips some polling cycles to retrieve data and then sends the last value. This produces better results for your plugin users' dashboards.

Type

Limit

Description

Components

500

Number of distinct components currently tracked. Please note this is a per POST limit only. More than 500 components are able to report to an account simultaneously.

Metrics per component

10,000

Total number of unique metrics per component. Take precautions to ensure metric names are not generated too dynamically. Even if the number of metrics being sent in each individual post is small, over time they may add up to a large number of unique metrics. When the number of metrics for a given component exceeds this limit, the server may start aggregating metrics together by globbing segments of the metric name with an asterisk (*).

Metrics per post

20,000

Number of metrics sent per post. A post may send data for multiple components in a single request as long as the total number of metrics in the request does not exceed this limit.

Frequency of post

2 per minute

Frequency of update. Agents are expected to send data no more frequently than 1 per minute.

Data aggregation

The SDKs manage data aggregation in the event of a failed POST. If you are not using an SDK, you need to manage this yourself.

  • Include all five metric values in a POST: min, max, total, count, and sum or squares. (Exception: This may not be necessary for monotonic metrics where short term variation is not an issue.)
  • Recompute these values for the accumulating metric data as required by what is being measured, incrementing the duration accordingly, until a successful POST is sent.

Compression

Data can be sent in the following encoding formats:

  • identity
  • deflate
  • gzip

If data is sent compressed, make sure the Content-Encoding header specifies the type of encoding.

Examples

Here are some examples for developing plugins.

API responses and error codes

Depending on whether you are using the Plugin API or an agent SDK for plugins, the HTTP responses and logging techniques may be different. For example, responses for the Plugin API are uncompressed JSON. Successful posts return this JSON:

{"status":"ok"}

The API does not support Accept-Encoding.

For more help

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

Create issueEdit page
Copyright © 2021 New Relic Inc.