Microsoft SQL Server monitoring configuration

• Reference
• 3-min read
• Updated on Oct 08, 2026

After you define the scope of your configuration, you need to identify the following:

Example payload

Example payload to activate a Microsoft SQL extension:

{
  "value": {
    "enabled": true,
    "description": "My Microsoft SQL extension",
    "version": "1.0.1",
    "sqlServerRemote": {
      "endpoints": [
        {
          "host": "localhost",
          "port": 1521,
          "instanceName": "some-instanceName",
          "databaseName": "some-databaseName",
          "authentication": {
            "scheme": "basic",
            "username": "username",
            "password": "password"
          },
          "ssl": false
        }
      ]
    }
  },
  "scope": "ag_group-default"
}

Parameters

Enabled

If set to true, the configuration is active and Dynatrace starts monitoring immediately.

Description

A human-readable description of the specifics of this monitoring configuration.

Version

The version of this monitoring configuration. A single extension can run multiple monitoring configurations.

Endpoints

You can define up to 20,000 endpoints in a single monitoring configuration in the sqlServerRemote section.

"sqlServerRemote": {
        "endpoints": [
            {
                "host": "sqlserver.org",
                "port": 1433,
                "instanceName": "instance",
                "databaseName": "database",
                "authentication": {
                    "scheme": "basic",
                    "username": "admin",
                    "password": "password"
                }
            }
        ]
    }

To define a Microsoft SQL Server, add the following details in the endpoints section:

Authentication

Dynatrace obfuscates authentication details passed to the API when you activate a monitoring configuration, and you can't retrieve them.

Basic

Basic authentication requires only a username and password.

"authentication": {
   "scheme": "basic",
   "username": "username",
   "password": "password",
}

Kerberos

Kerberos authentication enables connectivity to self-hosted databases. It requires an Active Directory domain setup and allows you to connect to a database by providing a domain username, password, Key Distribution Center (KDC), and realm.

"authentication": {
   "scheme": "kerberos",
   "username": "username",
   "password": "password",
   "realm": "realm",
   "kdc": "kdc"
}

One realm and KDC per JVM process

The realm and kdc fields map to the JVM-wide system properties java.security.krb5.realm and java.security.krb5.kdc. All SQL Server Kerberos endpoints that run inside the same ActiveGate task or the same Kubernetes executor pod share these values. Only one realm and one KDC can be active per JVM process at a time.

If two or more endpoints in the same process require different realm or kdc values, only the first endpoint's configuration takes effect. All subsequent endpoints that require different realm or kdc values fail to start. No configuration validation error is raised.

The datasource emits an SFM ERROR event when it detects that a property already set by a previous endpoint differs from the value required by the current endpoint. The event names the conflicting property and both values, so operators can identify the affected endpoints.

To work around this constraint:

NTLM

NTLM authentication enables connectivity to self-hosted databases. It requires an Active Directory domain setup and allows you to connect to a database by providing a domain username, a domain password, and, optionally, the domain.

"authentication": {
   "scheme": "ntlm",
   "username": "username",
   "password": "password",
   "domain": "some-domain-name"
}

Azure Active Directory managed identity

ActiveGate version 1.351+

Allows connection to Azure SQL Database, Azure SQL Managed Instance, or SQL Server on an Azure virtual machine using an Azure Active Directory (Microsoft Entra ID) managed identity. The target database must be configured for Microsoft Entra authentication. Requires a managed identity available to the ActiveGate host and mapped to a database user.

ActiveGate uses the assigned managed identity to authenticate, so there's no need to store a database password. The azureManagedIdentityClientId field is optional—provide the client ID of the managed identity only when the ActiveGate host has multiple user-assigned managed identities attached, so that Dynatrace can select the correct one.

"authentication": {
   "scheme": "ad_managed_identity",
   "azureManagedIdentityClientId": "<managed-identity-client-id>"
}

Credential vault

The credential vault authentication type provides a more secure approach to using extensions by securely storing and managing user credentials. To use this, you must be the owner of the credentials and have a credential vault that meets the following criteria:

"authentication": {
   "scheme": "basic",
   "useCredentialVault": true,
   "credentialVaultId": "some-credential-vault-id"
}

SSL

ActiveGate version 1.251+

Enable SSL to make the data source verify the server certificate and use SSL encryption instead of native encryption.

"ssl": true

Enable SSL without a local truststore

When SSL is enabled and the server's certificate chain is publicly verifiable (for example, issued by Azure or other well-known CAs), there's no need to manually create a truststore. The system automatically trusts the server's certificate based on the trusted CAs in the environment.

However, if you need to use a local truststore for certificates not globally recognized or for additional security measures:

Validate SSL certificates

ActiveGate version 1.269+

The certificate is also validated against the hostname. This means the domain in the certificate must match the endpoint's domain as defined in the monitoring configuration.

Enable this option when connecting to databases using custom certificates.

"validateCertificates": true

Scope

Each ActiveGate host running your extension needs the root certificate to verify its authenticity. For details, see Sign extension.

The scope is an ActiveGate group that executes the extension. Only one ActiveGate from the group runs this monitoring configuration. If you plan to use a single ActiveGate, assign it to a dedicated group. You can assign an ActiveGate to a group during or after installation. For details, see ActiveGate group.

Use the following format when defining the ActiveGate group:

"scope": "ag_group-<ActiveGate-group-name>",

Replace <ActiveGate-group-name> with the actual name.