Skip to content

New Relic One App Catalog How To Guide

Jump to bottom
John P Vajda edited this page Jan 21, 2022 · 15 revisions

Welcome

The New Relic One Catalog of applications are open source applications that are available to New Relic customers to use within the New Relic One Platform. This WIKI outlines some of the technical nuisances of these applications for users and teams that need a deeper understanding of this open source ecosystem.

Application Categories

New Relic's applications can be grouped into different open source categories. This WIKI focuses primarily on applications that are tagged as New Relic One Catalog.

  • Community Project
  • Community Plus
  • New Relic One Catalog
  • New Relic Experimental
  • Archived

Common Terms

Term Definition Notes
Global UUID The unique identifer for an application there is a global UUID used to identify the app in the App Catalog
Local UUID the identifier for a localized application after cloning an application repository this UUID is generated by the developer who has created their own version of the application
3rd party applications created internally or externally and made available to all customers Basic users can view details on these apps but can’t open/use them
1st party applications created internally and controlled by feature flags Available to all customers only when feature flags are set to 100%
Global apps applications globally available to all users in the App Catalog Available in the Global App Catalog
Custom apps applications available to only a customer instance of the App Catalog These are applications deployed to your NR1 Account and only available to users who have access to that account
Artifact Registry an internal database of Global UUIDs for applications Supported by #NR1-Platform-Services
app subscriptions how a user account is given access to an app subscribing applications is only possible with certain user roles
nerdpacks the entire React application learn more about building apps
nerdlets React components with the React application learn more about building apps
launchers a CTA type element that opens up a nerdpack learn more about building apps
visualizations React based elements used for visualizing data learn more about building visualizations
NR1 CLI an CLI used to develop applications for the NR1 Platform The NR1 CLI is available to download within the NR1 App Catalog

Resources

Resource Purpose
New Relic Developer Site Technical "how-to" guides focused on Developers
NR1 App Catalog Checklist How to add an app to the NR1 App Catalog
3rd Party App Community Github Project A project board for all of the 3rd Party Catalog application repositories
New Relic OpenSource Site A collection of open source projects at New Relic.
NR1 Catalog Repository New Relic One Catalog "repo of repos"

Global UUID vs Local UUID

The Global UUIDs are available in the nr1-catalog repository Whenever a new app is added, it's UUID is added to that global file. All the Catalog apps are published under the NR1 Apps account, which is a special account that sits as a parent to every other account (and that's the mechanism by which customer accounts can self-subscribe when they add an app through the Catalog).

Whenever an app update occurs, the UUID referenced in that globals file is copied to the nr1.json first, and then a publish occurs (that all happens in the CI workflow). That's how the UUIDs are kept in alignment.

New Relic doesn't particularly care what the UUID is in the source repository (Local UUID) since any user is free to pull that down and instructed (from the README) to run nr1 nerdpack:uuid -gf before they run the app.

Therefore when making global changes to the application in the Catalog in regards to category of the application or deploying an updated version of the application the Global UUID should be referenced.

Contributor workflow

Contributors who wish contribute code or content to applications in the App Catalog can do so by visiting an application's specific Github Repository. The easiest way to locate the repository for an application is by searching the project tag: New Relic One Application on the New Relic Open Source site.

When contributing to a project please be available for code review feedback and resolve that in a timely manner.

Global App Catalog Deployment workflow

In order to deploy to the Global New Relic One Catalog you'll will need to be an employee of New Relic.

  1. Make sure the app version has been updated in the package.json either manually or via conventional commits.
  2. Use the NR1 catalog manager nerdpack in the staging account to add or update the application. This will trigger a PR in NR1 Catalog Repository.
  3. Review the PR with New Relic App Catalog maintainers.
  4. Merge the change to trigger a publish/deploy to Production.
  5. If successful, the application will updated automatically for the US Production environment.
  6. Make a @hero request in the #help-NR1-Platform-Services Slack channel with the app/s you’d like updated in Staging and EU, their versions, and their Global UUIDs
  7. When completed, you've successfully updated all apps in all environments!

Removing an App from the Nr1 Catalog

To remove an application from the Catalog you'll also need to change an application's category. In order to make these changes you will need to be an employee of New Relic.

In some cases an app that is available in the NR1 App Catalog may no longer need to exist in the Catalog. Before removing it from the Catalog you will have to consider the following:

1. Conduct a litmus test for an application’s “health”

  1. Is an application even being used? Or is the usage low enough where it no longer makes sense to keep the repository open to the public.
  2. Does the applications repository have recent activity in the form of:
  • Forks
  • Stars
  • PRs
  • Issues
  • Issue Comments
  1. Is there anyone at the company STILL that actually built the applications early release?
  2. Is there an app maintainer? If so are they still able to contribute to the applications development?
  3. Is there a team that is willing to be a maintainer of the applications?

You can use this internal dashboard to construct some NRQL queries to analyze this data for a particular app. Please note that the name of the nerdpack application you want to query with can be found in the displayName field in the nr1.json file.

2. Analyze usage and decide

After evaluating an application's activity a decision should be made if an application is even worth supporting or if it should be Archived or converted to Experimental.

In doing this analysis you can also decide if a warning message in the form of an application banner, or toast should be added to the application prior to the change of the application category. This would be necessary to warn users who need to be aware of the change to the application they use.

3. Removal from the Catalog

You'll need to make a request to remove the application from the Catalog.

  1. Obtain the Global UUID for the application.
  2. Run the subscriptionModel mutation (nerd life post) and change it to OWNER_AND_ALLOWED via the production endpoint, this will remove it from the catalog and disable the ability to subscribe to the app for anyone not on the 3rd party global app accounts. There is no need to do this for the staging or eu endpoints as the state of the production version dictates the other two.
  3. Make a @hero request in the #help-NR1-Platform-Services Slack Channel.
  4. Request that all accounts are unsubscribed from the application (provide the Global UUID)
  5. Use the nr1 cli to undeploy the nerdpack under the Nr1-Apps (production) account. Platform services will need to undeploy it from staging and eu

Example Message

@hero could you confirm if there are any customer accounts subscribed to this app? App name global UUID If so, can you manually (ie. go into the database) unsubscribe those accounts? Could you also undeploy it in staging and eu?

4. Converting to Experimental

You will need to change the application open source category project banner in the source repository.

An Experimental Application solves an interesting problem but does not yet have an active maintainer(s). The project is being developed in the open for the purpose of feedback on a new feature or function.

By changing an application from Catalog to Experimental:

  • You will be removing the app from the Nr1 Catalog and the source code will need to maintained by the community.
  • Issue triage, PR reviews and other maintainer responsibilities will be handled by the community.

5. Archiving an application

You will need to change the application open source category project banner in the source repository

An Archived Application is one that has read-only source code. There is neither a maintainer team, active development nor support.

You will also need to officially archive the repository in Github. That can be done by following the Archiving repositories guide.

By changing an application from Catalog to Archived:

  • You will be removing the app from the Nr1 Catalog and the source code will no longer be maintained.
  • Issues triage, PR reviews and other maintainer responsibilities will no longer occur.
  • Active development will no longer occur on the application.

6. Removal of Sub Modules from The Catalog

Applications that exist in the Catalog are made available via GIT sub modules. In order to remove these sub modules from the Catalog you will need to do the following:

Example PR

  1. git submodule update --init --recursive
  2. git submodule deinit <path_to_submodule>
  3. git rm <path_to_submodule>
  4. git commit -m "fix: removed submodule"
Clone this wiki locally