This is the multi-page printable view of this section. Click here to print.
This section provides step-by-step instructions for setting up and using QMonitor.
You will learn how to:
Follow these guides to get the most out of QMonitor.
Go to the login page located at https://portal.qmonitor.app and click on the “Register” button.
You will be taken to the registration form, where you can enter your email and your chosen password. The password needs to be 20 characters at least. Using a password manager to generate and store your password is strongly advised.
We use a captcha validation system to protect our systems from bots. In case you didn’t pass the captcha validation, a message appears on the form. Please try entering your credentials again, maybe clicking around a bit more to differentiate from what a bot would do.
After you submit the form, our servers will process your registration request and send a confirmation email to the address that you entered. The email will contain a link that you can click to verify your email.
Please allow a couple of minutes for the email to reach your inbox. In case you don’t get the email in a couple of minutes, please check your spam folder: we do our best to avoid ending up in your spam, but sometimes it just happens. If you still the confirmation email is nowhere to be found, you can request a new confirmation email by visiting the “Resend email confirmation” page at https://portal.qmonitor.app/Identity/Account/ResendEmailConfirmation
Once your email is verified, you can proceed to log in to QMonitor using the credentials that you provided.
Follow these steps to log in to QMonitor:
If you have enabled 2FA for your account:
You can enable or disable 2FA on the Account page.
If you forgot your password:
We strongly suggest the use of a password manager.
When you log in to QMonitor for the first time you are met with a welcome page that will ask you if you want to create a new organization or join an existing one. In order to monitor and maintain SQL Server instances you will need to be part of an organization.
When you create a new organization, you will be simply asked to provide a name for it. The name that you enter will be “sanitized” by QMonitor, in order to remove any special characters in the name that might make it hard to work with. The name that you entered will still be used as it is as the display name of you organization, but the internal name of the organization will be the sanitized one. QMonitor will also generate a code called “Organization Key”, that you will have to provide during the setup of a new agent. Please note down carefully both the organization name and the Organization key, as you will need them later. For this purpose, the use of a password manager is highly recommended. Before you proceed, you will have to confirm that your codes are successfully stored in a safe location, by clicking the corresponding checkbox on the form.
Another important piece of information required to create your organization is the location of the data: you can choose one of the available regions (EU and US for the time being, more coming in the near future). Please choose the region that matches your needs, not only in terms of latency and bandwidth, but also in terms of regulatory constraints. While we do not store any sensitive data, your company might be subject to specific policies that prescribe to store all the data inside the boundaries of a particular region. Please check with your CISO to make sure that you choose the correct option. There is currently no option to move your organization from one region to another.
When you are ready, click the “Create new organization” button. Creating an organization requires around 20 seconds: please wait until the process completes. You will be met with a welcome message and a quick help dialog window that provides information on how to register your instances and start monitoring them.
When you log in to QMonitor for the first time, you see a welcome page. This page asks if you want to create a new organization or join an existing one. You must be part of an organization to monitor and manage SQL Server instances.
To join an existing organization, you need an invitation from the organization owner.
Important: New users must register for QMonitor before they can join your organization. They should:
This is how your coworkers gain access to the organizations you create.
This section will help you set up QMonitor to accomplish the most common tasks, such as installing an agent, registering an instance and start the data collection.
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.
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.
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.qmonitor.app. 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.qmonitor.app, 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.qmonitor.app', 'static.qmonitor.app' |
Test-NetConnection -Port 443 |
Select ComputerName, TcpTestSucceeded
What you want to see is the following result:
ComputerName TcpTestSucceeded
------------ ----------------
gateway.qmonitor.app True
static.qmonitor.app True
On Linux you can test using bash:
timeout 1 bash -c '</dev/tcp/gateway.qmonitor.app/443 && echo Port is open || echo Port is closed' || echo Connection timeout
timeout 1 bash -c '</dev/tcp/static.qmonitor.app/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.
The QMonitor agent is comprised of multiple components, each writing to its own log file.
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
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.
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.
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.
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.qmonitor.app/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.
See the full ConfigWizardCmd documentation in installation_cmd.md.
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
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.
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.
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
ConfigWizardCmd is the command-line tool used to install and manage QMonitor agents.
On Linux, it is the only available configuration method.
On Windows, it is an alternative to the graphical ConfigWizard tool and is suitable for automation, scripting, and DevOps pipelines.
This page documents all commands supported by ConfigWizardCmd, their parameters, and typical usage patterns.
ConfigWizardCmd is shipped together with the QMonitor agent kit and exposes several commands (verbs):
| Command | Description |
|---|---|
set-key | Registers or updates the organization key. |
install | Installs and starts an agent service. |
uninstall | Removes an agent service. |
start | Starts an installed agent. |
stop | Stops a running agent. |
set-serviceaccount | Updates the service account used by the agent service. |
network-check | Tests DNS, TCP, and TLS connectivity to QMonitor endpoints. |
help | Prints built-in help text. |
General syntax:
ConfigWizardCmd <command> [options]
Before installing agents, register the organization’s key:
ConfigWizardCmd set-key --org MyOrg --key your_organization_key
This command will validate the key and update any installed agents.
If the key is invalid, the command exits with an error.
To install an agent named Default:
ConfigWizardCmd install --org MyOrg --agent Default --key your_organization_key
During installation, ConfigWizardCmd performs:
--user and --password are provided (Windows only), that account is used.| Option | Description |
|---|---|
--user <name> | Windows service account username |
--password <pwd> | Password for the service account (hidden in CLI) |
Example with a custom account:
ConfigWizardCmd install --org MyOrg --agent Default --key your_key --user DOMAIN\User --password P@ss123
Start a service:
ConfigWizardCmd start --org MyOrg --agent Default
Stop a service:
ConfigWizardCmd stop --org MyOrg --agent Default
These commands interact directly with the OS service manager and do not require a key.
Remove an agent completely:
ConfigWizardCmd uninstall --org MyOrg --agent Default
This will:
You can change the credential under which an agent runs:
ConfigWizardCmd set-serviceaccount --org MyOrg --agent Default --key your_organization_key
A secure credential prompt appears:
The CLI prompts for:
Username:
Password:
After updating credentials, the service is automatically restarted.
Validate that the agent can connect to QMonitor servers:
ConfigWizardCmd network-check
This tool performs:
Example output:
[INFO] api.qmonitor.app -> 2606:4700:...
[ OK ] api.qmonitor.app:443 - TLS established (Tls13)
Useful for troubleshooting firewalls, proxies, and outbound restrictions.
When your agent is installed, it appears on the Instances page with a “running” status. You are now ready to register a SQL Server instance.
Click the “New Instance” button at the top. You will be taken to a page where you can enter the details for your instance.
The most important information is the connection string that the agent uses to contact and query your SQL Server instance. Click the edit button next to the connection string to open a dialog that helps you enter all required information. If you already have a complete connection string, you can paste it in the dialog.
server\instance. The host name you enter must be resolvable
by DNS on the machine where the agent runs. Make sure name resolution works correctly. Use fully qualified domain names (FQDN)
if required by your network setup.When your connection string is ready, click the Verify button on the right. A dialog window will appear with the validation results.
Many aspects are checked at this stage:
@@SERVERNAME property.
You cannot change this name or use a network alias like a CNAME record in your DNS. However, you can use an alias in the connection string.SERVERPROPERTY('EngineEdition').SERVERPROPERTY('Edition'). See the
page for SERVERPROPERTY for more information.INSERT INTO Customers (id, name) VALUES (1,'Quantumdatis')
INSERT INTO Customers (id, name) VALUES (1,'<value>')
When you register a SQL Server instance in QMonitor, make sure you are not adding an Always On listener. QMonitor will not allow you to add a listener. You must add the instance where the AG is defined instead. To check the state of the AG with the HA dashboard, we strongly recommend adding all the nodes in the AG setup.
QMonitor agents are monitoring your instances by running queries against multiple DMVs and system tables at regular intervals. Before you can add an instance to QMonitor, you will need to set up the instance in order to grant the required permissions and create additional objects such as the Extended Events session “QMonitor”.
The read access to those DMVs is granted either through sysadmin role membership or through grants on the individual objects.
QMonitor does not strictly require sysadmin role membership to collect the bare minimum information to populate the dashboards with performance metrics: if you decide not to grant sysadmin role membership to the QMonitor agent login, you can still monitor your instances by granting permissions on the individual DMVs and system tables. Additional permissions may be required to perform daily checks or to execute QMonitor jobs.
QMonitor offers a setup script that you can download from the Instances page: you can load the script in Management Studio to review the actions it performs and provide the parameters to set up the instance correctly.
At the very top of the script, you can provide the values for three required variables:
Once you provided values for all the three variables you can execute the script and review the results. If any error is returned from SQL Server, please review it, correct the cause and execute once again.
When the script executes successfully, the instance is ready to be added to QMonitor and the verification dialog will display all the checks as “Ok”. The check for sysadmin privileges may still display as “Ko” if you decided not to grant sysadmin role membership: you will still be able to proceed with the registration of the instance.
The Instances page allows you to list, create, edit and delete registered SQL Server instances.
At the top you have buttons to perform several actions:
At the top of the list is a search bar. Use it to filter the instances shown on the page. Enter any keyword to display servers with a matching name, description, tag, or other text field. You can also enter a version number, such as “2022”, to show only servers with that version.
The list of instances is grouped by agent and by groups/subgroups:
Agent Default
├─ Group A
│ ├─ Subgroup X
│ │ ├─ Instance 1
│ ├─ Instance 2
│ ├─ Instance 3
│ ├─ Instance 4
├─ Group B
│ ├─ Subgroup Y
│ │ ├─ Instance 5
│ │ ├─ Instance 6
│ ├─ Instance 7
│ ├─ Instance 8
Agent Custom
├─ Instance 9
├─ Instance 10
Next to each Agent name, you have the following controls:
Nested inside the agents, you may have instances directly, or groups and subgroups that contain instances.
The instance name is a hyperlink to the Instance Overview dashboard. Next to the name, you have:
If the instance is an Azure SQL Database, Azure SQL Database Pool, or Azure SQL Managed Instance, a blue tag will appear.
On the right side of the list, you have the following controls:
Content coming soon.