Register a SQL Server Instance

Add a SQL Server Instance to QMonitor

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.

Connection String

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.

  • Instance name: The name of the SQL Server instance. For default instances, this is the server name where SQL Server is running. For named instances, use the format 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.
  • Port: (Optional) Enter the port number if your SQL Server instance is not running on port 1433 and the instance name cannot be resolved to a TCP port by the SQL Server Browser service. You can leave this field blank most of the time.
  • Authentication: QMonitor supports three authentication methods:
    • SQL Server Authentication: Uses the username and password you enter in the form. Your credentials are part of the connection string and stored encrypted in our database.
    • Active Directory - Integrated (Windows Authentication): The easiest and safest option. The agent contacts the SQL Server instance using the Windows service account it runs under. No passwords need to be entered or stored.
    • Active Directory - Managed Identity: Uses an Azure Managed Identity to connect to SQL Server instances. This is also a safe option for running the QMonitor agent on an Azure VM or in an Azure Container App with a User-Assigned Managed Identity. See the documentation for Azure VMs and Azure Container Apps to learn about configuring a Managed Identity for your services.
  • Additional connection parameters: Enter any connection string properties that cannot be entered in a specific field. The connection string format must comply with the .NET connection string format (property=value). For a complete list of properties and values, see the .NET documentation.
    If you have an existing connection string to paste, enter it here. It will be parsed and all properties will be automatically placed in the corresponding text fields.

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:

  • Can Connect: Can the agent connect to the instance? If not, the error message is displayed in this window.
  • XE Session: QMonitor uses Extended Events to capture meaningful events from the server, such as deadlocks, blocking events, and errors. For this to work, you need to create an Extended Events session called QMonitor that captures these events. See the “Set up your SQL Server instance” section for more information.
  • Is Sysadmin: QMonitor can work without sysadmin role membership. However, sysadmin permissions ensure that the agent has access to all the DMVs it will query. It also ensures that the agent and its components, such as the Extended Events session, stay up to date. Using a sysadmin login also allows QMonitor to execute scheduled jobs that may interact with the instance.
    If you use a login without sysadmin permissions, you are responsible for granting all required permissions. QMonitor provides a setup script for this purpose. See the “Set up your SQL Server Instance” section for a detailed breakdown of the script and how to use it to prepare your instance for monitoring.
  • Permissions: In this section, you can check whether the QMonitor agent has access to all required DMVs and system tables for monitoring.
    • Sysschedules: Read access required to monitor SQL Server Agent jobs
    • Sysjobschedules: Read access required to monitor SQL Server Agent jobs
    • Syscategories: Read access required to monitor SQL Server Agent jobs
    • Sysjobs: Read access required to monitor SQL Server Agent jobs
    • Sysalerts: Read access required to monitor SQL Server Agent jobs
    • SysmailConfiguration: Read access required to monitor SQL Server Agent jobs
    • Syssessions: Read access required to monitor SQL Server Agent jobs
    • Sysjobactivity: Read access required to monitor SQL Server Agent jobs
    • Sysjobhistory: Read access required to monitor SQL Server Agent jobs
    • AgentDatetime: Read access required to monitor SQL Server Agent jobs
    • CalculateAvailableSpace: This is a scalar function created by QMonitor in the master database to calculate available space on database files. This shows as Ok if the function exists and the agent has permissions to invoke it.
    • ConnectAnyDatabase: This server-level permission allows the QMonitor agent to connect to all user databases in the instance to query database-specific DMVs. This permission does not grant access to user tables inside databases.
    • ViewServerState: This server-level permission allows QMonitor to query many DMVs to inspect the instance state.
    • ViewAnyDefinition: This server-level permission controls access to object definitions in all databases. Does not grant permissions to read data in user databases.

Other instance information

  • Name: This field is read-only. It contains the name that the instance returns when you query the @@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.
  • Acknowledge to use sysadmin rights: When the QMonitor agent connects using a sysadmin login, you will be prompted to confirm that this is acceptable. The use of a high-privileged login will be under your responsibility. This is especially important for QMonitor jobs, which will not run against this instance unless you check this box. You can also acknowledge your consent to use sysadmin permissions at the organization level, setting the default for new instances in the Manage Organization section.
  • Engine Edition: This field is also read-only. It contains the engine edition, as returned by SERVERPROPERTY('EngineEdition').
  • Edition: Read-only. Contains the edition of this SQL Server instance, as returned by SERVERPROPERTY('Edition'). See the page for SERVERPROPERTY for more information.
  • Description: Enter a description of your SQL Server instance in this field. Use a meaningful description that helps you search the list of instances and document what the instance is used for.
  • Tags: You can add tags to your instance to organize and categorize it. Add as many tags as you want by clicking the “New Tag” button and typing the text for the tag. Remove existing tags by clicking the “X” button on the tag itself. Tags help document your instance and can change how Issues are created on the instance, overriding default behavior for specific tags. See the Issues section to learn how tags work.
  • Group: Instances can be added to one group, which can be part of another group. Access the groups page from the Instances page to create a tree of groups to categorize your instances.
  • Agent: Use the drop-down list to assign your instance to one agent. Changing the agent after adding the instance requires a new validation process. During validation, the agent will verify it can contact the instance and query the required monitoring DMVs.
  • Enabled: When this box is checked, QMonitor will monitor the instance. When unchecked, no metrics will be collected.
  • Obfuscate SQL Text: Check this box if you want the text of all SQL commands processed to remove all constants that may contain sensitive data. For example, an application might run commands like this:
    INSERT INTO Customers (id, name) VALUES (1,'Quantumdatis')
    This SQL text could reveal that Quantumdatis is your customer. By obfuscating the SQL text, the command is captured like this:
    INSERT INTO Customers (id, name) VALUES (1,'<value>')

Considerations for Always On availability groups

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.