SQL Extensions Troubleshooting Guide

andrzej-skiba — Thu, 07 Aug 2025 09:15:44 GMT

Summary

This troubleshooting article should help you resolve the most common issues for SQL extensions

Failed to assign monitoring configuration

Problem

As SQL extension fast checks only attempt to verify connectivity to the configured database, this issue will typically be related to either network issues/timeouts or authorization issues with the account that was configured in the monitoring configuration.

Solution

The resolution of this issue will be dependent on the error returned by the fast-check, however, double-checking the hostname, username and password are all valid is a good place to start. You can see below how to resolve different connection issues.

Unable to connect to database

Problem

There’s a whole host of reasons why the extension might be unable to connect to the database. Below is a list of the most common ones and ways to investigate them.

In all cases, review the datasource logs on your ActiveGate server and look for connection exceptions.

Connection information issues

Double check that your host, port, database name and username, and password are correct.

Network issues

Troubleshooting steps:

If you are using a custom extension verify that the JDBC driver and that you’re trying to connect to a supported DB version.
Use tools like Netcat or Telnetto on the ActiveGate server to verify host availability.
- Host unreachable – there's some underlying network issue that needs to be resolved by your server/network administrator
- Host reachable – go to the next step.
Use the Dynatrace connection tool to verify connection to the database.
- Connected successfully – please reach out to support and supply information about all the steps that you have taken to verify the connection.
- Connection problem – go to step 4
Provide an external tool to verify the connection to the database (our recommendations in TOOLS section)
- Connected successfully – please reach out to support and supply information about all the steps that you have taken to verify the connection.
- Connection problem – your ActiveGate server is unable to connect to the database which means that there’s some underlying server or network issue which will need to be resolved by your administrator.

Connection issues can manifest in a multitude of ways, specific to each database vendor. Look for error codes in the connection for exception messages and see driver documentation for the particular error (linked below).

SSL certificate issues

Verify
- Truststore name: sqlds_truststore
- Truststore password: sqlds_truststore
- Truststore default path:
  - Windows: %PROGRAMDATA%\dynatrace\remotepluginmodule\agent\conf\userdata
  - Unix: /var/lib/dynatrace/remotepluginmodule/agent/conf/userdata
- No other truststore is in its directory
- Truststore and its directory permissions (too many permissions my also cause problems!)
- CN in the certificate matches the hostname in the connection string.
If you have more than one certificate in the truststore, create a new one with a single certificate. (Remember to move the other truststore to a different directory)

Metric data is missing

Problem

This is a common issue with SQL-based extensions. There are two main reasons why this will occur:

A feature set responsible for generating the metric is not turned on
The query responsible for the metric did not generate any results

Checking selected feature sets

Look at your extension configuration and review the list of selected feature sets.

Query does not return results

If this happens you will see an “Empty result for query” message in the datasource logs, along with the query itself. Copy the query that returned an empty result from the extension.yaml file and run it manually as the user in the monitoring configuration to determine if the query still returns an empty result.(link to article: Query Behind a Metric)

If the query returns no results it is likely that permissions to the proper table(s) are not granted to the configured extension user or it can occur if a customer has left feature sets enabled for features that they don't have implemented, such as always-on SQL servers in MS SQL, if the SQL server is not configured for high availability then the query for that data will be empty.

List of permissions required by various DB vendors listed in Extension details in the Hub:

Irregular data issues

Keywords: restart, crash, resource consumption

Problem

Sometimes it happens that the extension correctly connects to the database and starts collecting data that can be seen in the UI on dashboards or in Data Explorer, but there are holes or unexpected gaps in the data.

The most common reason for this situation is restarting Extension Framework components, i.e.: the Java-DataSource, Extension Execution Controller or Active Gate. To confirm this, check the logs of these components. You can find the reason for the restart in the logs, most often they are:

update
exceeding the permissible load limits of the machine, see: https://docs.dynatrace.com/docs/extend-dynatrace/extensions20/extensions-concepts#resource-consumption
unexpected crash.

An alternative to viewing logs may be the analysis of Self-Monitoring metrics for:

Datasource - SQL
Extension - Engine
Active Gate: see: https://docs.dynatrace.com/docs/setup-and-configuration/dynatrace-activegate/activegate-sfm-metrics

Troubleshooting

Verify the Java-DataSource, EEC and ActiveGate logs:
- Look for restarts (CTRL + F => “starting“ should find it)
- analyze what happened before restart
- analyze how often a restart occurs
Verify Self-Monitoring metrics

Useful Information

Error codes

Database documentation to read about error codes:

Default platform paths

(used in further descriptions, could be customized!):

Windows

EEC installation directory -> C:/Program Files/dynatrace/remotepluginmodule/ EEC operation directory -> C:/ProgramData/dynatrace/remotepluginmodule

Linux

EEC installation directory -> /opt/dynatrace/remotepluginmodule/
EEC operation directory -> /var/lib/dynatrace/remotepluginmodule/

Datasource

<DATASOURCE_EXECUTABLE_NAME>.log (<EEC operation directory>\log\extensions\datasources\) - log files of the datasource, named after DS executable, e.g dynatracesourcesql.log or dynatracesourcesnmp.log

EEC

extensions.conf (<EEC installation directory>agent\conf) - AG address for communication, tenant number and log level (is replaced by template on each update)
extensionsuser.conf (<EEC installation directory>\agent\conf)
ruxitagent.conf (<EEC installation directory>\agent\conf) - The base URL of the Collector/Server this agent should connect to
ruxitagent_extensionsmodule_<PID>.log (<EEC operation directory>\log\extensions) - logs started DS jobs / tasks - you can check there if EEC had problem starting some job. EEC logs are in the
ruxitagent_extensionsmodule_xxxxx.log files.

Tools

Connection Tool → our internal tool used for connection verification
External JDBC connection tool: DBWeaver
External pinging and connecting tools: Telnet. Netcat

What's next

If none of the solutions above has worked for you and you are still experiencing issues with the SQL extension you are trying to configure there's always a chance that there is a problem with the extension itself or the underlying data source.

In that case feel free to open a support ticket specifying:

A description of the problem, ideally, with screenshots
What extension you are trying to configure and its version
If it's a custom extension please provide the extension YAML or ZIP file
Dynatrace version
ActiveGate version
Extensions Module version
A list of troubleshooting steps that have been performed

Re: SQL Extensions Troubleshooting Guide

AntonPineiro — Mon, 14 Jul 2025 12:54:03 GMT

Thank you!

Re: SQL Extensions Troubleshooting Guide

AjithaN — Tue, 05 Aug 2025 12:26:47 GMT

Hi,

I'm doing similar configuration with microsoft sql server extension to monitor Azure SQLMI agent jobs. Configuration status is seen OK , but the logs show only these 2 warnings repeatedly and the DB metrics is not been collected it seems. I'm not able to see any DB information in the data collected.

"Polling finished with issues for endpoints: sqlmidevuks****-sl-development.720e9a6d****.database.windows.net:1433/ SL**CardPayment"

"While polling for endpoint sqlmidevuks****-sl-development.720e9a6d****.database.windows.net:1433/ SL**CardPayment query have failed: instance, database"

A user definied managed identity is present for the active gate which is given all the db datareader and VIEW SERVER state permission. This managed identity is given as the user in the extension monitoring configuration.

Can anyone suggest if the approach is rite or any alternative to use ? any valid format to give the connection string with managed identity

Re: SQL Extensions Troubleshooting Guide

gregor_liddell — Mon, 22 Sep 2025 09:21:03 GMT

I'm trying to build an extension which gets business metrics from an Informix database over JDBC. Using the informix DB extension as a reference, but I'm getting :-

"ERROR | c.d.s.p.u.ResultSetUtil | Couldn't retrieve value of col:COMPANY_QUEUE. Exception occurred Column label col:COMPANY_QUEUE not found in {col:(count(*))=1}:"

extenstion.yaml

name: custom:za.co.cipc.extension.info-portal

version: 0.0.23

minDynatraceVersion: 1.310.0

author:

name: Gregor Liddell

metrics:

- key: za.co.extension.info-portal.businessmetrics.companyqueue

metadata:

displayName: Company Queue

unit: Count

description: Number of Companies in the registration Queue

sourceEntityType: businessmetrics.companyqueue

jdbc:

driverClassName: "com.informix.jdbc.IfxDriver"

connectionStringPattern: "^jdbc:informix-sqli://.*$"

connectionStringPatternErrorMessage: “This isn't a correct connection string, please start with jdbc"

errorMessage: "An error occurred while trying to connect to the database. Please check the connection details and try again."

validationQuery: SELECT 1 FROM (SELECT 1 AS dual FROM systables WHERE (tabid=1)) AS dual;

versionQuery: SELECT 1 FROM (SELECT 1 AS dual FROM systables WHERE (tabid=1)) AS dual;

groups:

- group: Business Metrics

interval:

minutes: 5

query: >

SELECT count(*)

FROM doc_submitted AS COMPANY_QUEUE;

timeout: "60"

metrics:

- key: za.co.extension.info-portal.businessmetrics.companyqueue

value: col:COMPANY_QUEUE

Re: SQL Extensions Troubleshooting Guide

gregor_liddell — Fri, 17 Oct 2025 09:06:47 GMT

" SELECT count(*) AS COMPANY_QUEUE

FROM doc_submitted; " solved the problem.

Re: SQL Extensions Troubleshooting Guide

tarjei_statkraf — Thu, 12 Mar 2026 13:29:03 GMT

Is there any "script" or example commands for granting access to the user which the extension should use for MSSQL?

Re: SQL Extensions Troubleshooting Guide

AntonPineiro — Fri, 13 Mar 2026 07:46:51 GMT

Hi @tarjei_statkraf,

I can see it for Oracle but not for MSSQL.

Best regards

article SQL Extensions Troubleshooting Guide in Troubleshooting

SQL Extensions Troubleshooting Guide

Summary

Failed to assign monitoring configuration

Problem

Solution

Unable to connect to database

Problem

Connection information issues

Network issues

SSL certificate issues

Metric data is missing

Problem

Checking selected feature sets

Query does not return results

Irregular data issues

Problem

Troubleshooting

Useful Information

Error codes

Default platform paths

Windows

Linux

Datasource

EEC

Tools

What's next

Re: SQL Extensions Troubleshooting Guide

Re: SQL Extensions Troubleshooting Guide

Re: SQL Extensions Troubleshooting Guide

Re: SQL Extensions Troubleshooting Guide

Re: SQL Extensions Troubleshooting Guide

Re: SQL Extensions Troubleshooting Guide