Overview

This document outlines the steps on how to upgrade from the BrightGauge Agent v4 over to v5. Please make sure you read this ENTIRE document before executing any steps. Certain steps will BREAK your Datasource connection and dataset syncs until you configure the Datasource with the new agent. 

 

What is the BrightGauge Agent v5?

The new BrightGauge Agent v5 is a completely rewritten application with upgraded performance, enhanced security, and improved ease of use. The biggest changes on the v5 agent include:

• A completely new syncing architecture that uses a heartbeat check-in and push methodology
  • No inbound network connections, therefore no need for firewall configurations.
• Increased timeout ranges on connections and syncs
  • Fewer timeout errors.
• New token-based authentication
  • No dependency on a single user's credentials
• New installation and management UI
  • Agent software installs in just a few minutes and runs strictly as a service 
  • New UI within the Datasource configuration page allows you to easily keep track of all v5 agent instances that you have installed

 

How do I upgrade to the new v5 Agent?

The Agent v5 upgrade process must be executed for EACH on-prem Datasource on your account. Due to the fact that the Agent v5 runs on an entirely new synching architecture, the upgrade process is an automated workflow that upgrades all of the datasets over from the old v4 syncing architecture. This means that apart from the actual agent install and Datasource configuration, there is NO need for anything on your account to be recreated manually (this includes datasets, gauges, dashboards, reports, etc.). To upgrade a Datasource, please follow these steps:

 

Step 1 - Ensure that you have:

• Admin access to your BrightGauge Account
• Admin access to the machine hosting the existing v4 agent
• Documented the current database details for each Datasource you are upgrading. This includes (but is not limited to):
  • Database IP
  • Database Name
  • Database Port
  • Database username and password

Step 2 - Log on as a local or domain administrator to the device currently hosting the existing v4 agent.

Step 3 - Open up a web browser (preferably Chrome as it is our recommended web browser) and navigate to your BrightGauge account (https://YOURSUBDOMAIN.brightgauge.co)

Step 4 - Log in to your BrightGauge account as an Admin user.

Step 5 - Click on the "Data" menu on the top righthand corner of the screen and select "Datasources" from the dropdown menu:

 

Step 6 - Click into the on-prem Datasource you wish to upgrade:

 

Step 7 - Once on the Datasource configuration screen, take a screenshot of the current details/info listed for that Datasource. (You will need this info again when reconfiguring the Datasource after the upgrade.)

Step 8 - Scroll all the way down to the bottom of the Datasource configuration page and click on the green "Upgrade Datasource" button:

 

Step 9 - Read and acknowledge the points listed on the "Upgrade Datasource?" pop-up modal:

IMPORTANT NOTE: Please make sure you have read the rest of this document and are completely ready to execute the remaining steps prior to clicking the "Yes, I would like to Upgrade!" button. The moment you click this button, your Datasource connection will break and your Datasets be in a red error state until you configure the upgraded Datasource with the new agent.

Additionally, make sure that you DO NOT DELETE YOUR DATA SOURCE while upgrading, OR at another time. Doing so will cause data tied to that data source to be permanently deleted from your account.

 

Step 10 - Once upgraded, the Datasource configuration page will automatically refresh and load up with the new header below: 

It is now time to download and install the new v5 agent. Before downloading the new agent, please review the entire "Installing the BrightGauge Agent" document for detailed installation instructions.

Note: You do not have to worry about removing the previous agent yet (especially if other non-upgraded Datasources are still using it). The new agent can run concurrently on the same machine as the old agent without any issues. 

 

Step 11 - Once the v5 agent is installed, you can now proceed to finish configuring the Datasource by:

• Selecting the correct agent host from the dropdown menu
• Entering the database details that you documented prior to upgrading the Datasource
  • Database IP, Database name, Database Port, Database username and password.
    
• Testing the connection
• Saving the Datasource after a successful "Test Connection"

Step 12 - Once you successfully save the upgraded Datasources, the page will automatically redirect you to the general Datasource page listing all of your Datasources. You can now navigate to the Datasets page using the link on the left-hand side:

 

Please do not be alarmed when you see all of the datasets associated with the Datasource being upgraded in a red/broken state:

The upgrade is still underway in the backend and each dataset is automatically being upgraded and resaved one by one. Note that the top dataset will appear as "Processing". If you refresh this page every few minutes, you will see the datasets successfully starting to save. The entire automated process of resaving all of the datasets will take an average of 15-30 minutes, depending on the total number of datasets you have associated with that particular Datasource.

 

Step 13 - If you have any other on-prem Datasources on your BrightGauge Account, you will need to follow this upgrade workflow for each one accordingly. 

NOTE: If you are upgrading multiple Datasources that are SHARING one agent, it is best to do one at a time. In other words, be sure to wait for the automatic dataset upgrade to be completed for one Datasource before upgrading another Datasource.

 

Step 14 - After ALL of your on-prem Datasources have been upgraded to the v5 Agent, you can then proceed to:

• Uninstall the legacy v4 Agent following this Article: Uninstalling the BrightGauge Agent
  
  • Please DO NOT uninstall via Control Panel. The legacy v4 Agent MUST be UNINSTALLED using its own application. Failure to do so may result in unnecessary items remaining in the registry as well as the service ending up in an odd state. 
• Remove firewall rules that had been previously created for the v4 agent
  • This includes IP Exceptions, NAT Routes, Port Forwards, etc
  • The new v5 agent no longer relies on an inbound connection, therefore none of these rules are longer necessary. 

If you experience any issues, please contact Support by selecting Help > Open a Ticket from the top menu bar.