Working with Agent Settings
ThousandEyes Agents provide a variety of settings to customize their behavior to your needs. This article describes menu choices under the Cloud & Enterprise Agents and Endpoint Agent areas.
Cloud and Enterprise Agents can be configured through the Cloud & Enterprise Agents > Agents Settings menu. You'll see some or all of the following menus, depending on your account's permissions and those of your organization. Agent configuration in the UI is organized as follows:
- 1.Agents tab, containing the Clusters, Notifications, and Kerberos Settings tabs
- 2.Cloud Agents listing tab
- 3.Agent Labels list and label creation tab
- 4.Proxy Settings list and proxy configuration tab
Enterprise Agents are lightweight Linux-based software agents that run tests configured in the ThousandEyes platform, and that upload the results to ThousandEyes for aggregation and analysis. For a fuller description of Enterprise Agents, see What Is an Enterprise Agent. If you have a role with the View agents in account group permission, such as the default Account Admin or Organization Admin roles, you can view the Enterprise Agents listing.
If the account group has installed at least one Enterprise Agent, the Cloud & Enterprise Agents > Agent Settings > Enterprise Agents menu displays a listing of the Enterprise Agents, under the Agents tab:
- 1.Agents/Clusters/Notifications/Kerberos tab: Click the tab to display listings of either individual Enterprise Agents, or Enterprise Agent clusters. Select or configure Notification Rules and Kerberos Settings under these tabs.
- 2.Search box: Enter a text string to search for your agent(s). The string can be either text or an IP address. The Agent Name, Hostname and public and private IP address fields (visible when an agent's row is expanded) will be searched. Matches are displayed in the listing.
- 3.Total Agents: The number of Enterprise Agents assigned to this organization.
- 4.Account Group filter: Display either the Enterprise Agents assigned to the current account group or those Enterprise Agents not in the current account group. The sum of the two categories should be the number displayed in #3. The user must have View agents in account group permission to view Enterprise Agents in the relevant account groups. Click the column header to sort in one of two directions.
- 5.Agent Name: Displays the name given to the Enterprise Agent, located in the Agent Name field. Click the column header to sort in one of two directions.
- 6.Hostname: Displays the hostname given to the Enterprise Agent. The hostname is either a name or a domain name, taken from the 'hostname' command run on the agent. Click the column header to sort in one of two directions.To the left of the hostname are icons indicating the following:
- The agent runs an IPv4 TCP/IP network stack.
- The agent runs an IPv6 TCP/IP network stack. An agent can be only one of IPv4 or IPv6, but not both.
- The agent is configured to use an HTTP proxy.
- The agent is a member of an Enterprise Agent cluster.
- 7.Utilization: The highest percentage of the currently active Agent Utilization queues (visible when an agent's row is expanded). Utilization queues measure the amount of test time slots used for various types of tests. As utilization values near 100%, tests of the type measured by the queue are more likely to fail to run before the next round of tests commences, producing a "No data" result for the agent running the test. Click the column header to sort in one of two directions.
- 8.Status/Last Contact: The time since the Enterprise Agent last contacted the ThousandEyes collector. The Last Contact of the agent-collector connection is rendered with a green dot if the agent status is "Online". If the agent has not contacted the ThousandEyes collector for more than .5 hour, the status is set to "Offline" and rendered with a red dot. If the agent has been disabled, the status is set to "Disabled" and rendered in grey. Click the column header to sort in one of two directions.
- 9.Options menu**:** Reveals options to perform below specified actions on the agent:
- Delete: Clicking this option permanently deletes the agent from the account group.
- Disable: Click this to disable the agent. Disabled agents will continue to contact the ThousandEyes collector to determine whether they have been reenabled. Disabled agents do not collect test results, but do remain configured, allowing for easy re-enabling in the future. Disabled agents do not count towards an organization's limit of concurrent Enterprise Agents, but may count towards the monthly quota, depending on when and how long the Enterprise Agent was deployed.
- 10.Add New Enterprise Agent button: Reveals a side pane with Enterprise Agent install options arranged in tabs based on Package Type.
Click on the row of any Enterprise Agent to expand the row for access to the Agent Settings. The Agent Settings will display three tabs: Basic Configuration, Advanced Settings and Agent Statistics. Additionally, panels on the right provide detailed agent information and some administrative options. Note that the Basic Configuration will not be visible if the agent is assigned to an Enterprise Agent cluster, and other parts of the interface will change or to reflect the agent's membership in the cluster. Information no longer available under the agent will be available under the agent's cluster.
Basic Configuration
- 1.Agent Name: The name of the agent. This can be modified in the ThousandEyes agent settings UI by a user having a role with the _Edit agents_ permissions.
- 2.Country: Obtained from a geolocation service based on the public IP address of the agent. Can be overridden using the pull-down selector.
- 3.Region: Obtained from a geolocation service based on the public IP address of the agent. Can be overridden using the pull-down selector.
- 4.Account Groups: Displayed for users having a Role with the Edit Agents permissions and whose organizations contain more than one account group. Shows the account groups to which the Enterprise Agent is assigned and allows agents to be shared across account groups. To share with another account group, expand the pull-down selector and check the box next to the account group.
- 5.Tests: Displays a list of tests to which the agent has been assigned. Users having a Role with the Edit Tests permission can add or remove tests assigned to this agent.
- 6.Agent notifications: Click this checkbox to enable agent Notification Rules to the agent, which will notify users of agent downtime or other agent conditions. The selector below the checkbox is used to assign or edit Notification Rules.
- 7.Warnings: Displays details of agent conditions requiring user attention.
- 8.Labels: A list of the user-defined and built-in agent Labels to which the agent belongs. Click the down-arrow icon to list the names of the agent Labels or to add the agent to an agent Label. The Labels box will not be visible if the agent is assigned to a Cluster. To configure an agent Label, navigate to Cloud & Enterprise Agents > Agent Settings > Agent Labels tab.
- 9.Cluster/Member of Cluster: Click the Add agent to cluster link to add this Enterprise Agent to an Enterprise Agent Cluster. If the agent is already assigned to a Cluster then the Cluster's name will be displayed. Click the X next to the Cluster name to remove the agent from the Cluster. For more information about adding and removing agent from a cluster, see Working with Enterprise Agent Clusters.
- 10.General Info: Displays the following information:
- Primary Account Group: The name of the account group under which the agent was created (Account Group Token for Installation from the listed group was used to install the agent).
- Created: The date the agent was installed.
- Private IP Address: The IP address assigned to the agent system's interface, and to which the agent is bound.
- Public IP Address: The IP address that the ThousandEyes collector sees during communication with the agent.
- Operating System: The agent's operating system type and version.
- Agent System Time: Time reported by agent's clock.
- Agent Version: The version of the ThousandEyes agent software (te-agent package)
- BrowserBot Version: The version of the BrowserBot software for Page Load and Transaction tests (te-browserbot package)
- Installation Type: Linux, Virtual Appliance or Docker container
- 11.System Info: Click this link to display several categories of information about the system, including the contents of the Agent's config file (te-agent.cfg).
- 12.Reset Appliance Password: Present only for ThousandEyes Virtual Appliances. Click this link to reset the web admin user interface's password back to the default ("welcome"). The agent must have connectivity to the ThousandEyes collector to reset the password in this way. Console access also can be used to reset the password via a text menu.
- 13.Cancel: Click this button to cancel changes to the agent Settings.
- 14.Save Changes: Click this button to save changes to the agent configuration.
Advanced Settings
- 1.IPv6 Policy: Choose a name resolution policy for non browser based tests. Below are the available options:
- IPv4 Only
- Prefer IPv6
- Force IPv6
- 2.Target for Tests IP Address: Used by Network/Agent-to-Agent and RTP tests to specify the IP address that the testing Agents will use to target this Agent. By default, this is the IP address of the agent's network interface. Normally, if the testing agents' packets are traversing the public Internet, the Target for Tests field should be set to the IP address shown in the Public IP Address field on the Basic Configuration tab. If the testing agents' packets are traversing a private network, the Target for Tests field should be set to the IP address shown in the Private IP Address field of this Agent Settings page.
- 3.Behind a NAT: Check this box to enable NAT traversal. Checking this box will allow agents running Network/Agent-to-Agent tests to initiate connections to this Enterprise Agent if it is behind a NAT'ing firewall or similar device without the need for port forwarding rules on the device. For more information on NAT traversal, see NAT Traversal for Agent-to-Agent Tests.
- 4.Verify SSL certificates for browser tests: Check this box to verify the chain of SSL certificates when running Page Load or Transaction tests. Leave the box unchecked to ignore certificate-related errors, such as self-signed certificates, expired certificates, certificates whose CN fields do not match the URL used to access the resource, etc. Note that this is an agent-wide setting, so will apply to all Page Load or Transaction tests assigned to this agent.
- 5.Proxy Option: Select an appropriate proxy option for scheduled tests. Below are available choices:
- Direct: Do not use proxy.
- Enterprise Agent's proxy configuration: Use proxy configured in agent's config file(te-agent.cfg).
- Specific proxy configuration: Choose from in-app proxy configurations (see the Proxy Settings section in this article).
- 6.Enable Kerberos: Enables Kerberos authentication for agent. Credentials are configured on the Kerberos Settings tab (see the Kerberos Settings section in this article).
Agent Statistics
- 1.Agent Uptime: A graph of the agent's connection to the ThousandEyes collector over the past 7 days.
- 2.Agent Utilization: This section charts the agent Utilization per Test type for the last 24 hours. Only those Test types which the Agent is running are displayed. Utilization for a ThousandEyes Enterprise Agent means the amount of time slots in the test queue that are filled by running tests. A high utilization indicates that the agent is barely managing to complete all tests assigned to it, each round.
If you have a role with the Edit agents permission, such as the default Account Admin or Organization Admin roles, you can add new Enterprise Agents. To add a new agent, navigate to the Agents tab of Cloud & Enterprise Agents > Agents Settings and click Add New Agent. A side modal containing agent install methods with hyperlinks to respective Install Guide opens, with tabs based on Package Type.
Click the Show Account Token for Installation link, and copy the account token to your clipboard or similar location so that you can paste it when needed during the installation. Be sure to handle the account token with appropriate security, as it provides a means of affecting your usage of ThousandEyes resources. Note that the account token is specific to your current account group. All Enterprise Agents installed with this account token will belong to this account group.
If the account group has configured at least one Enterprise Agent cluster, the Settings > Agents > Enterprise Agents menu displays a listing of the Enterprise Agent clusters, under the Agents tab:
For an organization's Enterprise Agents, notifications can be generated on three types of event:
- Last Contact: Represents the last contact with the ThousandEyes collector. The default time limit is 30 minutes (agents normally contact the ThousandEyes collector every minute). Notifications can be set to trigger when the value is less than or greater than a defined time limit in minutes.
- Clock Offset: Represents the offset in seconds of the Enterprise Agent's time from true value. The data collected by ThousandEyes requires accurate timestamps. If an Enterprise Agent's clock varies from the ThousandEyes collector's time by a significant fraction of the frequency of any test the agent is running, then the test data can be affected. Most commonly, this condition arises when the agent cannot reach the agent's Network Time Protocol (NTP) servers via the network. Notification rules can be configured to ensure that the agent's clock drift generates a notification.
- Agent Version is Outdated: Triggered when the Agent Version from the Cloud & Enterprise Agents > Agents Settings > Enterprise Agents tab indicates the agent's version is less than the current version available. Normally, Enterprise Agents automatically update their agent software, but if conditions prevent update, notification can be generated.
Navigate to the Cloud & Enterprise Agents > Agents Settings > Enterprise Agents > Notification tab and click the Add New Notification Rule button to add a new rule or click on a row to expand the row and view the settings of an existing rule. As with any alert or notification rule, some period of experimentation may be required to tune the criteria so that the rule is neither too noisy nor failing to notify users of valuable events.
- 1.Search: Enter a text string to search for Notification Rules based on the name of the Rule.
- 2.Name: The name of the Notification Rule. Click the column title to sort in one of two directions.
- 3.Conditions: Lists the conditions of the Notification Rule.
- 4.Agents: Indicates the number of Enterprise Agents to which this Rule has been assigned.
- 5.Default: Check this box to assign the Rule to all agents created subsequent to the Rule becoming a default. There is no limit to the number of Default Rules.
- 6.Options button: Reveals options to Delete and Duplicate the Notification Rule.
- 7.Add New Notification Rule button**:** Opens up a side pane with blank notification rule form.
When an agent notification is sent out via email or webhook, the notification can be confused with an "alert notification", as they use similar terminology. While the agent notification does come from "[email protected]" and has an "Alert ID", these are not related to the alerts found in the Alerts List menu, and are not shown in that list.
At this time, there is no ability to search for agent alerts using the "Agent Alert ID" provided in the notification email.
To add a new notification rule, navigate to Notifications tab of Cloud & Enterprise Agents > Agents Settings and click Add New Notification Rule to reveal the below side pane:
Configure appropriate values for the settings below:
- 1.Notification Name: The name of the Notification Rule. Be aware that there is no uniqueness constraint on Notification Names.
- 2.Enterprise Agents: Click the selector and check the boxes of the Enterprise Agents to which this Notification Rule will be assigned.
- 3.All/Any operator: Set the selector to Any (logical OR) or All (logical AND) which applies to the conditions listed below.
- 4.Conditions: As explained above, Last Contact, Clock Offset or Agent Version is Outdated, along with the appropriate operator and operand, if applicable.
- 5.Add/remove conditions: Click + to add a new condition or - to remove an existing condition. A minimum of one condition is required.
- 6.Notification tab: Configure notifications for this rule.
Once done, click Add to create the notification rule.
The Kerberos Settings tab is where configurations for this method of authentication are listed. Typically an Enterprise Agent authenticating to a Microsoft Windows Server will use this method. Navigate to the Cloud & Enterprise Agents > Agents Settings > Enterprise Agents > Kerberos tab to list or create a new configuration. To setup new authentication schemes click the Add Kerberos Configuration button. Fill in Configuration Name, Realm, Username, Password, Kerberos Key Distribution Center (KDC) Host, KDC Port, Whitelisted IP address range or subnet. Then add an associated Enterprise Agent.
The list of domains under the Whitelist field indicates which domains are authorized to negotiate with Chromium. This is a required parameter for browser-based tests in order to perform HTTP authentication using kerberos credentials.
If your organization has access to ThousandEyes Cloud Agents, the Cloud Agents menu will be present. Navigate to Cloud & Enterprise Agents > Agents Settings > Cloud Agents to see this listing. Our Cloud Agents are installed around the world in major cities and on six continents giving our customers access to performance data from local transit providers and last-mile ISPs to simulate end user performance. Choose from this list to view the Name, Primary Provider, Country and number of tests using these agents. To see a map of our existing Cloud Agents, visit the ThousandEyes website.
- 1.Search: Enter a text string to search for Cloud Agents based on the agent name or location.
- 2.Agent Name: Indicates the geographic location (city and state or city and country) as well as indicating an IPv6 Agent.
- 3.Group: Displays the group to which the Cloud Agent belongs.
- 4.Provider: Provider information shown where a single provider is used for at least 30% of outbound routes.
- 5.Country: The country in which the Cloud Agent is located.
- 6.Tests Selector: Add the agent to tests within your account group by opening the Tests selector and checking the boxes for the required tests.
- 7.Labels: Displays the list of agent group to which the Cloud Agent belongs.
- 8.IPv6 Policy: Shows the name resolution policy for non browser based tests.
Labels can be setup to organize resources listed in the ThousandEyes platform. To organize Enterprise Agents under a particular group Navigate to the Cloud & Enterprise Agents > Agents Settings > Agent Labels tab. Organizing more than one agent under a particular color and named label can expedite test and alert configuration by selecting the label then leafing through the list.
List or configure proxy settings under the Cloud & Enterprise Agents > Agents Settings > Proxy Settings tab. Add new settings by clicking the Add New Proxy Configuration button. For a detailed description of proxy server settings, see Configuring an Enterprise Agent to Use a Proxy Server.
These proxy settings can be assigned as an agent wide setting for tests or as a per-test configuration from test settings for Web Layer tests.
The per-test proxy setting is given more priority over the agent wide in-app configuration which is then prioritized over the proxy configured at agent level.
Note: These configurations only apply to tests assigned to selected agents. Do not affect connections to ThousandEyes services.
For instructions on deploying the right type of Endpoint Agent for your organization, see this article. If you do not have access to the Endpoint Agent and would like more information, contact your account representative. You can contact ThousandEyes Sales from the Billing tab of the Account Settings view.
If your account group has access to ThousandEyes Endpoint Agents, the Endpoint Agents menu will be present. To configure Endpoint Agents, navigate to the Endpoint Agents > Agents Settings menu to reveal the Endpoint Agents, Proxy Settings and Agent Labels tabs.
- 1.Endpoint Agents/Proxy Settings/Agent Labels: Access agent list, add New Endpoint Agents. Configure Proxy Settings and create customer labels for your Endpoint Agents.
- 2.Filters: Available filters for agent list include Location, ASN, User, Status, Version, Platform, Agent Type, Label, Browser Extension Status, VPN Vendor, VPN Gateway Address, VPN Client Address, VPN Client Network.
- 3.Search: Search for Endpoint Agents based on the hostname, username, or OS version.
- 4.Name: The hostname of the system as returned by the Endpoint Agent.
- 5.Agent Version: Version of the Endpoint Agent.
- 6.Browser Extension: Shows status of installed Browser.
- 7.Current Location: Displays the Endpoint Agent's current location.
- 8.Last Contact: The time since the report by the Endpoint Agent to the ThousandEyes collector.
- 9.Warnings: When an agent experiences a condition requiring the user's attention, a red warning triangle will appear next to the agent Name. Expand the row to view the details of the warning
- 10.OS Version: The operating system and version as returned by the Endpoint Agent.
- 11.Options button: Reveals options to Delete agent or Transfer Ownership to another account group on click.
- 12.Proxy: Select a specific proxy configuration for scheduled HTTP Server test, these configurations can be added from the Proxy Settings tab. By default System Proxy of an Endpoint Agent is used.
- 13.Agent Settings: Displays a list of properties about the system hosting the agent.
- 14.Disable: Click this button to block the results from an Endpoint Agent session from appearing in the list of sessions. If an Endpoint Agent is disabled, this button will become an Enable button.