Versioning your plugin

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

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

Eventually the "dev" version will be ready to move to "prod." This document describes how to do so, and what your plugin's users experience will be during the process.

Plugin agents and dashboards

New Relic plugins contain two versioned parts:

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

Versioning works differently for these two parts.

Agent versioning

There are two types of agents for New Relic Plugins, 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 Versioning
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 Plugins will be the metrics available to (but not necessarily charted for) your users in their New Relic Plugins dashboards.
On-premises agents When you publish a new version of your agent (explained below), all users of your plugin will be notified in their New Relic Plugins dashboards 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 upgrade procedure in your own documentation.

Workflow for updating a SaaS agent

This sequence 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 to 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.

Follow this workflow 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 improved 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.

Workflow for updating an on-premises agent

This sequence assumes you are starting with a plugin published to 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 Plugins "knows" two different versions of your agent exist now, run the agent so that it reports metrics to the API for New Relic Plugins.
  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 "current" version for your plugin users, save it to the location where you distribute your agent code (for example, Github).
  6. From the New Relic Plugins menu bar, select your published plugin, and select Edit.
  7. From the editing page, select Save.
  8. Select Publish, and then select the new agent version you are publishing.

At this point, all users of your plugin will be prompted (via a message in their New Relic Plugins dashboard) that a new version is available. They will be directed to your listing in Plugin Central, which points to your Github repo (or other download location), from which users can acquire your new agent version.

Dashboard versioning

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 upgrade their agent (if you are offering an on-premises agent). To update your dashboard, follow the workflow below.

To clear outdated metric data while testing changes to your plugin's dashboard: From the New Relic menu bar, select (account) > Account settings > Connected agents, and select Clear metric data for one more more components (instances).

Workflow for updating a plugin dashboard

This sequence assumes you are starting with a plugin published to Plugin Central, and you want to make improvements to the dashboard portion of your plugin.

  1. From the New Relic Plugins menu bar, select your plugin name.
  2. From your plugin's summary page, select Edit.
  3. From the Dashboards section, select the Edit (pencil) or Delete (X) icon for an existing dashboard, or select Add to create a new custom dashboard for your plugin.
  4. Make changes to the dashboard in your New Relic account, then save your changes.
  5. Repeat these steps as necessary.
  6. When you are ready to publish: From your plugin's summary page, select Publish.

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

Migrate dashboards

If you need to migrate dashboards between GUIDs, get help at support.newrelic.com.

For more help

Additional documentation resources include Checklist for developing plugins (a checklist for planning, creating, and publishing your plugin).

Recommendations for learning more: