Overview

This document describes how to upgrade to the BrightGauge v5 agent. This upgrade process must be executed for each on-premises datasource on your account. Because the v5 agent runs on an entirely new syncing architecture, the upgrade process is an automated workflow that upgrades datasets 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.)

Prerequisites

Before you upgrade to the v5 agent, please ensure that you have the following:

• Admin access to your BrightGauge account.
• Admin access to the machine hosting the existing v4 agent.
• You have installed the new BrightGauge agent.
• You have 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

Upgrade to the v5 Agent

Important: The agent v5 upgrade process must be executed for each on-premises datasource on your account.

Because the v5 agent runs on an entirely new syncing 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 agent install and datasource configuration, you do not need to manually recreate anything on your account (such as datasets, gauges, dashboards, reports, etc.).

To upgrade a datasource to the v5 agent:

1. Log in to your BrightGauge account as an admin user.
2. Navigate to Data > Datasources.
3. Select the on-premises datasource you want to upgrade.
4. Record the datasource settings (take a screenshot). You need to enter these settings when configuring the datasource for the new agent.
5. Scroll to the bottom of the datasource configuration page and click Upgrade Datasource.
   
6. Select the checkboxes to confirm that you acknowledge the information in the Upgrade Datasource modal, then click Yes, I would like to Upgrade!.

   Important: Please ensure that 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. After you click this button, the datasource connection breaks and your datasets enter a red error state until you configure the upgraded datasource with the new agent.

   Warning: Do not delete your datasource while upgrading or at any other time. Doing so causes data tied to that datasource to be permanently deleted from your account.

   
   
7. After the upgrade is complete, the datasource configuration page automatically refreshes with the new Download BrightGauge Agent header.
   
8. Download and install the new v5 agent.

   Note: Before downloading the new agent, please review the Installing the BrightGauge Agent documentation for detailed installation instructions.

9. After the v5 agent is installed, configure the datasource:
   1. Select the correct agent host from the drop-down menu.
   2. Enter the database details you documented prior to upgrading the datasource.
   3. Test the connection.
   4. Save the datasource after a successful connection test.
10. After you save the datasource settings, you are redirected to the Datasources page. For datasource-specific configuration instructions, please refer to the On-Premises Datasources documentation.
11. Repeat for each of your remaining on-premises datasources.

    Note: If you are upgrading multiple datasources that share one agent, we recommend that you upgrade one datasource at a time. Be sure to wait for the automatic dataset upgrade to complete for one datasource before upgrading another datasource.

You can monitor the upgrade process from the Datasets page (Data > Datasets). As a datasource is upgraded, its associated datasets enter a broken (red) state. Broken datasets indicate that the upgrade is still underway in the backend and that the datasets are automatically being upgraded and re-saved one by one.

In the example below, the top dataset in the list appears as Processing. If you refresh the Datasets page every few minutes, you will see the datasets successfully starting to save. The process of re-saving all datasets takes approximately 15-30 minutes, depending on the total number of datasets associated with the datasource.

Remove the V4 Agent

After all of your on-premises datasources have been upgraded to the v5 agent, you can proceed to:

• Uninstall the v4 BrightGauge Agent
  
  

  Important: Do not uninstall via Control Panel. The legacy v4 agent must be uninstalled using its own application. Failure to use the uninstaller 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 (IP exceptions, NAT routes, port forwards, etc.). The new v5 agent no longer relies on an inbound connection, therefore these rules are no longer necessary.

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

FAQs

Please see the V4 Agent Deprecation FAQs for answers to frequently asked questions about the v5 agent.