Installing the Agent

Overview

If one or more of the tools you'd like to connect to are On-prem (rather than cloud-based), Viz will require you to install an agent on a server behind your firewall. A virtual machine can be used for the server if desired. 

The agent connects to your tools on-site and sends the data to Viz in the cloud. This easy deployment option is designed to ensure you do not have to punch open any incoming holes in your firewall.

Note: Viz does not support running multiple agents concurrently as it may negatively impact performance and cause errors.

Server Requirements

Requirements for the server where the agent will run are below:

If you'd like to learn more about how to prepare your network for the Viz agent, click here.

Downloading and Installing the Agent 

Once your account has been authorized by Planview, you can sign into Viz and set up the agent for access to On-prem tools.

You can access the Download an Agent guide from the Resource Center in the lower right corner or view the steps below.

Note: The agent is approximately 100 MB. 

First, navigate to the Org Settings screen from the main menu dropdown.

Note: You must download and install the agent on the server you prepared according to the system requirements here.

On the Org Settings screen, click the Tool Connections tab.

Next, click download to access the Agent Download screen.

Then, click the link to download the appropriate agent for your system.

Accessing Agent Details

After you've downloaded and installed your agent, you can view your agent details on the Tool Connections screen.

On the agent card, you can find the following details: 

• The version number of your agent
• The last ping of your agent (anything longer than a few seconds could mean that the agent is down)
• Associated tool connections
• Agent status (indicated by green or red dot; green indicates the agent is up and Viz can connect to tools, red indicates the agent is down and/or Viz cannot connect)

Note: Disabled agents are hidden from the agent card.

Disaster Recovery

A working backup strategy is a critical element of disaster recovery since only backups can mitigate complete hardware failure and user error. Regular backups of the entire Viz agent folder are an essential part of your organization’s backup strategy. If the agent server goes down or is decommissioned, a backup is required to ensure duplicate data is not sent to Viz.

Note: The backup should not be done on the same server hosting the agent, and should be done while the agent is shut down.

Connecting via a Proxy 

In order to configure the agent to communicate with ingress via a proxy, you will need to add the proxy settings to /conf/agent.conf

Note: The format in the agent.conf file can contain JSON or Key-Value pairs.

Add the proxy settings to the agent enclosure in the .conf file, as shown below:

Key-Value

agent.proxy.host = "squid.example.com"
agent.proxy.port = 3128
agent.proxy.username = "username"
agent.proxy.password = "password"

JSON

proxy {
  host = "squid.example.com"
  port = "3128"
  username = "username"
  password = "password"
}

Use the following system properties:

• host: the hostname of the proxy server (e.g., squid.example.com)
• port: the port of the proxy server (e.g., 3128)
• username: (Optional) the proxy username, if the proxy requires basic authentication
• password: (Optional) the proxy password, if the proxy requires basic authentication

Once completed, it should look like this:

Or, like this:

Migrating the Agent to a Different Host 

If the agent is migrated to a different host, ensure that the following files are moved to the corresponding location on the new host. If this step is skipped, you will risk generating inaccurate metrics due to duplicate events.

1. event-source.db.mv.db 
2. event-source.db.trace.db
3. /conf/agent.conf 
4. any files in /third-party (if using Microsoft Azure DevOps)

Troubleshooting 

Logs are provided to assist in agent troubleshooting. Logs can be found in the following location: [agent location]/logs/tasktop-agent.log

The most recent log file will be called tasktop-agent.log, while previous log files will be called tasktop-agent.YYYY-MM-DD.log.zip.

To change the location of the logs, you can update the agent.conf file. The key of the file is called log-path and should be located under the agent enclosure.

agent {
   log-path = "/some/path/to/log/directory/"
} 

Upgrading the Agent

Planview periodically releases agent updates containing bug fixes and performance-enhancing features. If an updated version of the agent is available, a pop-up will appear in the Viz UI.

​​​​​​​

You can find out which version of the agent you are on by going to agent/conf/build.conf.

You can find out the version of the newest agent by downloading the agent (from the new Tool Connection panel). The version number will be in the file name.

To upgrade the agent, please follow the steps below: