SQL Query Receiver with NRDOT

The sqlqueryreceiver is an OpenTelemetry Collector receiver that lets you run any custom SQL query against your database and ingest the results as metrics into New Relic.

Use this when you want to monitor data not covered by the built-in nroracledbreceiver / nrsqlserverreceiver / nrmysqlreceiver / nrpostgresqlreceiver metrics. Custom metrics collected via sqlqueryreceiver appear under the same Oracle, SQL Server, MySQL, or PostgreSQL entity in New Relic as the built-in receiver data, provided the entity-linking attributes are configured correctly.

Prerequisites

The database user configured in the datasource must have SELECT privilege on any view or table you intend to query.
The collector binary must include the sqlqueryreceiver component.

Configuration

Add the sqlqueryreceiver block inside the receivers: section of your existing oracle-config.yaml, alongside the existing nroracledb block:

receivers:
  nroracledb:

  ...

  sqlquery/oracle:
    driver: oracle

    # Approach 1: Use the `host`, `port`, `database`, `username`, and `password` fields to connect to your database. The receiver will construct the datasource URL for you.
    # host: <YOUR_DB_HOST>
    # port: <YOUR_DB_PORT>
    # database: <YOUR_DATABASE_NAME>
    # username: <YOUR_DB_USERNAME>
    # password: <YOUR_DB_PASSWORD>


    # Approach 2: Use the `datasource` field to provide a full connection string. 
    datasource: "oracle://<YOUR_DB_USERNAME>:<YOUR_DB_PASSWORD>@<YOUR_DB_HOST>:<YOUR_DB_PORT>/<YOUR_SERVICE_NAME>"

    collection_interval: 60s
    queries:
      - sql: "<YOUR_CUSTOM_SQL>"
        metrics:
          - metric_name: oracledb.<YOUR_METRIC_NAME>
            value_column: <RESULT_COLUMN>
            attribute_columns: [<DIMENSION_COLUMN_1>, <DIMENSION_COLUMN_2>]
            value_type: double

Set the following parameters for each metric:

Parameter	Description
`<YOUR_DB_HOST>`	Your hostname or IP address. For example, `10.12.0.4`
`<YOUR_DB_PORT>`	Your port number. The default value is set to `1433`
`<YOUR_DB_USERNAME>`	Your Oracle database username. For example `newrelic`
`<YOUR_DB_PASSWORD>`	Your Oracle database password.
`<YOUR_SERVICE_NAME>`	Your Oracle service name. For example `master`
`collection_interval`	How often to run the queries and collect metrics. For example, `30s`, `60s`
`<YOUR_CUSTOM_SQL>`	The SQL query to run. Important Ensure that your custom queries don't collect or expose PII or sensitive data.
`<YOUR_METRIC_NAME>`	Your metric name displayed in New Relic. Use `oracledb.` prefix for consistency. For example `oracledb.custom.wait_time_ms`
`<VALUE_COLUMN>`	The column from the query result whose value becomes the metric value. For example `wait_time_ms`
`<VALUE_TYPE>`	Data type of the value column. Options: `int`, `double`. Defaults to `int` if omitted. For example `int`
`<DATA_TYPE>`	OTLP metric type. Use `gauge` for current/snapshot values. Use `sum` for cumulative counters. Defaults to `gauge` if omitted. For example `gauge`
`<UNIT>`	Unit of measurement for the metric value. Used as metadata in New Relic. For example `ms`, `By`, `s`, `%`, `1`
`<ATTRIBUTE_COLUMNS>`	Columns from the query result that become metric labels/dimensions. Used to filter and facet in NRQL. For example `["wait_type", "database_name"]`

Important

For Oracle CDB users (C## prefix), encode # as %23 in the datasource URL. For example: c##newrelic must be c%23%23newrelic

Naming convention

Metric names must start with oracledb. to be associated with the correct entity in New Relic. Metrics with a different prefix will be ingested but will not appear under the database entity.

Entity synthesis

Add resource/add_event_name and resource/add_host processors to set server.address and server.port to the same values used by the database receiver. Without this, custom metrics will not be linked to the database entity.

Add the processors in the processors: section:

processors:
  batch:
  resource/add_event_name:
    attributes:
      - key: server.address
        value: "<YOUR_DB_HOST>"
        action: upsert
  resource/add_host:
    attributes:
      - key: server.port
        value: "<YOUR_DB_PORT>"
        action: upsert

Pipeline configuration

Add a metrics/custom pipeline in the service.pipelines: section of the config, alongside the existing pipelines:

service:
  pipelines:
    metrics/oracledb:
      receivers: [nroracledb]
      processors: [batch]
      exporters: [otlp/newrelic]
    logs/oracledb:
      receivers: [nroracledb]
      processors: [batch]
      exporters: [otlp/newrelic]

    metrics/custom:
      receivers: [sqlquery/oracle]
      processors: [resource/add_event_name, resource/add_host, batch]
      exporters: [otlp/newrelic]

Important

Add both resource/add_event_name and resource/add_host before batch in the processor list.

NRQL to validate data

After restarting the collector, run the following to confirm custom metrics are arriving:

SELECT uniques(metricName) FROM Metric
WHERE otel.library.name LIKE '%sqlqueryreceiver%'
AND metricName LIKE 'oracledb.%'
SINCE 1 hour ago

Troubleshooting

Issue	Cause	Fix
`ORA-00942: table or view does not exist`	Database user missing SELECT privilege	Grant `SELECT ON <VIEW_NAME>` to the user
`missing port in address`	`#` in username/password not URL-encoded	Replace `#` with `%23` in the datasource URL
No data in New Relic	`server.address`/`server.port` not set or mismatched	Add `resource/add_event_name` and `resource/add_host` processors with the correct values
Metrics not under database entity	Metric name missing required prefix	Ensure metric names start with `oracledb.`

If none of the above resolves the issue, check the collector's own logs for errors:

bash

$sudo journalctl -u nrdot-collector -f

Add the sqlqueryreceiver block inside the receivers: section of your SQL Server collector configuration, alongside the existing nrsqlserver block:

receivers:
  nrsqlserver:
    ...

  sqlquery:
    driver: sqlserver

    # Approach 1: Use the `host`, `port`, `database`, `username`, and `password` fields to connect to your database. The receiver will construct the datasource URL for you.
    # host: <YOUR_DB_HOST>
    # port: <YOUR_DB_PORT>
    # database: <YOUR_DATABASE_NAME>
    # username: <YOUR_DB_USERNAME>
    # password: <YOUR_DB_PASSWORD>

    # Approach 2: Use the `datasource` field to provide a full connection string.
    datasource: "sqlserver://<YOUR_DB_USERNAME>:<YOUR_DB_PASSWORD>@<YOUR_DB_HOST>:<YOUR_DB_PORT>?database=<YOUR_DATABASE_NAME>"
    collection_interval: 30s
    queries:
      - sql: "<YOUR_CUSTOM_SQL>"
        metrics:
          - metric_name: sqlserver.<YOUR_METRIC_NAME>
            value_column: <VALUE_COLUMN>
            value_type: <VALUE_TYPE>
            data_type: <DATA_TYPE>
            unit: <UNIT>
            attribute_columns: ["<ATTRIBUTE_COLUMNS>"]

      - sql: "<YOUR_CUSTOM_SQL>"
        metrics:
          - metric_name: sqlserver.<YOUR_METRIC_NAME>
            value_column: <VALUE_COLUMN>
            value_type: <VALUE_TYPE>
            data_type: <DATA_TYPE>
            unit: <UNIT>
            attribute_columns: ["<ATTRIBUTE_COLUMNS>"]

Set the following parameters for each metric:

Parameter	Description
`<YOUR_DB_HOST>`	Your server hostname or IP address. For example, `10.12.0.4`
`<YOUR_DB_PORT>`	Your server port number. The default value is set to `1433`
`<YOUR_DB_USERNAME>`	Your SQL Server username. Omit for Windows Domain/GMSA authentication. For example `newrelic`
`<YOUR_DB_PASSWORD>`	Your SQL Server password. Omit for Windows Domain/GMSA authentication. For example `secret`
`<YOUR_DATABASE_NAME>`	Your database name to use as the initial connection context. For example `master`
`collection_interval`	How often to run the queries and collect metrics. For example, `30s`, `60s`
`<YOUR_CUSTOM_SQL>`	The SQL query to run. For example, `SELECT SUM(pages_kb) / 1024 AS size_mb, type FROM sys.dm_os_memory_clerks GROUP BY type` Important Ensure that your custom queries don't collect or expose PII or sensitive data.
`<YOUR_METRIC_NAME>`	Your metric name displayed in New Relic. Use `sqlserver.` prefix for consistency. For example `sqlserver.custom.wait_time_ms`
`<VALUE_COLUMN>`	The column from the query result whose value becomes the metric value. For example `wait_time_ms`
`<VALUE_TYPE>`	Data type of the value column. Options: `int`, `double`. Defaults to `int` if omitted. For example `int`
`<DATA_TYPE>`	OTLP metric type. Use `gauge` for current/snapshot values. Use `sum` for cumulative counters. Defaults to `gauge` if omitted. For example `gauge`
`<UNIT>`	Unit of measurement for the metric value. Used as metadata in New Relic. For example `ms`, `By`, `s`, `%`, `1`
`<ATTRIBUTE_COLUMNS>`	Columns from the query result that become metric labels/dimensions. Used to filter and facet in NRQL. For example `["wait_type", "database_name"]`

Naming convention

Metric names must start with sqlserver. to be associated with the correct entity in New Relic. Metrics with a different prefix will be ingested but will not appear under the database entity.

Entity synthesis

Add a resource/add_host processor to set server.address and server.port to the same values used by the database receiver. Without this, custom metrics will not be linked to the database entity.

Add the processor in the processors: section:

processors:
  resource/add_host:
    attributes:
      - key: server.address
        value: "<YOUR_DB_HOST>"
        action: upsert
      - key: server.port
        value: "<YOUR_DB_PORT>"
        action: upsert

Pipeline configuration

Add a metrics/custom pipeline in the service.pipelines: section of the config, alongside the existing pipelines:

service:
  pipelines:
    metrics/custom:
      receivers: [sqlquery]
      processors: [resource/add_host, batch]
      exporters: [otlp]

Important

Add resource/add_host before batch in the processor list.

NRQL to validate data

After restarting the collector, run the following to confirm custom metrics are arriving:

SELECT uniques(metricName) FROM Metric
WHERE otel.library.name LIKE '%sqlqueryreceiver%'
AND metricName LIKE 'sqlserver.%'
SINCE 1 hour ago

Add the sqlqueryreceiver block inside the receivers: section of your existing mysql-config.yaml, alongside the existing nrmysql block:

receivers:
  nrmysql:
    ...

  sql_query/mysql:
    driver: mysql

    # Approach 1: Use the `host`, `port`, `database`, `username`, and `password` fields to connect to your database. The receiver will construct the datasource string for you.
    host: <YOUR_DB_HOST>
    port: <YOUR_DB_PORT>
    database: <YOUR_DATABASE_NAME>
    username: <YOUR_DB_USERNAME>
    password: <YOUR_DB_PASSWORD>

    # Approach 2: Use the `datasource` field to provide a full connection string.
    # datasource: "<YOUR_DB_USERNAME>:<YOUR_DB_PASSWORD>@tcp(<YOUR_DB_HOST>:<YOUR_DB_PORT>)/<YOUR_DATABASE_NAME>"

    collection_interval: 60s
    queries:
      - sql: "<YOUR_CUSTOM_SQL>"
        metrics:
          - metric_name: mysql.<YOUR_METRIC_NAME>
            value_column: <VALUE_COLUMN>
            value_type: <VALUE_TYPE>
            data_type: <DATA_TYPE>
            unit: <UNIT>
            attribute_columns: ["<ATTRIBUTE_COLUMNS>"]

Set the following parameters for each metric:

Parameter	Description
`<YOUR_DB_HOST>`	Your MySQL host name or IP address. For example, `10.12.0.4`
`<YOUR_DB_PORT>`	Your MySQL port number. The default value is `3306`
`<YOUR_DATABASE_NAME>`	The database to connect to. For example `information_schema`
`<YOUR_DB_USERNAME>`	Your MySQL monitoring username. For example `newrelic`
`<YOUR_DB_PASSWORD>`	Your MySQL monitoring password.
`collection_interval`	How often to run the queries and collect metrics. For example, `30s`, `60s`
`<YOUR_CUSTOM_SQL>`	The SQL query to run. Important Ensure that your custom queries don't collect or expose PII or sensitive data.
`<YOUR_METRIC_NAME>`	Your metric name displayed in New Relic. Must be prefixed with `mysql.` for consistency. For example `mysql.custom.wait_time_ms`
`<VALUE_COLUMN>`	The column from the query result whose value becomes the metric value. For example `wait_time_ms`
`<VALUE_TYPE>`	Data type of the value column. Options: `int`, `double`. Defaults to `int` if omitted. For example `int`
`<DATA_TYPE>`	OTLP metric type. Use `gauge` for current/snapshot values. Use `sum` for cumulative counters. Defaults to `gauge` if omitted. For example `gauge`
`<UNIT>`	Unit of measurement for the metric value. Used as metadata in New Relic. For example `ms`, `By`, `s`, `%`, `1`
`<ATTRIBUTE_COLUMNS>`	Columns from the query result that become metric labels/dimensions. Used to filter and facet in NRQL. For example `["wait_type", "database_name"]`

Important

MySQL's datasource connection string uses the format <user>:<password>@tcp(<host>:<port>)/<dbname>. Don't reuse another database's connection-string format here.

Naming convention

Metric names must start with mysql. to be associated with the correct entity in New Relic. Metrics with a different prefix will be ingested but will not appear under the database entity.

Pipeline configuration

Add a metrics/custom pipeline in the service.pipelines: section of the config, alongside the existing pipeline:

service:
  pipelines:
    metrics/mysql:
      receivers: [nrmysql]
      processors: [batch]
      exporters: [otlp/newrelic]
    metrics/custom:
      receivers: [sql_query/mysql]
      processors: [batch]
      exporters: [otlp/newrelic]

NRQL to validate data

After restarting the collector, run the following to confirm custom metrics are arriving:

SELECT uniques(metricName) FROM Metric
WHERE otel.library.name LIKE '%sqlqueryreceiver%'
AND metricName LIKE 'mysql.%'
SINCE 1 hour ago

Troubleshooting

Issue	Cause	Fix
Error 1045: Access denied for user	Wrong username/password	Double-check credentials; use the individual-fields approach rather than hand-building the datasource string
Error 1146: Table doesn't exist / SQL syntax error	Custom SQL references a table/column that doesn't exist on this MySQL/MariaDB version, or uses unsupported syntax	Test the query directly against the instance first with the same user before adding it to the receiver config
Metrics not under database entity	Metric name missing `mysql.` prefix	Ensure metric names start with `mysql.`
TLS/SSL negotiation error connecting to a TLS-enforcing server	Driver defaults to no TLS unless configured	Set the `tls` parameter under `additional_params` to match the server's TLS requirements

If none of the above resolves the issue, check the collector's own logs for errors:

bash

$sudo journalctl -u nrdot-collector -f

Add the sqlqueryreceiver block inside the receivers: section of your existing postgres-config.yaml, alongside the existing nrpostgresql block:

receivers:
  nrpostgresql:
    ...

  sql_query/postgres:
    driver: postgres

    # Approach 1: Use the `host`, `port`, `database`, `username`, and `password` fields to connect to your database. The receiver will construct the datasource URL for you.
    host: <YOUR_DB_HOST>
    port: <YOUR_DB_PORT>
    database: <YOUR_DATABASE_NAME>
    username: <YOUR_DB_USERNAME>
    password: <YOUR_DB_PASSWORD>
    additional_params:
      sslmode: disable

    # Approach 2: Use the `datasource` field to provide a full connection string.
    # datasource: "host=<YOUR_DB_HOST> port=<YOUR_DB_PORT> user=<YOUR_DB_USERNAME> password=<YOUR_DB_PASSWORD> dbname=<YOUR_DATABASE_NAME> sslmode=disable"

    collection_interval: 60s
    queries:
      - sql: "<YOUR_CUSTOM_SQL>"
        metrics:
          - metric_name: postgresql.<YOUR_METRIC_NAME>
            value_column: <VALUE_COLUMN>
            value_type: <VALUE_TYPE>
            data_type: <DATA_TYPE>
            unit: <UNIT>
            attribute_columns: ["<ATTRIBUTE_COLUMNS>"]

Set the following parameters for each metric:

Parameter	Description
`<YOUR_DB_HOST>`	Your hostname or IP address. For example, `10.12.0.4`
`<YOUR_DB_PORT>`	Your port number. The default value is `5432`
`<YOUR_DATABASE_NAME>`	Your database name to use as the initial connection context. For example `testdb`
`<YOUR_DB_USERNAME>`	Your PostgreSQL database username. For example `newrelic`
`<YOUR_DB_PASSWORD>`	Your PostgreSQL database password.
`collection_interval`	How often to run the queries and collect metrics. For example, `30s`, `60s`
`<YOUR_CUSTOM_SQL>`	The SQL query to run. Important Ensure that your custom queries don't collect or expose PII or sensitive data.
`<YOUR_METRIC_NAME>`	Your metric name displayed in New Relic. Must be prefixed with `postgresql.` for consistency. For example `postgresql.custom.connections_by_state`
`<VALUE_COLUMN>`	The column from the query result whose value becomes the metric value. For example `conn_count`
`<VALUE_TYPE>`	Data type of the value column. Options: `int`, `double`. Defaults to `int` if omitted. For example `int`
`<DATA_TYPE>`	OTLP metric type. Use `gauge` for current/snapshot values. Use `sum` for cumulative counters. Defaults to `gauge` if omitted. For example `gauge`
`<UNIT>`	Unit of measurement for the metric value. Used as metadata in New Relic. For example `ms`, `By`, `s`, `%`, `1`
`<ATTRIBUTE_COLUMNS>`	Columns from the query result that become metric labels/dimensions. Used to filter and facet in NRQL. For example `["state"]`

Important

If your PostgreSQL server requires TLS, set sslmode accordingly under additional_params (Approach 1) or in the datasource string (Approach 2) — for example sslmode: require. When omitted, the underlying driver defaults to negotiating SSL for non-local connections, which fails against a server that isn't configured for it.

Naming convention

Metric names must start with postgresql. to be associated with the correct entity in New Relic. Metrics with a different prefix will be ingested but will not appear under the database entity.

Entity synthesis

nrpostgresql synthesizes its database entity from server.address and server.port. Add a resource/add_host processor to stamp the same server.address/server.port values used by the database receiver. Without this, custom metrics will not be linked to the database entity.

Add the processor in the processors: section:

processors:
  batch:
  resource/add_host:
    attributes:
      - key: server.address
        value: "<YOUR_DB_HOST>"
        action: upsert
      - key: server.port
        value: "<YOUR_DB_PORT>"
        action: upsert

Important

If your nrpostgresql pipeline already has a resource/* processor setting server.address/server.port (for example resource/postgresql), reuse that same processor in the metrics/custom pipeline below instead of duplicating it — both receivers must stamp identical values to attach to the same entity.

Pipeline configuration

Add a metrics/custom pipeline in the service.pipelines: section of the config, alongside the existing pipelines:

service:
  pipelines:
    metrics/postgresql:
      receivers: [nrpostgresql]
      processors: [resource/add_host, batch]
      exporters: [otlp/newrelic]
    logs/postgresql:
      receivers: [nrpostgresql]
      processors: [resource/add_host, batch]
      exporters: [otlp/newrelic]
    metrics/custom:
      receivers: [sql_query/postgres]
      processors: [resource/add_host, batch]
      exporters: [otlp/newrelic]

Important

Add resource/add_host before batch in the processor list.

NRQL to validate data

After restarting the collector, run the following to confirm custom metrics are arriving:

SELECT uniques(metricName) FROM Metric
WHERE otel.library.name LIKE '%sqlqueryreceiver%'
AND metricName LIKE 'postgresql.%'
SINCE 1 hour ago

Troubleshooting

Issue	Cause	Fix
`pq: SSL is not enabled on the server`	`sslmode` not set, driver defaulted to negotiating SSL	Set `sslmode: disable` (or the mode your server supports) under `additional_params`, or in the `datasource` string
`pq: password authentication failed for user`	Wrong username/password, or special characters not escaped in a raw `datasource` string	Use Approach 1 (individual fields) — the receiver URL-escapes `username`/`password` automatically — or manually escape special characters in `datasource`
Metrics not under database entity	Metric name missing required `postgresql.` prefix, or `server.address`/`server.port` not set or mismatched	Ensure metric names start with `postgresql.`, and add `resource/add_host` (or reuse the existing `nrpostgresql` resource processor) with the correct host/port values

If none of the above resolves the issue, check the collector's own logs for errors:

bash

$sudo journalctl -u nrdot-collector -f

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

Configuration

Important

Important

Naming convention

Entity synthesis

Pipeline configuration

Important

NRQL to validate data

Troubleshooting

Important

Naming convention

Entity synthesis

Pipeline configuration

Important

NRQL to validate data

Important

Important

Naming convention

Pipeline configuration

NRQL to validate data

Troubleshooting

Important

Important

Naming convention

Entity synthesis

Important

Pipeline configuration

Important

NRQL to validate data

Troubleshooting

Prerequisites