Workbench Agent Remote [WAR] (for non Workbench Hosts)

Workbench 9.1 adds a Metric data ingestion feature that enables observability of host and process CPU, Memory, Disk and Network metric data, providing rich insights and analysis capability into host and process metric utilization, performance and trends.

For example, the Workbench Agent Remote component can be deployed on Engage hosts, for example, SIP/URS/STAT or Framework (CS, SCS, MS, DBS etc) Genesys Application Hosts.

---

Overview

With the Workbench Agent Remote (WAR) installed on a Remote Host (non Workbench), it's main function is to send Host and Process Metric event data to the local Data-Center Workbench instance/Cluster for visibility via the Workbench Dashboards and Visualizations.

Workbench Agent Remote also has an auto-upgrade capability, therefore installing Workbench Agent Remote is a one time exercise, when new Workbench or Workbench Agent Remote versions are released, the respective Workbench Agent Remote components can be automatically upgraded; please see the section below for more details on the Workbench Agent Auto Upgrade feature.

Workbench Agent and Workbench Agent Remote

Important

• Workbench Agent 8.5 is ONLY for LFMT
• Workbench Agent 9.x is ONLY for Workbench 9.x Hosts
• If/when Workbench and LFMT is deployed, both Workbench Agents 8.5 and 9.x would be needed on each remote host
  • The Workbench Agent 8.5 would be required for LFMT to collect log files from the remote hosts (i.e. sip, urs, gvp etc)
  • The Workbench Agent 9.x would be required for Workbench ingestion of data from the remote hosts (i.e. sip, urs, gvp etc)
• Workbench Agent Remote (WAR) 9.x is ONLY deployed on remote Genesys Hosts such as SIP, URS, GVP etc - this components sends Metric data to the Workbench 9.x Server/Cluster
• It's recommended not to change any Workbench Agent Remote configuration from the default settings, due to a limitation that when upgrading Workbench, all the Workbench Agent Remote configuration will be reverted back to the default settings.

---

Architecture

Workbench Cluster with a single Engage Data-Center

Important

• Workbench Agent Remote has an Auto-Upgrade feature, thereby the Workbench Agent Remote is a one time install with subsequent upgrades being autonomous (upgrade check performed at 02:00 by default).

---

Workbench Cluster with a multi Engage Data-Center

Important

• Users can only visualize Dashboard Metric data based on the Data-Center they're logged into
• .i.e. A User logged into the APAC Workbench instance/Cluster cannot view Metric data for EMEA - they need to log into the EMEA Workbench instance/Cluster

---

Components - Run-time

The Workbench Agent Remote Run-time components consist of:

• Workbench Agent Remote - executable installed as a Service
  • Start a HTTP Server for WB_IO_Primary communication
  • Sends initial configuration of the Workbench Agent Remote to Workbench ZooKeeper
  • Schedules an upgrade if/when an upgrade notification is received from WB_IO_Primary
  • Downloads any new Workbench Agent Remote package, from WB_IO_Primary
  • Validates the checksum of the downloaded package
• Workbench Agent Metricbeat - executable installed as a Service
  • Transmits Host and Application Metric data to the Workbench instance/Cluster
  • Metric data is visible via Workbench Dashboards and Visualizations
• Workbench Agent Updater - executable installed as a Service
  • Installs and starts the Metricbeat Service
  • Installs any new updates on the Workbench Agent Remote or the Metricbeat Services.
  • If the upgrade fails, a rollback to the previous version of the Workbench Agent Remote is performed.

---

Components - Installation

The Workbench Agent Remote Installation components consist of:

• installer.exe (Windows) / installer (Linux)
  • This executable file initiates the silent installation of the Workbench Agent Remote component on the respective remote host
• install_config.json (both Windows and Linux)
  • This file:
    • contains mandatory configuration used by the installer/uninstall files
    • is auto generated when the Workbench Primary Node is installed
    • can be edited - i.e. change the installation folder or ports
    • should be edited if/when certain Workbench component configuration is changed

The above components are stored on the Workbench Primary Host/Node, within directories:

Windows

• <WB_HOME_FOLDER>\Karaf\resources\windows\wbagent_9.x.xxx.xx_installscripts directory (Windows)
  • i.e. C:\Program Files\Workbench_9.x.xxx.xx\Karaf\resources\windows\wbagent_9.x.xxx.xx_installscripts

Linux

• <WB_HOME_FOLDER>/Karaf/resources/linux/wbagent_9.x.xxx.xx_installscripts directory (Linux)
  • i.e. /opt/Genesys/Workbench_9.x.xxx.xx/Karaf/resources/linux/wbagent_9.x.xxx.xx_installscripts

---

Installation Pre-Requisites

Warning

• Ensure the Workbench IO application (i.e. WB_IO_Primary is up and running before running the Workbench Agent Remote installer
  • if the WB_IO_Primary application is down, the WAR components will be installed but the associated configuration will be incomplete, resulting in a need to uninstall/install
• From a firewall perspective, ensure you open the ports below on any remote Host that will be running the Workbench Agent Remote component.
  • For WB 9.0 to 9.2, ports 9091 and 5067
  • For WB 9.3, ports 9091 and 6067

---

Installation of Workbench Agent Remote on Windows Hosts

• Copy the 2 x Pre-Install Workbench Agent Remote Windows component files detailed above:
  • from the <WB_HOME_FOLDER>\Karaf\resources\windows\wbagent_9.x.xxx.xx_installscripts directory on the Workbench Primary Host/Node
  • to C:\tmp\Workbench_Agent_Remote\ (or equivalent) directory of the remote Windows Host(s) - i.e. the Genesys Engage SIP Server Host
  • cd to C:\tmp\Workbench_Agent_Remote\
• Run installer.exe (cmd) or .\installer.exe (PS) as Administrator
  • The output/progress/result from running the executable can be found in agent_install.log

The above action has created 3 Windows Services:

• Genesys Workbench Agent Remote
• Genesys Workbench Metricbeat
• Genesys Workbench Agent Updater

Warning

• For each Workbench Agent Remote installation, the Heartbeat component is restarted, this will affect the status displayed of ALL Workbench components - therefore, post Workbench Agent Remote installation, please wait several minutes for the Workbench Heartbeat component to restart and status to recover.

Example of a new Workbench Agent Remote object in Workbench post installation

---

Installation of Workbench Agent Remote on Linux Hosts

• Copy the 2 x Pre-Install Workbench Agent Remote Linux component files detailed above:
  • from the <WB_HOME_FOLDER>/Karaf/resources/linux/wbagent_9.x.xxx.xx_installscripts directory on the Workbench Primary Host/Node
  • to the home/genesys/tmp/Workbench_Agent_Remote (or equivalent) directory of the remote Linux Host(s) - i.e. the Genesys Engage SIP Server Host
  • cd to home/genesys/tmp/Workbench_Agent_Remote
• Run sudo ./installer (as a sudo privileged user)

Warning

• Run sudo ./installer (as a sudo privileged user)

• • The output/progress/result from running the executable can be found in agent_install.log

The above action has created 3 Linux Services:

• Genesys_Workbench_Agent_Remote
• Genesys_Workbench_Agent_Updater
• Genesys_Workbench_Metricbeat

List/manage the Genesys services using:

• $ systemctl list-units --type=service --state=active | grep Genesys
• $ systemctl status Genesys_Workbench_Agent_Remote
• $ systemctl stop Genesys_Workbench_Agent_Remote
• $ systemctl start Genesys_Workbench_Agent_Remote

The above Linux Services can be located in /etc/systemd/system

Warning

• For each Workbench Agent Remote installation, the Heartbeat component is restarted, this will affect the status displayed of ALL Workbench components - therefore, post Workbench Agent Remote installation, please wait several minutes for the Workbench Heartbeat component to restart and status to recover.

Example of a new Workbench Agent Remote object in Workbench post installation

---

Workbench Agent Remote Configuration File

The install_config.json contains settings required to successfully install Workbench Agent Remote on a remote Host, these settings are automatically generated during the installation of the Workbench Primary Node/Host.

See # comments inline regarding modifications that may be required to the install_config.json file.

Example install_config.json:

{
"updater" : {
"name" : "WB_Agent_Updater_9.x.xxx.xx",
"executable" : "/opt/Genesys/Workbench_9.x.xxx.xx/updater",
#change the above if a different installation path is required
"displayName" : "Genesys Workbench Agent Updater 9.x.xxx.xx",
"description" : "Genesys Workbench Agent updater service for PureEngage environments",
"arguments" : [ "-rootPath=/opt/Genesys/Workbench_9.x.xxx.xx", "-logPath=/opt/Genesys/Workbench_9.x.xxx.xx/logs" ], 
#change the above if a different installation path is required
"yamlFile" : null
},
"root_folder" : "/opt/Genesys/Workbench_9.x.xxx.xx", 
#change the above if a different installation path is required
"wb_io_ip" : "GEN-WB-1",
"wb_io_port" : "8181", 
# change if the Workbench IO is changed from the default 8181
"wb_io_https_port" : "8181", 
#change the above if the Workbench IO is changed from the default 8181
"logstash_host" : "GEN-WB-1",
"logstash_port" : "5048", 
#change the above if the Workbench Logstash is changed from the default 5048
"datacenter_name" : "APAC", 
# change if the respective Data-Center is changed
"datacenter_id" : "2e048957-b9f1-463b-84bd-116cdf494de2",
"update_hour" : "02:00", 
#the property above should not be modified manually in the file. If needed, you can modify it in Workbench UI, in the configuration properties of the WAR application
"zookeeper_hosts" : [ "GEN-WB-1:2181" ],
"local_http_port" : "9091", 
#change the above if the Workbench Kibana is changed from the default 9091
"local_https_port" : "8443", 
#change the above if the Workbench Kibana is changed from the default 8443
#the properties below should not be modified manually, doing this will cause Workbench Agent Remote (WAR) to behave unexpectedly
"tls_server_cert_file" : "na",
"tls_server_key_file" : "na",
"tls_ca_cert_file" : "na",
"enable_tls" : false,
"enable_mutual_tls" : false,
"update_file_name" : "wbagent_9.x.xxx.xx.tar.gz",
"update_file_checksum" : "166ca35224bff0194c1d94c40e216a6ac249eca3284f92bbad39811528c95678",
"download_endpoint" : "wb/upgrade/upgrade-download",
"notify_endpoint" : "wb/upgrade/notify"
}

---

Post Installation

Validate Installation

Ensure the Workbench Agent Remote Services below are running:

• Genesys Workbench Agent Remote
• Genesys Workbench Metricbeat
• Genesys Workbench Agent Updater

If the above Services are not present, check the agent_install.log file for the highlighted terms below:

time="2020-MM-DDT13:48:34Z" level=info msg="Available disk space meets requirements for the agent installer" available_MB=145032 min_MB_needed=100
time="2020-MM-DDT13:48:34Z" level=info msg="Found installation configuration file"
time="2020-MM-DDT13:48:34Z" level=info msg="Configuration loaded"
time="2020-MM-DDT13:48:34Z" level=info msg="Downloading file from: http://WB-1:8181/wb/upgrade/upgrade-download?file=wbagent_9.x.xxx.xx.zip"
time="2020-MM-DDT13:48:34Z" level=info msg="Downloading file to path: C:/Program Files/Workbench_9.x.xxx.xx\\wbagent_9.x.xxx.xx.zip"
time="2020-MM-DDT13:48:34Z" level=info msg="Downloaded compressed file successfully"
time="2020-MM-DDT13:48:37Z" level=info msg="Files successfully extracted, compressed file:C:/Program Files/Workbench_9.1.000.00\\wbagent_9.x.xxx.xx.zip"
time="2020-MM-DDT13:48:37Z" level=info msg="Creating updater service..."
time="2020-MM-DDT13:48:37Z" level=info msg="Done creating updater service"
time="2020-MM-DDT13:48:37Z" level=info msg="Installing updater service named: Genesys Workbench Agent Updater 9.1.000.00"
time="2020-MM-DDT13:48:37Z" level=info msg="Starting updater service..."
time="2020-MM-DDT13:48:37Z" level=info msg="Updater service status: RUNNING"

---

Metric Data Transmission

Post installation, Workbench Agent Remote will send Metric (Host/Application CPU/RAM/DISK/NETWORK) data to the respective local Data-Center Workbench instance/Cluster

• Host Metric Data
  • Host CPU and RAM Metrics - enabled by default - cannot be disabled
  • Host Disk, Network and Uptime Metrics can be enabled/disabled
  • The default Host Metric transmit frequency to the respective Workbench instance/Cluster is 60 seconds

• Application/Process Metric Data
  • Application/Process can be transmitted based on Top 10 or Specific Process Names (i.e. "metricbeat.exe")
  • The Top 10 (CPU/RAM) Application/Process Metrics
  • Application/Process Metrics are summarised by default
  • The default Application/Process transmit frequency to the respective Workbench instance/Cluster is 60 seconds

Important

• Any changes to Sections 5 Host Metrics and 6 Application Metrics of the Workbench Agent Remote configuration does NOT required a restart of Services; the changes are dynamic

---

Auto Upgrade

Workbench Agent Remote has an auto-upgrade capability, therefore installing Workbench Agent Remote is a one time exercise; when new Workbench or Workbench Agent Remote versions are released, the respective Workbench Agent Remote components can be automatically upgraded based on receiving an upgrade notification from the Workbench IO application.

Each Workbench Agent Remote application installed on a remote, non Workbench host:

• will receive a notification from the Workbench IO application if/when a new Workbench Agent Remote component is available for upgrade
• has Auto Upgrade enabled by default
• checks the hash of the downloaded file to validate it matches the original upgrade notification received from Workbench IO
  • if it matches the upgrade if initiated based on the Upgrade Time value
• the upgrade on the remote Host by default will occur at 02:00 - change via Section 3. Auto Upgrade - Upgrade Time value if required
• the Section 3. Auto Upgrade - Upgrade Time value can be changed for each Workbench Agent Remote application
  • providing flexibility as to when the auto upgrade check/action will be initiated.

---

Auto Upgrade - Example Steps to upgrade the Workbench Agent Remote (WAR) Application

• In Workbench Configuration > Applications, for each of the Workbench Agent Remote (WAR) applications, set the desired upgrade time (default is 02:00).
  • The upgrade time is relative to the destination machine where WAR is installed
    • e.g. if the WB time is Eastern time-zone and WAR machine is in Pacific time-zone, the time must be in Pacific time-zone.
• Delete (archive to a different folder) any previous/existing Workbench Agent Remote (WAR) package (wgagent_9.x.xxx.xx.zip or wbagent_9.x.xxx.xx.tar.gz) files within
  • <WB_HOME_FOLDER>/Karaf/resources/windows/data for Windows
  • <WB_HOME_FOLDER>/Karaf/resources/linux/data for Linux
• Copy the new WAR package (.zip or .gz) file to
  • <WB_HOME_FOLDER>/Karaf/resources/windows/data for Windows
  • <WB_HOME_FOLDER>/Karaf/resources/linux/data for Linux
• The checksum for the new package will be calculated (this will take a few minutes)
• After the checksum is calculated, an upgrade notification is sent to Workbench Agent Remote (WAR)
• Once Workbench Agent Remote (WAR) receives the notification, it will schedule the upgrade
• The Workbench Agent Remote (WAR) upgrade will automatically occur based on the upgrade time
• The Workbench Agent Remote (WAR) Application will be automatically restarted
• The Workbench Agent Remote (WAR) will now be running the updated package

Warning

• Please note that if the Upgrade Time is updated after the new WAR package is copied, the time change will take effect based on the old time value and not the new updated time
• Workbench upgrades starting from version 9.1 will automatically trigger the upgrade of any WAR components that existed prior to the Workbench upgrade.
• The respective Workbench Agent Remote (WAR) components, installed on hosts such as SIP, URS, GVP etc, will be upgraded based on the WAR Upgrade Time (default 02:00)
• For WB 9.3 the WAR [General] section Log File Location, Segment and Expire fields will be blank post an upgrade until the WAR Upgrade Time (default 02:00) is triggered and the WAR upgrade is completed

Auto Upgrade - Upgrade Time

---

Auto Upgrade Sequence Diagrams

The diagram below details the Workbench agent Remote installation and upgrade functions:

---

Uninstallation - Windows Hosts

• On the respective Remote Host(s) - i.e. UK-SIP-1
• cd to C:\Program Files\Workbench_9.x.xxx.xx\ (or equivalent) directory
• Run uninstall.exe (cmd) or .\uninstall.exe (PS) as Administrator

The above action will remove the 3 x Windows Services:

• Genesys Workbench Agent Remote
• Genesys Workbench Metricbeat
• Genesys Workbench Agent Updater

An uninstall.log is also created detailing the uninstallation progress.

Important

• Workbench Agent Remote will no longer send Host and Application Metrics to the Workbench instance/Cluster, therefore Dashboard visualizations will not present any data for the respective host(s) that have had Workbench Agent Remote uninstalled.

Warning

• Post Workbench Agent Remote uninstall, the uninstall.exe and uninstall.log files will need manual deletion

---

Uninstallation - Linux Hosts

• On the respective Remote Host(s) - i.e. UK-SIP-1
• cd to /opt/Genesys/Workbench_9.x.xxx.xx/ (or equivalent) directory
• Run sudo ./uninstall (as a sudo privileged user)

Warning

• Run sudo ./uninstall (as a sudo privileged user)

The above action will remove the 3 x Linux Services:

• Genesys_Workbench_Agent_Remote
• Genesys_Workbench_Metricbeat
• Genesys_Workbench_Agent_Updater

An uninstall.log is also created detailing the uninstallation progress.

Important

• Workbench Agent Remote will no longer send Host and Application Metrics to the Workbench instance/Cluster, therefore Dashboard visualizations will not present any data for the respective host(s) that have had Workbench Agent Remote uninstalled.

Warning

• Post Workbench Agent Remote uninstall, the uninstall and uninstall.log files will need manual deletion

---