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 server running a supported Windows version, 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 Portal and installed in minutes with just a few simple configurations. All performance data is securely managed, analyzed and alerted by the Dynatrace Synthetic Classic 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. Minimal network configuration is required, for internet access (see Network 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 Synthetic Classic 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 Classic 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
  • Windows 2016
  • Windows 10, recommended for micro instances only

Hardware

The machine on which Software Private Agent is installed must have a C: drive. For medium and large installations, the machine must not have an R: drive, because an R: drive will be created during installation.

The installation drive must have a minimum of 30 GB of free space. The SPA installation requires up to 3 GB on the C: drive even if the SPA is installed on a different drive.

Important

Software Private Agent is used to accurately measure performance and availability of your web applications. Running the Software Private Agent on a machine with any memory-, CPU-, or network-intensive application may negatively affect browser measurements. For this reason, we recommend that you run the Software Private Agent on a dedicated machine or instance with no other software applications running (other than commercial anti-virus software).

A Last Mile or Private Last Mile peer should not be run on the same machine as the Software Private Agent, because this may lead to conflicts between engine versions.

Protocol Requirements

Software Private Agent is compatible with handshake protocols TLS1.0, TLS1.1, and TOS1.2. Do not use SSLv3.

The following Cipher Suites are required for installing SPA:

  • TLS1_RSA_AES_128_SHA
  • TLS1_RSA_AES_256_SHA
  • TLS1_ECDHE_RSA_AES_256_SHA
  • TLS1_ECDHE_ECDSA_AES_128_SHA
  • TLS1_ECDHE_ECDSA_AES_256_SHA
  • TLS1_RSA_AES_128_SHA256
  • TLS1_RSA_AES_256_SHA256
  • TLS1_ECDHE_RSA_AES_128_GCM_SHA256
  • TLS1_ECDHE_RSA_AES_256_GCM_SHA384
  • TLS1_ECDHE_ECDSA_AES_128_SHA256
  • TLS1_ECDHE_ECDSA_AES_128_GCM_SHA256
  • TLS1_ECDHE_ECDSA_AES_256_GCM_SHA384

For more information on updating your machine's handshake protocols and ciphers, see Troubleshooting Software Private Agent.

Sizing guidelines

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

  • Micro – Up to 150 tests per hour (2 parallel tests). Requires 2 CPUs and 8 GB of memory.
  • 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.

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.

Important

When installing the SPA on a virtual machine, you must reserve the recommended minimum memory during VM setup; otherwise medium and large installations may experience issues with the R: RAM drive. See Hardware above for the recommended memory. Consult your virtual machine documentation for details on how to do this: e.g., for VMware, make sure Reserve all guest memory (All locked) is enabled.

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 character @ is reserved and cannot be used in the proxy password.

If your test scripts require proxy servers to access applications under test, you will be prompted for this during installation.

The default port is 443 for SSL, 1080 all others. For more information, see CURLOPT_PROXYPORT explained.

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 Classic 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 Classic Platform without whitelisting URLs or ports.
  • Your Software Private Agent cannot connect to the Dynatrace Synthetic Classic 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

Important

When registering or updating a production Software Private Agent, you must be logged in to the production Synthetic Classic Portal (portal.dynatrace.com), not the EAP Portal (portaleap.dynatrace.com).

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

  1. Download the Software Private Agent installer.
  2. Run the installer as administrator, following the prompts in the installer screens.
  3. Download the default configuration file to the SPA installation directory on the Software Private Agent machine.
  4. Configure and register the Software Private Agent in the Private agents page.

The Software Private Agent installs files on the drive you designate.

The installation process for medium and large installations also creates the R: RAM drive, 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 Synthetic Classic Portal with a username that has the Account Admin or Account Primary profile.
  • If you are installing a medium or large SPA installation, make sure the Software Private Agent machine 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 Synthetic Classic 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 – Click Next to begin the installation.

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

Configuration: Software Private Agent Requirements – Review the drive requirements.

Choose Install Location – In the Destination Folder field, specify the folder in which you want to install the software Private Agent. The default location is C:\dynatrace\. Don't use either C:\Program Files or C:\Program Files (x86).

Configuration: Private Agent Environment Selection – Install the Prod version of the Software Private Agent for use with the production Synthetic Classic Portal (portal.dynatrace.com).

Configuration: Private Agent Size Selection – Select the size based on how many tests will run on the private agent. The size affects how long installation may take.

The installer screen summarizes the hardware requirements for each size:

  • Micro – 2 CPUs and 8 GB of memory
  • Small – 4 CPUs and up to 12 GB of memory
  • Medium – 8 CPUs and 16 GB of memory
  • Large – 12 or more CPUs and 24 GB of memory

See Sizing guidelines above for more information.

Installer/SPA service require access to dynatrace.com – If you access the Internet through a proxy, enter the proxy URL or IP address, the proxy port, and the user credentials if required. Otherwise, leave the fields blank.

The installer and Software Private Agent service do not support automatic proxy configuration. You must specify an explicit proxy host and port.

If proxy required for applications please specify here – If your tests need to access Internet or intranet resources through a proxy, enter the proxy URL or IP address, the proxy port, and the user credentials if required. Otherwise, leave the fields blank.

Test scripts support automatic proxy configuration. If your system is configured to use automatic proxy configuration, copy the address of the automatic configuration script to the host field (the address will typically end in a .PAC extension) and select URL specifies automatic configuration script.

Click Install.
The installation may take 10 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 installation directory. We recommend copying the file before you respond to the prompt. After the file is in the 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 Synthetic Classic Portal to configure the new private agent, as described in the next section.

Upgrading from SPA v1 to v2

Because of the significant changes in SPA v2, you must manually upgrade from v1.

Your private agents will not auto-update to v2. After you have upgraded a private agent to v2, the automatic update function will be re-enabled.

You can either maintain the same agent name and continue to run the tests on that agent after upgrading, or install the SPA v2 as a new agent.

Upgrade using the same agent name

To use the same agent name and run the same tests on that agent, you need to uninstall the existing SPA before installing the new version. The agent will remain registered in the Portal. Tests will resume execution on the upgraded agent without any further action.

Install SPA v2 as a new agent

To run SPA v2 as a new agent, install SPA v2 on a new machine and register the machine as a new Private Agent. You will need to manually add tests to the new agent.

For this choice, perform the installation and configuration procedures described above.

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 Synthetic Classic 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

We recommend renaming a Software Private Agent before deleting it, to prevent future conflicts (names cannot be re-used). We recommend adding a suffix to the name: deleted mm-dd-yy hh:mm.

  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 Synthetic Classic 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 \<SPA_installation_directory>\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.