Database Mapper Remote Agents
Remote Agent Overview
What is a remote agent?
A remote agent is a service that runs in the background on a machine within your environment, and is responsible for generating the snapshots and documentation for the solutions configured within Database Mapper. It feeds the snapshot and documentation back to Database Mapper Cloud. This agent service needs to be installed on a machine that has access and permissions to the environments configured to be documented. See the System Requirements article for more details.
Where should a remote agent be installed?
The remote agent may be installed on any on-premises machine that meets the system requirements, including access to all the resources (i.e. a SQL Server) it must connect to in order to create documentation. Keep in mind that since it runs as a Windows service in the background, it can only perform the work while the machine is running. A machine that is shut down overnight will not be able to generate documentation or take snapshots during that time.
How many remote agents are needed?
In general, you should start with a single remote agent. Situations where you may need more than one remote agent include:
- You require numerous or large snapshots and they are taking longer than acceptable to complete with a single agent
- Your network environment is locked down in such a way that not one machine has access to all the resources you are trying to document. In this case, you might need to install a remote agent on Machine1 to access SQLServer1, and a remote agent on Machine2 to access SQLServer2.
What is a remote agent pool?
A remote agent pool is a grouping of remote agents in your Database Mapper environment. Database Mapper automatically creates a default system-generated remote agent pool that you can't change. When you register any remote agent, your remote agent goes into the system-generated pool by default. If you have multiple remote agents, and want to control what work they can pick up, you can group them into pools. When a snapshot is requested for a solution item, it allocates that work to any of the available agents within the pool that's associated with the solution item.
For example, you could create remote agent pools with remote agents that document only:
- your production server
- your development server
- SSIS packages
Managing Remote Agents
Manage the remote agents assigned to Database Mapper. In Database Mapper, select to open the Remote Agents management page. Starting with Version 2022.3, Remote Agents are displayed on the top and Remote Agents Pools are displayed on the bottom of the same page for streamlined management.
Remote Agents details
| Metadata | Description |
|---|---|
| Machine Name | The name of the machine where the Remote agent is installed. |
| Date Registered | The day and time that the Remote agent was registered with Database Mapper. |
| Description | A user entered description about the Remote agent. |
| Remote Agent Pool | The Remote agent pool to which the remote agent is assigned. |
| Last Signal received | The last time a successful connection was made to the remote agent. |
| Version | The software version number of the remote agent. Note: Database Mapper displays an Upgrade button by your Remote Agent if an update is available. Select Update to update your remote agent remotely. |
Managing Remote Agents page buttons
| Button | Description |
|---|---|
|
Select the Edit description button to edit the description column for the selected remote agent. Enter your desired description, and then select to save your changes. |
|
Select the Change pool assignment button to open the Change pool assignment window. Select the desired remote agent pool from the drop-down list, and then select Saveto save your changes. |
|
Select the Check connectivity button for a remote agent to open the Check remote agent connectivity window. Select Start connectivity check to verify the connection. |
|
Select the Task History button for a remote agent to open the Task History page for the remote agent. |
|
Select the Software Update History button to open the Software history window for the selected remote agent. |
|
Note: This is no longer an option or requirement in versions 2021.3 and later. Select the Manage License button to open the Manage License window. |
|
Select the Show Running Tasks button to open the running tasks window for the selected remote agent. |
|
Select the Show Available Providers button to open the Available Providers window for the selected remote agent. |
|
Select the Delete button to open the Delete Remote agent window. Select Delete Remote agent to delete the selected remote agent from the Remote Agents page. |
Updating a Remote Agent
Note:
- When using Database Mapper (the cloud version at document.sentryone.com), you will see the Update option next to the remote agent to upgrade them via the Database Mapper web interface when updates are available.
- Selecting Update also updates any other remote agents from the same installation directory.
- When using Database Mapper Software (the on-premises, self-hosted version), you must download the latest Database Mapper Remote Agent software from my.sentryone.com, then run through the installer.
- This updates all remote agents that are part of this installation.
- There's no need to stop the remote agent services before upgrading them.
- We don't recommend upgrading them while they are performing work (e.g. generating documentation or a snapshot).
Update your remote agent to the newest software version on the Remote Agents page.
1. Select the Update option next to an out-of-date remote agent to open the Update prompt.
2. Select Ok to update the selected remote agent remotely. 
Deleting a Remote Agent
You can delete any unused remote agents in your Database Mapper environment by completing the following:
1. Open Windows Services, then select the remote agent you want to delete. Right click the remote agent, then select Stop to stop the service from running.
Note: Stopping the Database Mapper Remote Agent Service makes the uninstall process easier and does not require you to restart your machine.
2. Select the Windows button, then navigate to the SolarWinds folder. Right click the Database Mapper Solution Configuration Tool, and select Uninstall to open the Control Panel.
3. Right click the Database Mapper Remote Agent that you want to uninstall, then select Uninstall to uninstall the service. Select Yes to confirm your selection.
Viewing a Remote Agent Log
If your remote agent encounters any issues or failures, you can select the Task History button for the desired remote agent. On the Task History page for the remote agent, you can view or download log output that details the issue.
Note: For a more detailed log, you can view the log output for your on premises installation at the following path:
C:\Program Files (x86)\SentryOne\SentryOne Document Remote Agent\SentryOne.Document.RemoteAgent.exe.configLogging is set to record any error by default. If you want your log to record more detailed data, you can change this configuration to debug.
Managing Remote Agent Pools Details
Starting with Version 2022.3, Remote Agent Pools are located under the Remote Agents Options on the Remote Agents page. 
Note: Database Mapper automatically creates a default system-generated remote agent pool that you can't change. When you register a remote agent, your remote agent goes into that pool by default.
Create custom pools, and move agents around between them. If you have multiple remote agents, and want to control what work they can pick up, you can group them into pools. When a snapshot is requested for a solution item, it allocates that work to any of the available agents within the pool that is associated with that solution item.
Creating a new pool
Create a new remote agent pool in the Manage Remote Agents pools page by completing the following steps:
- Select + to open the New Remote Agent Pool window.
- Enter a Pool name, and then select Save to create your remote agent pool.
Success: Your remote agent pool is ready to use!
Managing remote agent pool page details
| Metadata | Description |
|---|---|
| Pool name | The name of the remote agent pool. |
| Agents Assigned | The number of remote agents assigned to the pool. |
Managing remote agent pool buttons
| Button | Description |
|---|---|
|
Select the + button to open the New Remote Agent Pool window. |
|
Select the Edit Remote agent pool name button to open the Edit Remote Agent Pool window. Enter the desired changes, and then select Update to save your changes. |
|
Select the Delete button to open the Delete Remote Agent pool window. Select Confirm Delete to delete the selected remote agent pool. |
Deleting a Remote Agent Pool
Important: Before deleting a selected remote agent pool, you must reassign all the existing remote agents, solutions, and solution items within the pool to another pool.
Delete a selected remote agent pool from Database Mapper by completing the following:
1. Reassign any remote agents, solutions, or solution items that are assigned to the pool you want to delete. In this example, we reassign a remote agent to a different pool.
2. Select the Delete button for the remote agent pool you want to delete, then select Confirm Delete to complete the process.
Success: The remote agent pool has been deleted from your Database Mapper environment.