Install & configure NRDOT for MSSQL monitoring with Helm

You can install and configure SQL Server monitoring on Kubernetes using the mssql-otel Helm chart. Optionally, the chart can also run a setup job that creates the monitoring login for you.

Important

This chart only supports SQL Server Authentication (username/password). It does not support Windows Authentication, Windows Domain Authentication, or gMSA. The collector always reaches SQL Server remotely over the network, whether it runs on Linux or Windows, self-hosted or on RDS, so SQL authentication works identically in every case. It also reports SQL Server metrics only (no host/infrastructure metrics), since the collector runs as a Kubernetes Deployment rather than on the SQL Server host itself.

Prerequisites

Valid New Relic license key.
Helm 3.0 or later, and kubectl configured to access your Kubernetes cluster.
Network connectivity from your Kubernetes cluster to the SQL Server host (or RDS endpoint) and port:
- Self-hosted: a routed path to the SQL Server host (VPN, peering, or shared network), and the SQL Server-side firewall must allow the connection's source IP.
- AWS RDS: VPC peering, a transit gateway, or shared-VPC placement with the RDS instance, and the RDS security group must allow the SQL Server port (1433 by default) from the cluster's egress source.
Either a monitoring login you've already created, or SQL Server admin credentials (a sysadmin-role login, such as sa or the RDS master user) so the chart's setup job can create one for you. See Configure monitoring credentials below.

Create the namespace

Create the namespace you'll install into. It must exist before you create any secrets in the next step, since helm install --create-namespace only creates the namespace during the final install step:

bash

$kubectl create namespace newrelic

Tip

Set it as the default namespace for your current kubectl context so you don't need to pass -n on every command below:

bash

$kubectl config set-context --current --namespace=newrelic

Configure monitoring credentials

Decide whether you want the chart's setup job to create the SQL Server monitoring login for you, and if not, how you'll supply its credentials:

With this method there's no setup job, so nothing here creates the monitoring login for you. This chart only supports SQL Server Authentication, so before installing it, create the monitoring login yourself using the SQL Server Authentication Create monitoring user step from Linux self-hosted, Windows self-hosted, Linux RDS, or Windows RDS, depending on your environment.

You'll set the monitoring username and password directly in values.yaml in the next step.

With this method there's also no setup job. Create the monitoring login yourself first, exactly as in the plain-credentials method above. The only difference is where its credentials live: instead of plaintext in values.yaml, store them in a Kubernetes secret:

bash

$kubectl create secret generic mssql-monitor-creds \
>  --from-literal=username=<MONITORING_USERNAME> \
>  --from-literal=password='<MONITORING_PASSWORD>' \
>  -n newrelic

With this method, the chart's setup job creates the monitoring login for you using SQL Server admin credentials. Both the monitoring and admin credentials must be provided as Kubernetes secrets: the setup job never accepts plaintext admin credentials, and enabling it requires secret-based monitoring credentials too.

Create a secret with the monitoring username and password. This is the identity the setup job creates and the collector connects with:

bash

$kubectl create secret generic mssql-monitor-creds \
>  --from-literal=username=<MONITORING_USERNAME> \
>  --from-literal=password='<MONITORING_PASSWORD>' \
>  -n newrelic

The setup job only accepts admin credentials via a Kubernetes secret (no plaintext username/password in values.yaml). Since this credential can create logins and grant broad VIEW access, create it as its own secret. Use a login in the sysadmin role (or equivalent) for self-hosted SQL Server, or the RDS master user for SQL Server on AWS RDS:
bash
```
$kubectl create secret generic mssql-admin-creds \
>  --from-literal=username=<ADMIN_USERNAME> \
>  --from-literal=password='<ADMIN_PASSWORD>' \
>  -n newrelic
```

Configure the Helm values

Set mssql.topology to match your environment:

Value	Description
`self-hosted`	Self-hosted SQL Server, reached over the network (Linux or Windows host).
`rds`	SQL Server on AWS RDS.

Use the values.yaml that matches the credential method you chose in the previous step:

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: https://otlp.nr-data.net:4318

mssql:
  topology: <self-hosted|rds>
  server: <YOUR_DB_HOST>
  port: <YOUR_DB_PORT>
  username: <YOUR_MONITORING_USERNAME>
  password: <YOUR_MONITORING_PASSWORD>

# No setup job runs, so create the monitoring login yourself
# before installing the chart.
setupJob:
  enabled: false

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: https://otlp.nr-data.net:4318

mssql:
  topology: <self-hosted|rds>
  server: <YOUR_DB_HOST>
  port: <YOUR_DB_PORT>
  existingSecret: mssql-monitor-creds

# No setup job runs, so the monitoring login referenced by
# this secret must already exist - create it yourself
# before installing the chart.
setupJob:
  enabled: false

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: https://otlp.nr-data.net:4318

mssql:
  topology: <self-hosted|rds>
  server: <YOUR_DB_HOST>
  port: <YOUR_DB_PORT>
  existingSecret: mssql-monitor-creds

setupJob:
  enabled: true
  image:
    # -- sqlcmd image. No default: see the chart's README for why
    # (mcr.microsoft.com/mssql-tools:latest is freely pullable but
    # stale and unmaintained).
    repository: ""
    tag: ""
    pullPolicy: IfNotPresent
  sqlAdmin:
    existingSecret: mssql-admin-creds

Parameter	Description
`licenseKey`	Your New Relic license key.
`otlpEndpoint`	Your region's OTLP/HTTP endpoint, as a full URL with scheme: `https://otlp.nr-data.net:4318` (US) or `https://otlp.eu01.nr-data.net:4318` (EU). For more information, refer to New Relic OTLP endpoints documentation.
`mssql.server` / `mssql.port`	Your SQL Server host (or RDS endpoint) and port, reachable from the cluster.
`mssql.tls.enabled` / `mssql.tls.trustServerCertificate`	Optional. Set `enabled: true` to encrypt the connection to SQL Server, and `trustServerCertificate: true` to skip certificate validation (useful for self-signed certs in test environments).
`setupJob.image.repository` / `setupJob.image.tag`	A `sqlcmd`-capable image used by the setup job. There's no default: Microsoft's freely pullable `mcr.microsoft.com/mssql-tools:latest` is dated 2017 and unmaintained, so confirm you're comfortable with its age (including unpatched CVEs) before using it, or build a current image yourself from Microsoft's `mssql-tools18` apt packages. Only required for secret-based credentials, where the setup job is enabled.

Tip

See the chart's values.yaml for all available configuration options, including mssql.collectionInterval, mssql.maxConcurrentQueries, and the additionalReceiverConfig escape hatch.

(Optional) Monitor multiple instances from one release

Instead of mssql.*, set mssqlMulti.enabled: true to monitor several SQL Server instances (self-hosted or RDS) from a single collector pod in one release. The two modes are mutually exclusive: don't set mssql.server and mssqlMulti.enabled: true in the same release.

Multi-instance mode has no plain-username/password path: every instance needs its own Kubernetes secret with monitoring credentials. Decide whether you also want the setup job to create each monitoring login for you:

Create each instance's monitoring-login secret yourself before installing (repeat per instance, matching the name you give it in values.yaml):

bash

$kubectl create secret generic db1-monitor-creds \
>  --from-literal=username=<MONITORING_USERNAME> \
>  --from-literal=password='<MONITORING_PASSWORD>' \
>  -n newrelic
$# Repeat for every instance (db2-monitor-creds, ...)

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: https://otlp.nr-data.net:4318

# EDIT the two example entries below (or add more) to match
# your real instances - each `name` must be unique within
# this release and match the Secret you created for it.
mssqlMulti:
  enabled: true
  topology: <self-hosted|rds>
  databases:
    - name: db1
      server: <YOUR_DB_1_HOST>
      existingSecret: db1-monitor-creds
    - name: db2
      server: <YOUR_DB_2_HOST>
      existingSecret: db2-monitor-creds

# No admin credential is configured here since the setup
# job is disabled - create each instance's monitoring login
# yourself first.
setupJob:
  enabled: false

Each instance needs both its own monitoring-login secret and its own admin-credentials secret (repeat per instance):

bash

$kubectl create secret generic db1-monitor-creds \
>  --from-literal=username=<MONITORING_USERNAME> \
>  --from-literal=password='<MONITORING_PASSWORD>' \
>  -n newrelic
>kubectl create secret generic db1-admin-creds \
>  --from-literal=username=<ADMIN_USERNAME> \
>  --from-literal=password='<ADMIN_PASSWORD>' \
>  -n newrelic
$# Repeat for every instance (db2-monitor-creds, db2-admin-creds, ...)

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: https://otlp.nr-data.net:4318

# EDIT the two example entries below (or add more) to match
# your real instances - each `name` must be unique within
# this release and match the Secrets you created for it.
mssqlMulti:
  enabled: true
  topology: <self-hosted|rds>
  databases:
    - name: db1
      server: <YOUR_DB_1_HOST>
      existingSecret: db1-monitor-creds
      sqlAdmin:
        existingSecret: db1-admin-creds
    - name: db2
      server: <YOUR_DB_2_HOST>
      existingSecret: db2-monitor-creds
      sqlAdmin:
        existingSecret: db2-admin-creds

setupJob:
  enabled: true
  image:
    repository: ""
    tag: ""

Parameter	Description
`mssqlMulti.enabled`	Set to `true` to monitor multiple instances from one release instead of `mssql.*`. Defaults to `false`.
`mssqlMulti.topology`	`self-hosted` or `rds`, same meaning as `mssql.topology`, shared by every instance in this release.
`mssqlMulti.databases`	List of instances to monitor. Each entry requires a unique `name`, `server` (`port` defaults to `1433`), and `existingSecret`; add `sqlAdmin.existingSecret` per entry only when `setupJob.enabled` is `true`.

Tip

Scrape settings (collection interval, TLS, metrics) apply identically to every instance in mssqlMulti.databases. There's no per-instance override. Use additionalReceiverConfig for anything that needs to differ. The setup job runs once per instance (<release>-setup-<name>) rather than once per release.

Install the Helm chart

Add the New Relic Helm repository:

bash

$helm repo add newrelic https://helm-charts.newrelic.com
$helm repo update

Install the chart using your values.yaml file:

bash

$helm upgrade --install mssql-otel newrelic/mssql-otel \
>  -n newrelic \
>  --create-namespace \
>  -f values.yaml

Verify the installation

Check that the setup job completed (if enabled) and the collector pod is running:
bash
```
$kubectl get jobs,pods -n newrelic --watch
```

Run this query in the query builder to confirm data is arriving:

SELECT count(*) FROM Metric
WHERE metricName LIKE 'sqlserver.%'
AND instrumentation.provider = 'opentelemetry'
SINCE 10 minutes ago

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

Metrics reference

Learn about the available metrics collected by the NRDOT Collector.

Troubleshooting

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

Set up APM-database correlation

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

Install & configure NRDOT for MSSQL monitoring with Helm

Important

Prerequisites

Create the namespace

Tip

Configure monitoring credentials

No setup job: plain username and password

No setup job: secret-based credentials

Automated setup job

Configure the Helm values

No setup job: plain username and password

No setup job: secret-based credentials

Automated setup job

Tip

(Optional) Monitor multiple instances from one release

No setup job

Automated setup job

Tip

Install the Helm chart

Verify the installation

Find and use your data

Metrics reference

Troubleshooting

Set up APM-database correlation

Install & configure NRDOT for MSSQL monitoring with Helm

Important

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

Create the namespace

Tip

Configure monitoring credentials

No setup job: secret-based credentials

Automated setup job

Configure the Helm values

No setup job: plain username and password

No setup job: secret-based credentials

Automated setup job

Tip

(Optional) Monitor multiple instances from one release

No setup job

Automated setup job

Tip

Install the Helm chart

Verify the installation

Find and use your data

Related documentation

Metrics reference

Troubleshooting

Set up APM-database correlation

Prerequisites