Working with Agents

• 1: Create an Agent
• 2: Installation Options
• 3: Network Setup
• 4: Agent Components
• 5: Installing the Agent

1 - Create an Agent

An agent is the service that takes care of collecting metrics from your instances and uploads them to our servers in the cloud. Depending on your infrastructure, you will need one or more agents, each in charge of a different set of instances. In general, an agent can collect metrics from any number of instances, as long as it is capable of contacting them, so you usually have one agent per each data center.

You can create, rename or delete agents from the Instances page, with the buttons at the top or next to the name of the agent. Every organization always contains a Default agent, ready to be installed and used. Next to the name of each agent there is a status icon that indicates whether the agent is running or not. Click on the status icon to display additional information about the agent: the name of the host it is running on, the service account and the version of the software.

Before you can add your SQL Server instances to QMonitor, you will have to install and configure at least one agent and then you will be able to register and add your instances to that agent.

2 - Installation Options

You do not need to install the agent on each instance that you want to monitor: it is not recommended to install an agent on the same machine of a monitored instance. On the other hand, while a dedicated machine specifically for the QMonitor agent is ideal, it is not a requirement. The agent itself is not a resource-intensive application and does not require vast amounts of CPU, RAM or disk.

The QMonitor agent runs on Windows and Linux and can also be run as a container: you are free to choose the installation target that fits your needs.

3 - Network Setup

Before you install an agent, please review the network requirements and make sure that your setup fulfills them.

The QMonitor agent needs to connect to your SQL Server instances, so make sure that the machine that hosts the server has the appropriate network access to the TCP/IP ports the instance is listening on. This is usually port 1433 for default instances, but the default port can be changed and assigned statically or dynamically. Please check your instance network configuration to identify which ports to open on your servers.

The agent will also need to upload all the metrics it collects to our servers in the cloud: please make sure that the machine where the agent runs can connect to the SSL port (443) on gateway.qmonitorapp.com. Please make sure that you configure your firewall to allow the connection to the host name rather than the IP address, as we use multiple servers in our gateway and your agent might be assigned to different IP addresses at different times of the day.

The agent periodically checks for updates by querying our servers for the latest available version of the software. When a new version is detected, your agent will have to download and install it from our software distribution network. In order to allow this process to complete successfully, please make sure that you configure your network to allow connections to the host static.qmonitorapp.com, again on port 443. The same advice stands for this host as well: please use the host name rather than the IP address when configuring your network, as we use a CDN network that might serve the contents from various source IP addresses.

On windows, you can test whether your agent machine is configured correctly by running this powershell script:

'gateway.qmonitorapp.com', 'static.qmonitorapp.com' | 
    Test-NetConnection -Port 443 | 
    Select ComputerName, TcpTestSucceeded

What you want to see is the following result:

ComputerName            TcpTestSucceeded
------------            ----------------
gateway.qmonitorapp.com             True
static.qmonitorapp.com              True

On Linux you can test using bash:

timeout 1 bash -c '</dev/tcp/gateway.qmonitorapp.com/443 && echo Port is open || echo Port is closed' || echo Connection timeout
timeout 1 bash -c '</dev/tcp/static.qmonitorapp.com/443 && echo Port is open || echo Port is closed' || echo Connection timeout

The output should be “Port is open” for both hosts.

If you see a different output, please investigate any connectivity issues with your network team.

4 - Agent Components

The QMonitor agent is comprised of multiple components, each writing to its own log file.

• QMonitor agent - this is the main component and the entry point of the background service. It takes care of connecting to the QMonitor servers, retrieve the configuration and start the data collection accordingly. The executable is called Quantumdatis.QMonitor.Agent.exe and it is the one invoked by the windows service.

This component is located inside the QMonitor.Agent folder under the installation folder of QMonitor (usually c:\program files\QMonitor\QMonitor.Agent). The logs are located in the logs subfolder and may contain useful information to troubleshoot your agent setup. The logfiles follow the naming pattern <organization>_<agent>-log-<timestamp>.txt

• Telegraf - this is the data collection agent, which connects to the SQL Server instances and runs the data collection queries. It also caches the metrics locally and uploads them regularly to our gateway in the cloud.

This component is located directly in the QMonitor installation folder and the executable is called telegraf.exe. The logs are found under the logs folder and follow the naming pattern telegraf_<organization>_<agent>.log

• XeSmartTarget - This is a component that takes care of streaming the events from the monitored instances to our gateway in the cloud. The executable (xesmarttarget.exe) is found in the main installation path of QMonitor and its logs are found in the corresponding logs subfolder, with the naming pattern xesmarttarget_<organization>_<agent>.log

• Autoupdater - This component ensures that your QMonitor agent stays always up to date. It runs in the background to query our servers for newer versions of the software and it downloads and runs the setup in case a new version is found. Two executables are involved: autoupdater.exe and updaterkickstarter.exe, both found in the main installation folder of QMonitor. The logs can be found in the logs directory.

5 - Installing the Agent

To start the QMonitor agent installation, download the setup kit for your operating system (Windows or Linux), copy it to the target machine, and run it. Running the agent in a container does not require installation steps and is described in “Running the QMonitor agent in a container”. The installation copies files to the chosen installation directory and requires no user input except for that directory. Additional configuration is required to authenticate the agent to your organization and to run it as a background service.

Setting up the agent on Windows

On Windows we provide two tools to configure the agent. ConfigWizard is a GUI for users who prefer a visual flow. ConfigWizardCmd is a CLI tool offering the same functionality in a scriptable, repeatable form.

Using ConfigWizard

Open the Start menu, type QMonitor, and launch the QMonitor ConfigWizard. ConfigWizard displays the organizations configured on the machine in a dropdown at the top of the window.

To add an organization, click the “+” button and enter the organization name and the organization key you obtained when creating the org.

If you lost the organization key, regenerate it from the Settings page: https://portal.qmonitorapp.com/settings. Warning: regenerating the org key invalidates the old key and causes all existing agents to stop working until they are reconfigured with the new key.

Note: the machine-safe organization name may differ from the display name. You can copy the machine-safe name from the Settings page if needed.

After the server validates the org name and key, agent names appear in the agents dropdown and you can configure agent services on this machine. The UI shows whether an agent is installed and the service account in use.

To install an agent, click the service account link, enter service credentials, and press “Install”. This creates a Windows service configured to start automatically. By default the service runs as NT AUTHORITY\Network Service.

Using ConfigWizardCmd

ConfigWizardCmd provides the same capabilities as the GUI in a CLI form that is suitable for automation. See the ConfigWizardCmd reference for parameter details and examples.

For instance, you can use a similar syntax to install an agent service:

ConfigWizardCmd.exe install --org your_organization_name --key your_organization_key --agent your_agent_name

Additional considerations

The service account is important because it is used to authenticate the agent to SQL Server instances when using Integrated Security (Windows auth). Using Integrated Security is recommended as it avoids storing passwords.

If the service runs as NT AUTHORITY\Network Service it authenticates on the network using the computer account (DOMAIN\ComputerName$). If the SQL Server instance is local to the agent host, authentication uses the Network Service account on that machine.

Windows may show a localized name for the Network Service account (for example, “NT AUTHORITY\Servizio di Rete”). To get the localized account name, run this PowerShell command:

(New-Object System.Security.Principal.SecurityIdentifier "S-1-5-20").Translate([System.Security.Principal.NTAccount])

Example output from an Italian system:

Value
-----
NT AUTHORITY\SERVIZIO DI RETE

When ConfigWizard or ConfigWizardCmd complete setup, the agent starts and begins collecting data for associated SQL Server instances. The agent also contacts QMonitor servers to report its state. On the Instances page click the green/red icon next to an agent to view its state, service account, and agent version.

Setting up the agent on Linux

ConfigWizard is not available on Linux; configure the agent using ConfigWizardCmd. See the CLI documentation for required parameters and examples.

On Linux, the agent cannot impersonate Windows users, so Integrated Security is not available. Entra (Managed Identity) authentication may be available if the Linux VM or container supports a managed identity.

Running the QMonitor agent in a container

The QMonitor agent runs easily in a container. Configure the container with a few environment variables that provide secrets and configuration options.

An example command line for docker looks like this:

docker run -d -e OrganizationName=your_organization_name -e OrganizationKey=your_organization_key -e AgentName=your_agent_name qmonitor/agent:latest