Software Private Agent

Overview

Enterprise web applications and partner-facing apps running on secure intranets and extranets demand high availability and performance. The consumer web has raised expectations for the enterprise user’s experience. Now you can monitor your enterprise system.

The Software Private Agent is a lightweight service that can be deployed to any Windows server, where it will reliably monitor performance and availability of internal applications. Because it uses real browsers, any interactive business application workflow can be simulated — even complex logical web services can be monitored. Software Private Agents are downloaded from the Dynatrace Portal and installed in minutes with just a few simple configurations. All performance data is securely managed, analyzed and alerted by the Dynatrace Advanced Synthetics SaaS platform.

You can install the Software Private Agent in any number of locations in your organization's network. You control the hardware and operating system used to run the private agent, making it easier to comply with internal security processes. Zero network configuration is required (the Software Private Agent does require internet access; see requirements below). The Software Private Agent communicates securely with our data center over SSL.

You can configure tests using just your private nodes, or combine private nodes with public Backbone nodes for a comprehensive view of your website's performance. The data is stored in a single database and is available in the Dynatrace Portal.

The Software Private Agent automatically updates itself as required, allowing you to take advantage of new features and capabilities as soon as they are available. You will receive notifications in advance of updates, so the process can cause minimal disruption.

The following diagram shows how data flows between the Software Private Agent and the Dynatrace Synthetic platform to deliver data from your enterprise system.

Requirements

Account requirements

  • Installing and configuring Software Private Agent – Users that have the Account Primary or Account Admin profile can download and configure the Software Private Agent.
  • Using Software Private Agent:
    • Users whose profiles have test configuration permissions can provision tests on Software Private Agent nodes: Account Primary, Account Admin, and Test Admin.
    • These user profiles have read-only access to the Private agents page: Operator Advanced, Perf Analyst, Scripter, and Test Admin.

For more details about profiles and access permissions, see Profiles.

System requirements

Supported environment

  • Windows Server 2012 R2

Hardware

The machine on which Software Private Agent is installed must have a C: drive and a D: drive, and must not have an R: drive. The C: and D: drives must have a minimum of 40 GB of free space each.

Sizing guidelines

Sizing the Software Private Agent is based on the following factors:

  • Desired throughput of tests per hour
  • Ratio of single-URL to multi-step tests being executed
  • Average number of steps in multi-step tests

Based on analysis of all customer usage, we use the following averages to size Backbone nodes:

  • There is a 70:30 ratio of single to multi-step tests: 70% of all tests are single-URL.
  • The median number of steps per test is 4.

Software Private Agent can be installed as a small, medium, or large installation. Assuming the averages apply to your testing requirements, the small, medium, and large installations support the following throughput:

  • Small – Up to 500 tests per hour. Requires 4 CPUs and up to 12 GB of memory.
  • Medium – Up to 1,000 tests per hour. Requires 8 CPUs and 16 GB of memory.
  • Large – Up to 4,000 tests per hour. Requires 12 or more CPUs and 24 GB of memory.

Use the attached Excel-based calculator to determine what size installation meets your throughput needs. Note that multiple private agents can be installed (at no additional cost) to achieve higher throughout when needed.

To download the Excel spreadsheet, click this link.

Enter the values for:

  • Desired test throughput (tests per hour)
  • Ratio of single-URL to multi-step tests
  • Average number of steps per test, for multi-step tests

Default values are provided for the ratio and the number of steps.

As you enter the values, the spreadsheet automatically updates the calculations and displays the recommended installation size.

If the calculated pages per hour is close to the maximum for the indicated size, we recommend using the next larger installation size.

Virtual machine environment

The requirements for a VM environment are the same as the hardware requirements listed above. Note that the network traffic generated by a large Software Private Agent deployment may affect other virtual machines on the virtualization server; conversely, other network-heavy VMs may affect accuracy of the Software Private Agent.

Network requirements

The Software Private Agent needs to be able to communicate with our data center over SSL; therefore, the machine running the Software Private Agent must have Internet connectivity. The Software Private Agent supports Internet proxy servers for basic authentication; NTLM proxy servers are not supported.

If you use a non-default port for your proxy, the port must be specified in the proxy settings. For example, if your proxy uses port 80 for a default, you need to specify:

<proxy>http://mycompany.proxy.com:80</proxy>

The default port is 443 for SSL, 1080 all others. For more information, see https://curl.haxx.se/libcurl/c/CURLOPT_PROXYPORT.html.

All network traffic originates from the Software Private Agent to the Dynatrace data center. External Internet URLs may need to be whitelisted depending on where you install the Software Private Agent in your network. If your network requires whitelisting of external IP addresses, these URLs should be whitelisted:

  • https://scheduler.spa.dynatrace.com – port 443
  • https://sitemgrapi.spa.dynatrace.com – port 443
  • https://receiver.spa.dynatrace.com – port 443
  • https://nuget.spa.dynatrace.com– port 443
  • https://scoe.spa.dynatrace.com – port 443

All these URLs use the IP address 69.84.209.65.

Internet access to the above URLs is required for the Software Private Agent Windows service (named Dynatrace Common Agent Core in Windows Services). By default, this service runs under the Local Account settings. If your corporate firewall requires a named user account for firewall access, you may need to configure the Software Private Agent service to use a named user account. If you receive a permissions error ("windows error 1297: a privilege that the service requires...") when trying to start the Software Private Agent service under a different account, you will need to adjust the security policy on the Software Private Agent server. The Software Private Agent requires the following permissions to be allowed for a user account.

Group policy setting Constant name
Act as part of the operating system SeTcbPrivilege
Adjust memory quotas for a process SeIncreaseQuotaPrivilege
Back up files and directories SeBackupPrivilege
Impersonate a client after authentication SeImpersonatePrivilege
Replace a process level token SeAssignPrimaryTokenPrivilege
Restore files and directories SeRestorePrivilege

To adjust these, run secpol.msc and select Local Policies > User Rights Assignment. For each of the Group Policy Settings listed, ensure that it is available to either the Users group, or to the specific user account you want to authorize it for. You may need to consult with your IT security team for more information.

Security considerations

The security and integrity of information are of key concern to Dynatrace. The Software Private Agent implements the following safeguards:

  • Access to the machine that runs the Software Private Agent is managed by you, the customer, and is therefore governed by your own security policies.
  • Communication between the Software Private Agent and the Dynatrace Synthetic platform is one-way from the Software Private Agent to the platform and only takes place via SSL.
  • The Software Private Agent can use proxy configuration, which allows it to communicate with the Dynatrace Synthetic platform without whitelisting URLs or ports.
  • Your Software Private Agent cannot connect to the Dynatrace Synthetic platform without a valid customer configuration file. The file is generated and downloaded from within our secure Portal. This secure configuration file ensures that measurements sent to our platform are only associated with your accounts.
  • User credentials used by test scripts that test your target application can be securely encrypted and only decrypted as needed.
  • All scripts, settings and measurements are encrypted during temporary storage on the Software Private Agent file system.

Installing Software Private Agent

Installing and configuring the Software Private Agent involves the following tasks:

  1. Download the Software Private Agent installer from the Dynatrace Portal. (From the Private agents page, and click Set up private agent.)
  2. Run the installer as administrator, following the prompts in the installer screens.
  3. Download the default configuration file to the Software Private Agent machine: copy the file to the D:\AGENT directory.
  4. Configure and register the Software Private Agent in the Private agents page.

The Software Private Agent installs files on the C: and D: drives.

The installation process also creates the R: ramdrive, which accelerates the loading of browsers to improve test throughout, but does not affect application measurements.

Prerequisites

  • Log on to the Software Private Agent machine with an account that has Windows administrator permissions.
  • Log in to the Dynatrace Portal with a username that has the Account Admin or Account Primary profile.
  • Make sure the Software Private Agent machine has a D: drive with at least 40 GB of free space, and that it does not have a drive labeled R:.
  • If the Software Private Agent will access the Internet through a proxy, make sure you have the proxy URL or IP address, the port the proxy uses, and the username and password required by the proxy. This information is required for the installation to be successful.
  • Ensure that the Software Private Agent machine's time zone is set to UTC, to prevent issues with Screen Capture on Error and maintenance windows.

Installation procedure

In the Dynatrace Portal, select  > Private Agent to go to the Set up private agent page.

  • If your account doesn't yet have any private agents, the Set up private agent page appears.
  • If the account already has private agents, the Private agents page appears. Click Set up private agent in the top right corner to display the Set up private agent page.

Click Download agent.
Save the installer file spasetup.exe to the Software Private Agent machine.

Click Download configuration to download the license.bin file.
Save the file in the same location as spasetup.exe.

Right-click the installer file spasetup.exe or the shortcut to this file, and select Run as administrator to open the installer.

Welcome screen– Click Next to begin the installation.

License Agreement screen – Click I Agree to accept the license agreement.

Software Private Agent Requirements screen – Review the drive requirements and click Next.

Private Agent Size Selection screen – Select the size based on how many tests will run on the private agent, then click Next.
See Hardware above for guidelines. The size affects how long installation may take.

Software Private Agent Proxy Configuration screen – If you access the Internet through a proxy, enter the proxy URL and port and the user credentials. Otherwise, leave the fields blank.

See Network requirements, above, for requirements for using the Software Private Agent through a proxy.

Click Install.
The installation may take 15 minutes or longer, depending on the deployment size you selected. In the Installing screen, you can click Show details to watch the progress. You can ignore icons, unzip and command windows, and Windows messages that appear during the installation unless an installer message identifies and error.
Near the end of the installation process, IE, Firefox, and Chrome browsers open and close several times depending on the deployment size.

When installation is complete, you are prompted to copy the license.bin file to the D:\AGENT directory. We recommend copying the file before you respond to the prompt. After the file is in the D:\AGENT directory, click Yes to close the message box.

Click Finish to quit the installer.

After installation is complete, go to the Set up private agent page in the Dynatrace Portal to configure the new private agent, as described in the next section.

Configuring Software Private Agent

Use the Private agents page to set up a new Software Private Agent or edit the details of a private agent.

The page lists all the private agents that have been created for your account. If a private agent is installed but not yet configured, its status is Pending.

To define a private agent's configuration details:

On the Private agents page, click the expand icon in the Edit column for the private agent.

If you've just finished installing a private agent and the Set up private agent page is displayed, click Register agent to go to the Private agents page.

Provide the identifying details for the agent:

  • Private agent name – We recommend a name that identifies the agent's location and the network on which it runs. See below for information about automatic prefixing.
  • Host name – The host name is provided during installation. It cannot be edited.
  • City, Country, and State – The state is only required for a United States location. When you select a country other than the United States, the State changes to UNKNOWN.
  • Contact name – Identify the person who should be notified if the private agent has an outage or other issue.
  • Email address – The address for the contact.
  • Phone – The primary phone number for the contact.

The Dynatrace Portal displays the Software Private Agent name as follows:

  • USA Software Private Agent: <STATE:CITY> – Private-<agentname>
    Example – Software Private Agent named SPA1 installed in Detroit, Michigan: MI:Detroit – Private-SPA1

  • Non-USA Software Private Agent: <COUNTRY:CITY> – Private-<agentname>
    Example – Software Private Agent named SPA2 installed in London, UK: UK:London – Private-SPA2

Save the information.

  • When setting up a Pending private agent – Click Register private agent.
  • When changing the details of a registered private agent – Click Update agent.

Using Software Private Agents

You can use your private agents the same as any public Backbone node. When you provision a Backbone test, you can select private agents from the Nodes and IPv6 Preferences list, including in combination with public Backbone nodes. Other test configuration details are the same as for tests that run on all public nodes. You can configure all alert types for your Software Private Agent tests.

All Software Private Agent names include the word Private, so you can quickly find Software Private Agents by searching for Private in the search field.

The only limitation is that running instant tests and diagnostics is not available for the Software Private Agent.

Editing Private Agent details

All the details in the private agent configuration can be edited except for the Host name. However, we don't recommend changing the Private agent name after the initial setup.

If, for example, you need to change Owner/Contact information, click the expand icon in the Edit column for the private agent, and enter the new information as described above.

Deleting a Private Agent

  1. In the Private agents page, click the delete icon for the private agent.
  2. When prompted to confirm the deletion, click Yes.

Deleting a Software Private Agent from the Dynatrace Portal does not uninstall the Software Private Agent. It will remain pending until you delete it on the server. To do this, log on to the Software Private Agent server using Administrator credentials, and run the D:\SPA\uninstall.exe program As Administrator (right-click the program in Windows Explorer and select Run as Administrator).

Frequently asked questions

Is there a limit to the number of Private Agents an account can install?

No.

Tests run from Software Private Agents consume XF points, the same as any Backbone test.

Can Web Recorder transactions be provisioned to run on private nodes?

Yes. Backbone tests that use the Software Private Agents are the same as any other Backbone test.

Can Backbone tests be configured to run on private nodes by default?

Yes. Select the appropriate Software Private Agents in the Backbone Test Configuration section of the Defaults page. For details, see Creating Default Backbone Test Settings.

You can also configure test templates with Software Private Agents. See Test Templates for details.

Can I use the portal's diagnostics features to check the health of my private nodes?

No. Diagnostics tests — Instant tests and Backbone analysis — are not available for the Software Private Agent.

How do we get upgrades of the Software Private Agent?

The Software Private Agents are automatically updated when an upgrade is available. You will be notified in advance when an update is scheduled, in the same way that Backbone and Private Last Mile updates and scheduled and published.