• /
  • Log in
  • Free account

Maintain plugin versions

Limited access


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.

Plugin agents and dashboards

As a plugin publisher, typically you need to have two versions of your plugin running simultaneously:

  • The stable production version that users can acquire from Plugin Central in New Relic
  • A development version that you are actively improving, testing, or otherwise have in a non-production state

Plugins contain two versioned parts:

  • The agent collects metrics from the source and transmits those metrics to the Plugin API.
  • The dashboard is a collection of visualizations and configurations that you make in the Plugins user interface. Plugin users view this automatically from their own Plugins dashboards in New Relic.

Versioning works differently for these two parts.

Agent versioning

There are two types of plugin agents, with two different versioning situations:

  • SaaS agents are agents that you, the SaaS application developer, deploy and run on behalf of your SaaS users.
  • On-premises agents are agents that your users install into their systems.

Plugin agents


SaaS agents

There is only one copy of this agent running anywhere (the one you developed and deployed on behalf of your users), so whatever version you are running will inherently be the latest version. Whatever metrics the latest version is sending to New Relic will be the metrics available to (but not necessarily charted for) your users in their Plugins dashboards.

On-premises agents

When you publish a new version of your agent, all of your plugin users' dashboards will note that a new agent version is available. They will be directed to your Plugin Central listing, where they can download and install the new version of your agent.

Recommendation: Provide a streamlined agent update procedure in your own documentation.

Update a SaaS agent

This procedure assumes:

  • You are starting with a plugin published to the Plugin Central (the production version).
  • Your plugin has a SaaS agent running inside your app, and you want to make improvements to the SaaS agent portion of your plugin.
  • As part of your normal development process you have a second dev version of your agent running, which is not published in Plugin Central.
  • Your plugin's dev version uses a different GUID (for example, com.company.service.plugin.dev).
  • Both your dev and your production plugins have the same plugin dashboards.

To update your plugin's SaaS agent:

  1. Make changes to your dev agent.
  2. Do not change the version number or GUID of your dev agent in the agent config file.
  3. When you are ready to make your latest dev agent the production agent for your customers, follow your standard procedures to deploy your dev code to production.
  4. If applicable, make any necessary changes to your plugin's dashboards.

Your users will receive no notification, and they do not need to take any action. You didn't change the version number, so your agent changes are transparent to your users.

Update an on-premises agent

This procedure assumes you are starting with a plugin published in Plugin Central, and you want to make improvements to the on-premises agent portion of your plugin.

  1. Make a copy of your agent code.
  2. Change the version number in the agent config file.
  3. To ensure that New Relic knows two different versions of your agent exist now, run the agent so that it reports metrics to the Plugin API.
  4. Continue working on your agent and making improvements, but do not change the version number again.
  5. When you are ready to make this new agent version the latest version for your plugin users, save it to the location where you distribute your agent code (for example, GitHub).
  6. From the New Relic UI, select your published plugin, select Edit, and then select Save.
  7. Select Publish, and then select the new agent version you are publishing.

At this point, all of your plugin users will see a notice in the Plugins UI that a new version is available. They will be directed to your listing in Plugin Central, which points to your download location. From there your users can acquire your new agent version.

Update plugin dashboards

If you add metrics to your agent, be sure to add them to charts on your dashboard, and then save your dashboard and re-publish. All your users will see the new dashboard, and the new metrics will either be populated immediately (if you are running a SaaS agent on their behalf) or as soon as they update their agent (if you are offering an on-premises agent).

If you need to migrate dashboards between GUIDs, get help at support.newrelic.com. Otherwise, to update your dashboard, follow this workflow. These steps assume you are starting with a plugin already published in Plugin Central, and you want to make improvements to the dashboard portion of your plugin.

  1. Go to one.newrelic.com > More > Plugins, and select your plugin's name.
  2. From your plugin's summary page, select Edit > Dashboards, then add, edit, or delete dashboards.
  3. When you are ready to publish: From your plugin's summary page, select Publish.

At this point, all of your plugin users will see your new dashboard version the next time they select your plugin's dashboard in the New Relic UI.

For more help

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

Create issueEdit page
Copyright © 2021 New Relic Inc.