Database Mapper Remote Agents

Update: SentryOne Document is now SolarWinds Database Mapper (DMR). See the Database Mapper product page to learn more about features and licensing. Want to explore Database Mapper? An interactive demo environment is available without any signup requirements.

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 > Remote Agents to open the Remote Agents management page. 

Database Mapper Web Portal Remote Agents > Manage Remote Agents
Database Mapper Web Portal Manage Remote Agents page

Managing Remote Agents page details

Database Mapper Remote Agents page

MetadataDescription
Machine NameThe name of the machine where the Remote agent is installed.
Date RegisteredThe day and time that the Remote agent was registered with Database Mapper.
DescriptionA user entered description about the Remote agent.
Remote Agent PoolThe Remote agent pool to which the remote agent is assigned.
Last Signal receivedThe last time a successful connection was made to the remote agent.
VersionThe 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

ButtonDescriptionImage
Database Mapper Web Portal Edit description buttonSelect 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. Database Mapper Web Portal Manage Remote Agents Edit description
Database Mapper Web Portal Change pool assignment buttonSelect 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 Change Pool Assignment to save your changes.Database Mapper Web Portal Change Pool Assignment window
Database Mapper Web Portal Check Connectivity buttonSelect the Check connectivity button for a remote agent to open the Check remote agent connectivity window. Select Start connectivity check to verify the connection.Database Mapper Web Portal Check Remote Agent Connectivity window
Database Mapper Web Portal Task History buttonSelect the Task History button for a remote agent to open the Task History page for the remote agent. Database Mapper Web Portal Remote Agent Task History
Database Mapper Remote Agents Software Update History buttonSelect the Software Update History button to open the Software history window for the selected remote agent.Database Mapper Remote Agents Software Update History window
Database Mapper Web Portal Manage License buttonNote:  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. 
Database Mapper Web Portal Manage Licenses window
Database Mapper Show Running Tasks buttonSelect the Show Running Tasks button to open the running tasks window for the selected remote agent. Database Mapper Remote Agents Running Tasks window
Database Mapper Show Available Providers buttonSelect the Show Available Providers button to open the Available Providers window for the selected remote agent.Database Mapper Remote Agents Available Providers window
Database Mapper Web Portal Delete buttonSelect 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.Database Mapper Web Portal Delete Remote Agent window

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. 

Select the Update option next to an out-of-date remote agent to open the Update prompt.Database Mapper Remote Agents Update Remote Agent

Select Update to update the selected remote agent remotely. Database Mapper Remote Agents Update Remote Agent Prompt

Note: 


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.Database Mapper Open Services and Stop Remote Agent

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 SentryOne folder. Right click the Database Mapper Solution Configuration Tool, and select Uninstall to open the Control Panel.Database Mapper Solution Config Tool select Uninstall

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.

Database Mapper Remote Agent Uninstall from Control panel
Database Mapper select Yes to Uninstall Remote Agent

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.config

Logging 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

Manage your remote agents pools in Database Mapper. In Database Mapper, select > Remote Agents Pools to open the Remote Agents Pools management page.

Database Mapper Remote Agent Pool Settings

Managing Remote Agent Pools page details

Database Mapper Web Portal Manage Remote Agent Pools

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.

Use the Database Mapper Remote Agent pool page to 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:

  1. Select to open the New Remote Agent Pool window.Database Mapper Web Portal Manage Remote Agent Pools New Pool
  2. Enter a Pool name, and then select Save to create your remote agent pool.Database Mapper Web Portal Create New Pool window

Success: Your remote agent pool is ready to use! Database Mapper Web Portal Manage Remote Agent Pools New pool available

Managing remote agent pool page details

MetadataDescription
Pool nameThe name of the remote agent pool.
Agents AssignedThe number of remote agents assigned to the pool.

Managing remote agent pool buttons

ButtonDescriptionImage
Database Mapper Remote Agent Pools Add buttonSelect the button to open the New Remote Agent Pool window.Database Mapper Web Portal Create New Pool window
Database Mapper Web Portal Manage Remote Agent Pools Edit name buttonSelect 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.Database Mapper Web Portal Manage Remote Agent Pools Edit pool name
Database Mapper Web Portal Manage Remote Agent Pools Delete pool buttonSelect the Delete button to open the Delete Remote Agent pool window. Select Confirm Delete to delete the selected remote agent pool.Database Mapper Web Portal Delete Remote Agent Pool Window

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. 

Database Mapper Web Portal Change pool assignment
Database Mapper Web Portal select Remote Agent poolDatabase Mapper Web Portal Change Pool Assignment

2. Open the Remote Agent Pools page ( > Remote Agent Pools). Database Mapper Web Portal Manage > Remote Agent Pools

3. Select the Delete button for the remote agent pool you want to delete, then select Confirm Delete to complete the process.

Database Mapper Web Portal Delete Remote Agent Pool button
Database Mapper Web Portal Delete Remote Agent Pool Confirm Delete

Success: The remote agent pool has been deleted from your Database Mapper environment.Database Mapper Web Portal Remote Agent Pool deleted