Install & configure NRDOT for MSSQL monitoring with CLI

You can install and configure the NRDOT Collector for SQL Server monitoring using the New Relic CLI. The CLI installs the collector, creates or authorizes the monitoring identity, and configures the collector in a single command.

Tip

To install this through the New Relic UI instead, go to one.newrelic.com > Integrations & Agents > MSSQL (OpenTelemetry) . Follow the on-screen instructions to set up the integration.

Prerequisites

A New Relic account with a valid license key.
A New Relic account ID.
Microsoft SQL Server 2017 or later.
Self-hosted SQL Server:
- SQL Server Authentication: A Linux or Windows collector host, and a login in the sysadmin server role (or equivalent) with its password.
- Windows Authentication or gMSA: A Windows collector host, an administrator PowerShell session, and a Windows account or gMSA with the required permissions.
SQL Server on AWS RDS:
- A Linux or Windows collector host with network connectivity to the RDS endpoint (inbound access granted on the SQL Server port within the RDS security group), alongside the RDS master username and password.
- Windows Domain Authentication or gMSA: A Windows collector host and an RDS instance already joined to an AWS Managed Microsoft Active Directory domain.
Linux collector host: The curl utility, systemd, and the sqlcmd utility installed and available on PATH (or located under /opt/mssql-tools18/bin or /opt/mssql-tools/bin).
Windows collector host: The sqlcmd.exe utility installed and available on PATH.
Network connectivity to the New Relic OTLP endpoint corresponding to the target region.

Install and configure the NRDOT Collector

This recipe monitors one or more SQL Server instances from a single collector. Instead of prompting for a single host/port/credential set, it reads two files you create ahead of time: an instances file (YAML) listing every instance to monitor, and a secrets file (KEY=VALUE) with an admin login and password for each, indexed to match.

Create the instances file. Add one entry per SQL Server instance you want this collector to monitor, or just one entry if you're only running a single instance:
bash
```
$cat > ~/mssql-instances.yml << 'EOF'
$instances:
$  - host: localhost
$    port: 1433
$    login_name: newrelic
$EOF
```
Create the secrets file with an admin login and password for each instance, indexed to match the instances file's order. The admin login must be a member of the sysadmin role (or equivalent):
bash
```
$umask 077
$cat > ~/mssql-secrets.env << 'EOF'
$NR_CLI_MSSQL_ADMIN_USER_1=<YOUR_ADMIN_USERNAME>
$NR_CLI_MSSQL_ADMIN_PASSWORD_1=<YOUR_ADMIN_PASSWORD>
$EOF
$chmod 600 ~/mssql-secrets.env
```

Linux:

bash

$curl -Ls https://download.newrelic.com/install/newrelic-cli/scripts/install.sh | bash && sudo NEW_RELIC_API_KEY=INSERT_YOUR_API_KEY NEW_RELIC_ACCOUNT_ID=INSERT_YOUR_ACCOUNT_ID NEW_RELIC_REGION=INSERT_YOUR_REGION /usr/local/bin/newrelic install -n nrdot-collector-mssql

Windows (run in an Administrator PowerShell session):

[Net.ServicePointManager]::SecurityProtocol = 'tls12, tls'; $WebClient = New-Object System.Net.WebClient; $WebClient.DownloadFile("https://download.newrelic.com/install/newrelic-cli/scripts/install.ps1", "$env:TEMP\install.ps1"); & PowerShell.exe -ExecutionPolicy Bypass -File $env:TEMP\install.ps1; $env:NEW_RELIC_API_KEY='INSERT_YOUR_API_KEY'; $env:NEW_RELIC_ACCOUNT_ID='INSERT_YOUR_ACCOUNT_ID'; $env:NEW_RELIC_REGION='INSERT_YOUR_REGION'; & 'C:\Program Files\New Relic\New Relic CLI\newrelic.exe' install -n nrdot-collector-mssql

The CLI prompts interactively for the following variables. You can also set them ahead of time as environment variables to run non-interactively.

Variable

Description

Default

NR_CLI_MSSQL_CONFIG_PRESET

NRDOT configuration:

1 for Basic
2 for Advanced

1

NR_CLI_MSSQL_INSTANCES_FILE

Required. Path to the instances YAML file.

None

NR_CLI_MSSQL_SECRETS_FILE

Required. Path to the secrets file (KEY=VALUE, one admin login/password pair per instance).

None

Tip

To monitor more than one SQL Server instance from this collector, add more entries to the instances file and matching numbered credentials (_2, _3, ...) to the secrets file. An instance that fails its checks is skipped with a logged reason rather than aborting the whole install. The install only fails outright if none of the instances pass.

This method is only supported on a Windows collector host. It uses Windows authentication (integrated security=true) instead of SQL logins, and monitors one or more SQL Server instances from a single collector. The collector is one Windows service with one logon account, and connects to every instance as that account, so a multi-instance install always uses one auth mode and one Windows identity, granted on every instance you list.

Create the instances file. Add one entry per SQL Server instance you want this collector to monitor, or just one entry if you're only running a single instance. Only host and port are needed (no login_name, no secrets file):
```
instances:
  - host: sql01.contoso.com
    port: 1433
  - host: sql02.contoso.com
    port: 1433
```
Save this anywhere on the collector host, for example C:\mssql-instances.yml. For a named instance, use host plus its static TCP port rather than host\INSTANCE.

Before you run this command, have ready:

The instances file from step 1
Whether you're using a Windows account or a gMSA account
For Windows Authentication: whether the collector runs on the same host as SQL Server, or on a different host
The Windows account (or gMSA account) to grant permissions to (not needed if the collector runs on the same host as SQL Server)
Whether you want Basic or Advanced metrics

Run this in an Administrator PowerShell session:

[Net.ServicePointManager]::SecurityProtocol = 'tls12, tls'; $WebClient = New-Object System.Net.WebClient; $WebClient.DownloadFile("https://download.newrelic.com/install/newrelic-cli/scripts/install.ps1", "$env:TEMP\install.ps1"); & PowerShell.exe -ExecutionPolicy Bypass -File $env:TEMP\install.ps1; $env:NEW_RELIC_API_KEY='INSERT_YOUR_API_KEY'; $env:NEW_RELIC_ACCOUNT_ID='INSERT_YOUR_ACCOUNT_ID'; $env:NEW_RELIC_REGION='INSERT_YOUR_REGION'; & 'C:\Program Files\New Relic\New Relic CLI\newrelic.exe' install -n nrdot-collector-mssql-winauth

The CLI prompts interactively for the following variables. You can also set them ahead of time as environment variables to run non-interactively.

Variable	Description	Default
`NR_CLI_MSSQL_CONFIG_PRESET`	NRDOT configuration: `1` for Basic `2` for Advanced	`1`
`NR_CLI_MSSQL_AUTH_MODE`	SQL Server authentication: `1` for Windows Authentication `2` for gMSA	`1`
`NR_CLI_MSSQL_WINAUTH_LOCATION`	Windows Authentication only: `1` if the collector runs on the same host as SQL Server (the installing user's identity is used and the service stays `LocalSystem`, so no domain account is needed) `2` if it runs on a different host	`1`
`NR_CLI_MSSQL_INSTANCES_FILE`	Required. Path to the instances YAML file (`host`/`port` per instance).	None
`NR_CLI_MSSQL_WIN_ACCOUNT`	Windows account to grant permissions to, `DOMAIN\username`. Required only when `NR_CLI_MSSQL_AUTH_MODE` is `1` and `NR_CLI_MSSQL_WINAUTH_LOCATION` is `2`; leave blank for gMSA or for the same-host flow.	None
`NR_CLI_MSSQL_WIN_PASSWORD`	Password for that Windows account. Required only when `NR_CLI_MSSQL_AUTH_MODE` is `1` and `NR_CLI_MSSQL_WINAUTH_LOCATION` is `2`; leave blank for gMSA or for the same-host flow.	None
`NR_CLI_MSSQL_GMSA_ACCOUNT`	gMSA account, `DOMAIN\gMSAName$`. gMSA only; leave blank for Windows Authentication.	None

Tip

To monitor more than one SQL Server instance from this collector, add more entries to the instances file. One auth mode and one Windows identity are used for every instance in the file; different identities per instance aren't supported. An invalid host or port, a duplicate host:port, or an instance that fails its version check or permission setup is skipped with a logged reason rather than aborting the whole install. The same-host flow (NR_CLI_MSSQL_WINAUTH_LOCATION 1) only works for instances on this machine. List instances on other hosts using the different-host flow, or gMSA.

This recipe monitors one or more RDS SQL Server endpoints from a single collector, using the same instances file / secrets file pattern as self-hosted.

Create the instances file, using the RDS endpoint as host, with just one entry if you're only monitoring a single RDS instance:

bash

$cat > ~/mssql-instances.yml << 'EOF'
$instances:
$  - host: mydb1.abcdefg12345.us-east-1.rds.amazonaws.com
$    port: 1433
$    login_name: newrelic
$EOF

Create the secrets file with the RDS master username and password for each instance, indexed to match the instances file's order:

bash

$umask 077
$cat > ~/mssql-secrets.env << 'EOF'
$NR_CLI_MSSQL_ADMIN_USER_1=admin
$NR_CLI_MSSQL_ADMIN_PASSWORD_1=YourMasterPassword1
$EOF
$chmod 600 ~/mssql-secrets.env

Linux:

bash

$curl -Ls https://download.newrelic.com/install/newrelic-cli/scripts/install.sh | bash && sudo NEW_RELIC_API_KEY=INSERT_YOUR_API_KEY NEW_RELIC_ACCOUNT_ID=INSERT_YOUR_ACCOUNT_ID NEW_RELIC_REGION=INSERT_YOUR_REGION /usr/local/bin/newrelic install -n nrdot-collector-mssql-rds

Windows (run in an Administrator PowerShell session):

[Net.ServicePointManager]::SecurityProtocol = 'tls12, tls'; $WebClient = New-Object System.Net.WebClient; $WebClient.DownloadFile("https://download.newrelic.com/install/newrelic-cli/scripts/install.ps1", "$env:TEMP\install.ps1"); & PowerShell.exe -ExecutionPolicy Bypass -File $env:TEMP\install.ps1; $env:NEW_RELIC_API_KEY='INSERT_YOUR_API_KEY'; $env:NEW_RELIC_ACCOUNT_ID='INSERT_YOUR_ACCOUNT_ID'; $env:NEW_RELIC_REGION='INSERT_YOUR_REGION'; & 'C:\Program Files\New Relic\New Relic CLI\newrelic.exe' install -n nrdot-collector-mssql-rds

The CLI prompts interactively for the following variables. You can also set them ahead of time as environment variables to run non-interactively.

Variable

Description

Default

NR_CLI_MSSQL_CONFIG_PRESET

NRDOT configuration:

1 for Basic
2 for Advanced

1

NR_CLI_MSSQL_INSTANCES_FILE

Required. Path to the instances YAML file, using RDS endpoints as host.

None

NR_CLI_MSSQL_SECRETS_FILE

Required. Path to the secrets file (KEY=VALUE, one RDS master username/password pair per instance).

None

Tip

To monitor more than one RDS SQL Server endpoint from this collector, add more entries to the instances file and matching numbered credentials to the secrets file. An instance that fails its checks is skipped with a logged reason rather than aborting the whole install.

This method is only supported on a Windows collector host, and requires your RDS instances to already be joined to an AWS Managed Microsoft AD domain. It monitors one or more RDS SQL Server endpoints from a single collector. The collector is one Windows service with one logon account, and connects to every endpoint as that account, so a multi-instance install always uses one auth mode and one Windows identity, granted on every endpoint you list. Unlike the self-hosted method above, there's no "same host" option here: a domain account (or gMSA) is always required.

Create the instances file, using each RDS endpoint as host, with just one entry if you're only monitoring a single RDS instance:
```
instances:
  - host: mydb1.xxxxxxxxxx.us-east-1.rds.amazonaws.com
    port: 1433
  - host: mydb2.xxxxxxxxxx.us-east-1.rds.amazonaws.com
    port: 1433
```
Save this anywhere on the collector host, for example C:\mssql-instances.yml.

Before you run this command, have ready:

The instances file from step 1
Whether you're using a Windows domain account or a gMSA account
The domain account (or gMSA account) to grant permissions to
Whether you want Basic or Advanced metrics

Run this in an Administrator PowerShell session:

[Net.ServicePointManager]::SecurityProtocol = 'tls12, tls'; $WebClient = New-Object System.Net.WebClient; $WebClient.DownloadFile("https://download.newrelic.com/install/newrelic-cli/scripts/install.ps1", "$env:TEMP\install.ps1"); & PowerShell.exe -ExecutionPolicy Bypass -File $env:TEMP\install.ps1; $env:NEW_RELIC_API_KEY='INSERT_YOUR_API_KEY'; $env:NEW_RELIC_ACCOUNT_ID='INSERT_YOUR_ACCOUNT_ID'; $env:NEW_RELIC_REGION='INSERT_YOUR_REGION'; & 'C:\Program Files\New Relic\New Relic CLI\newrelic.exe' install -n nrdot-collector-mssql-rds-winauth

The CLI prompts interactively for the following variables. You can also set them ahead of time as environment variables to run non-interactively.

Variable	Description	Default
`NR_CLI_MSSQL_CONFIG_PRESET`	NRDOT configuration: `1` for Basic `2` for Advanced	`1`
`NR_CLI_MSSQL_AUTH_MODE`	SQL Server authentication: `1` for Windows Domain Authentication `2` for gMSA	`1`
`NR_CLI_MSSQL_INSTANCES_FILE`	Required. Path to the instances YAML file, using RDS endpoints as `host`.	None
`NR_CLI_MSSQL_WIN_ACCOUNT`	Windows domain account to grant permissions to, `DOMAIN\username`. Windows Domain Authentication only; leave blank for gMSA.	None
`NR_CLI_MSSQL_WIN_PASSWORD`	Password for that domain account. Windows Domain Authentication only; leave blank for gMSA.	None
`NR_CLI_MSSQL_GMSA_ACCOUNT`	gMSA account, `DOMAIN\gMSAName$`. gMSA only; leave blank for Windows Domain Authentication.	None

Tip

To monitor more than one RDS SQL Server endpoint from this collector, add more entries to the instances file. One auth mode and one Windows identity are used for every endpoint in the file. An invalid host or port, a duplicate host:port, or an endpoint that fails its version check or permission setup is skipped with a logged reason rather than aborting the whole install.

Find and use your data

Once your data is being collected, you can access comprehensive SQL Server database monitoring through the New Relic UI.

To find your SQL Server database entity in New Relic:

Go to one.newrelic.com > All capabilities > Databases.
From the Entity type dropdown, select MSSQL instance, then click Apply.
Select your SQL Server database from the list of entities.
After setting up SQL Server monitoring with NRDOT, you can:
- Create custom dashboards to visualize your database metrics
- Set up alerts for critical database performance thresholds
- Explore your data using New Relic query capabilities

Set up APM-database correlation

Learn how to correlate your application performance with database operations in New Relic.

Troubleshooting

Learn how to troubleshoot your MSSQL monitoring setup in New Relic.

Metrics reference

Learn about the available metrics collected by the NRDOT Collector.

Install & configure NRDOT for MSSQL monitoring with CLI

Tip

Prerequisites

Install and configure the NRDOT Collector

Self-hosted - SQL Server Authentication

Tip

Self-hosted - Windows Authentication or gMSA

Tip

AWS RDS - SQL Server Authentication

Tip

AWS RDS - Windows Domain Authentication or gMSA

Tip

Find and use your data

Set up APM-database correlation

Troubleshooting

Metrics reference

Install & configure NRDOT for MSSQL monitoring with CLI

Tip

Prerequisites .css-21sua1{background:none;border:none;width:0;padding:0;}

Install and configure the NRDOT Collector

Self-hosted - Windows Authentication or gMSA

AWS RDS - SQL Server Authentication

AWS RDS - Windows Domain Authentication or gMSA

Find and use your data

Related documentation

Set up APM-database correlation

Troubleshooting

Metrics reference

Prerequisites