• /
  • EnglishEspañolFrançais日本語한국어Português
  • EntrarComeçar agora

Esta tradução de máquina é fornecida para sua comodidade.

Caso haja alguma divergência entre a versão em inglês e a traduzida, a versão em inglês prevalece. Acesse esta página para mais informações.

Criar um problema

Receptor de consulta SQL com NRDOT

|View as Markdown (English)

O sqlqueryreceiver é um receptor do OpenTelemetry Collector que permite executar qualquer consulta SQL personalizada em seu banco de dados e ingerir os resultados como métricas no New Relic.

Use isso quando desejar monitorar dados não cobertos pelas métricas integradas de nroracledbreceiver / nrsqlserverreceiver / nrmysqlreceiver / nrpostgresqlreceiver. As métricas personalizadas coletadas via sqlqueryreceiver aparecem sob a mesma entidade do Oracle, SQL Server, MySQL ou PostgreSQL no New Relic que os dados do receiver integrado, desde que os atributos de vinculação de entidade estejam configurados corretamente.

Pré-requisitos

  • O usuário do banco de dados configurado na fonte de dados deve ter o privilégio SELECT em qualquer visualização ou tabela que você pretenda consultar.
  • O binário do coletor deve incluir o componente sqlqueryreceiver.

Configuração

Adicione o bloco sqlqueryreceiver dentro da seção receivers: do seu oracle-config.yaml existente, ao lado do bloco nroracledb existente:

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

Defina os seguintes parâmetros para cada métrica:

Parâmetro

Descrição

<YOUR_DB_HOST>

Seu nome do host ou endereço IP. Por exemplo,

10.12.0.4

<YOUR_DB_PORT>

O número da sua porta. O valor padrão é definido como

1433

<YOUR_DB_USERNAME>

Seu nome de usuário do banco de dados Oracle. Por exemplo

newrelic

<YOUR_DB_PASSWORD>

A senha do seu banco de dados Oracle.

<YOUR_SERVICE_NAME>

O nome do seu serviço Oracle. Por exemplo

master

collection_interval

Com que frequência executar as consultas e coletar métricas. Por exemplo,

30s

,

60s

<YOUR_CUSTOM_SQL>

A consulta SQL a ser executada.

Importante

Certifique-se de que as suas consultas personalizadas não coletem ou exponham PII ou dados confidenciais.

<YOUR_METRIC_NAME>

O nome da sua métrica exibido no New Relic. Use o prefixo

oracledb.

para consistência. Por exemplo

oracledb.custom.wait_time_ms

<VALUE_COLUMN>

A coluna do resultado da consulta cujo valor se torna o valor da métrica. Por exemplo

wait_time_ms

<VALUE_TYPE>

Tipo de dados da coluna de valor. Opções:

int

,

double

. O padrão é

int

se omitido. Por exemplo

int

<DATA_TYPE>

Tipo de métrica OTLP. Use

gauge

para valores atuais/de snapshot. Use

sum

para contadores cumulativos. O padrão é

gauge

se omitido. Por exemplo

gauge

<UNIT>

Unidade de medida do valor da métrica. Usado como metadados no New Relic. Por exemplo

ms

,

By

,

s

,

%

,

1

<ATTRIBUTE_COLUMNS>

Colunas do resultado da consulta que se tornam rótulos/dimensões de métricas. Usado para filtrar e facetar no NRQL. Por exemplo

["wait_type", "database_name"]

Importante

Para usuários do Oracle CDB (prefixo C##), codifique # como %23 na URL da fonte de dados. Por exemplo: c##newrelic deve ser c%23%23newrelic

Convenção de nomenclatura

Os nomes das métricas devem começar com oracledb. para serem associados à entidade correta no New Relic. Métricas com um prefixo diferente serão ingeridas, mas não aparecerão sob a entidade do banco de dados.

Síntese de entidade

Adicione os processadores resource/add_event_name e resource/add_host para definir server.address e server.port com os mesmos valores usados pelo receptor do banco de dados. Sem isso, as métricas personalizadas não serão vinculadas à entidade do banco de dados.

Adicione os processadores na seção processors::

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

Configuração de Pipeline

Adicione um pipeline metrics/custom na seção service.pipelines: da configuração, junto aos pipelines existentes:

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]

Importante

Adicione tanto resource/add_event_name quanto resource/add_host antes de batch na lista de processadores.

NRQL para validar dados

Após reiniciar o coletor, execute o seguinte para confirmar se a métrica personalizada está chegando:

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

Resolução de problemas [#troubleshooting]

ProblemaCausaConsertar
ORA-00942: table or view does not existUsuário do banco de dados sem privilégio SELECTConceda SELECT ON <VIEW_NAME> ao usuário
missing port in address# em nome de usuário/senha não codificados em URLSubstitua # por %23 na URL da fonte de dados
Nenhum dado no New Relicserver.address/server.port não definido ou incompatívelAdicione os processadores resource/add_event_name e resource/add_host com os valores corretos
Métrica não sob a entidade de banco de dadosNome da métrica sem o prefixo obrigatórioCertifique-se de que os nomes das métricas comecem com oracledb.

Se nenhuma das opções acima resolver o problema, verifique os logs do próprio coletor em busca de erros:

bash
$
sudo journalctl -u nrdot-collector -f

Adicione o bloco sqlqueryreceiver dentro da seção receivers: da configuração do coletor do SQL Server, ao lado do bloco nrsqlserver existente:

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>"]

Defina os seguintes parâmetros para cada métrica:

Parâmetro

Descrição

<YOUR_DB_HOST>

Nome do host ou endereço IP do seu servidor. Por exemplo,

10.12.0.4

<YOUR_DB_PORT>

O número da porta do seu servidor. O valor padrão é definido como

1433

<YOUR_DB_USERNAME>

Seu nome de usuário do SQL Server. Omita para autenticação de domínio do Windows/GMSA. Por exemplo

newrelic

<YOUR_DB_PASSWORD>

Sua senha do SQL Server. Omita para autenticação de domínio do Windows/GMSA. Por exemplo

secret

<YOUR_DATABASE_NAME>

O nome do seu banco de dados para usar como contexto de conexão inicial. Por exemplo

master

collection_interval

Com que frequência executar as consultas e coletar métricas. Por exemplo,

30s

,

60s

<YOUR_CUSTOM_SQL>

A consulta SQL a ser executada. Por exemplo, SELECT SUM(pages_kb) / 1024 AS size_mb, type FROM sys.dm_os_memory_clerks GROUP BY type

Importante

Certifique-se de que as suas consultas personalizadas não coletem ou exponham PII ou dados confidenciais.

<YOUR_METRIC_NAME>

O nome da sua métrica exibido no New Relic. Use o prefixo

sqlserver.

para consistência. Por exemplo

sqlserver.custom.wait_time_ms

<VALUE_COLUMN>

A coluna do resultado da consulta cujo valor se torna o valor da métrica. Por exemplo

wait_time_ms

<VALUE_TYPE>

Tipo de dados da coluna de valor. Opções:

int

,

double

. O padrão é

int

se omitido. Por exemplo

int

<DATA_TYPE>

Tipo de métrica OTLP. Use

gauge

para valores atuais/de snapshot. Use

sum

para contadores cumulativos. O padrão é

gauge

se omitido. Por exemplo

gauge

<UNIT>

Unidade de medida do valor da métrica. Usado como metadados no New Relic. Por exemplo

ms

,

By

,

s

,

%

,

1

<ATTRIBUTE_COLUMNS>

Colunas do resultado da consulta que se tornam rótulos/dimensões de métricas. Usado para filtrar e facetar no NRQL. Por exemplo

["wait_type", "database_name"]

Convenção de nomenclatura

Os nomes das métricas devem começar com sqlserver. para serem associados à entidade correta no New Relic. Métricas com um prefixo diferente serão ingeridas, mas não aparecerão sob a entidade do banco de dados.

Síntese de entidade

Adicione um processador resource/add_host para definir server.address e server.port com os mesmos valores usados pelo receptor do banco de dados. Sem isso, as métricas personalizadas não serão vinculadas à entidade do banco de dados.

Adicione o processador na seção processors::

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

Configuração de Pipeline

Adicione um pipeline metrics/custom na seção service.pipelines: da configuração, junto aos pipelines existentes:

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

Importante

Adicione resource/add_host antes de batch na lista de processadores.

NRQL para validar dados

Após reiniciar o coletor, execute o seguinte para confirmar se a métrica personalizada está chegando:

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

Adicione o bloco sqlqueryreceiver dentro da seção receivers: do seu mysql-config.yaml existente, ao lado do bloco nrmysql existente:

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>"]

Defina os seguintes parâmetros para cada métrica:

Parâmetro

Descrição

<YOUR_DB_HOST>

O nome do host ou endereço IP do seu MySQL. Por exemplo,

10.12.0.4

<YOUR_DB_PORT>

O número da porta do MySQL. O valor padrão é

3306

<YOUR_DATABASE_NAME>

O banco de dados ao qual se conectar. Por exemplo

information_schema

<YOUR_DB_USERNAME>

Seu nome de usuário de monitoramento do MySQL. Por exemplo

newrelic

<YOUR_DB_PASSWORD>

Sua senha de monitoramento do MySQL.

collection_interval

Com que frequência executar as consultas e coletar métricas. Por exemplo,

30s

,

60s

<YOUR_CUSTOM_SQL>

A consulta SQL a ser executada.

Importante

Certifique-se de que as suas consultas personalizadas não coletem ou exponham PII ou dados confidenciais.

<YOUR_METRIC_NAME>

O nome da sua métrica exibido no New Relic. Deve ser prefixado com

mysql.

para consistência. Por exemplo

mysql.custom.wait_time_ms

<VALUE_COLUMN>

A coluna do resultado da consulta cujo valor se torna o valor da métrica. Por exemplo

wait_time_ms

<VALUE_TYPE>

Tipo de dados da coluna de valor. Opções:

int

,

double

. O padrão é

int

se omitido. Por exemplo

int

<DATA_TYPE>

Tipo de métrica OTLP. Use

gauge

para valores atuais/de snapshot. Use

sum

para contadores cumulativos. O padrão é

gauge

se omitido. Por exemplo

gauge

<UNIT>

Unidade de medida do valor da métrica. Usado como metadados no New Relic. Por exemplo

ms

,

By

,

s

,

%

,

1

<ATTRIBUTE_COLUMNS>

Colunas do resultado da consulta que se tornam rótulos/dimensões de métricas. Usado para filtrar e facetar no NRQL. Por exemplo

["wait_type", "database_name"]

Importante

A string de conexão datasource do MySQL usa o formato <user>:<password>@tcp(<host>:<port>)/<dbname>. Não reutilize o formato de string de conexão de outro banco de dados aqui.

Convenção de nomenclatura

Os nomes das métricas devem começar com mysql. para serem associados à entidade correta no New Relic. Métricas com um prefixo diferente serão ingeridas, mas não aparecerão sob a entidade do banco de dados.

Configuração de Pipeline

Adicione um pipeline metrics/custom na seção service.pipelines: da configuração, junto ao pipeline existente:

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

NRQL para validar dados

Após reiniciar o coletor, execute o seguinte para confirmar se a métrica personalizada está chegando:

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

Resolução de problemas [#troubleshooting-mysql]

ProblemaCausaConsertar
Erro 1045: acesso negado para o usuárioNome de usuário/senha incorretosVerifique novamente as credenciais; use a abordagem de campos individuais em vez de construir manualmente a string da fonte de dados
Erro 1146: a tabela não existe/erro de sintaxe SQLO SQL personalizado faz referência a uma tabela/coluna que não existe nesta versão do MySQL/MariaDB ou usa sintaxe não suportadaTeste a consulta diretamente na instância primeiro com o mesmo usuário antes de adicioná-la à configuração do receiver
Métrica não sob a entidade de banco de dadosNome da métrica sem o prefixo mysql.Certifique-se de que os nomes das métricas comecem com mysql.
Erro de negociação TLS/SSL ao conectar a um servidor que exige TLSO driver não usa TLS por padrão, a menos que configurado.Defina o parâmetro tls em additional_params para corresponder aos requisitos de TLS do servidor

Se nenhuma das opções acima resolver o problema, verifique os logs do próprio coletor em busca de erros:

bash
$
sudo journalctl -u nrdot-collector -f

Adicione o bloco sqlqueryreceiver dentro da seção receivers: do seu postgres-config.yaml existente, ao lado do bloco nrpostgresql existente:

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>"]

Defina os seguintes parâmetros para cada métrica:

Parâmetro

Descrição

<YOUR_DB_HOST>

Seu nome do host ou endereço IP. Por exemplo,

10.12.0.4

<YOUR_DB_PORT>

Seu número de porta. O valor padrão é

5432

<YOUR_DATABASE_NAME>

O nome do seu banco de dados para usar como contexto de conexão inicial. Por exemplo

testdb

<YOUR_DB_USERNAME>

Seu nome de usuário do banco de dados PostgreSQL. Por exemplo

newrelic

<YOUR_DB_PASSWORD>

Sua senha do banco de dados PostgreSQL.

collection_interval

Com que frequência executar as consultas e coletar métricas. Por exemplo,

30s

,

60s

<YOUR_CUSTOM_SQL>

A consulta SQL a ser executada.

Importante

Certifique-se de que as suas consultas personalizadas não coletem ou exponham PII ou dados confidenciais.

<YOUR_METRIC_NAME>

O nome da sua métrica exibido no New Relic. Deve ser prefixado com

postgresql.

para consistência. Por exemplo

postgresql.custom.connections_by_state

<VALUE_COLUMN>

A coluna do resultado da consulta cujo valor se torna o valor da métrica. Por exemplo

conn_count

<VALUE_TYPE>

Tipo de dados da coluna de valor. Opções:

int

,

double

. O padrão é

int

se omitido. Por exemplo

int

<DATA_TYPE>

Tipo de métrica OTLP. Use

gauge

para valores atuais/de snapshot. Use

sum

para contadores cumulativos. O padrão é

gauge

se omitido. Por exemplo

gauge

<UNIT>

Unidade de medida do valor da métrica. Usado como metadados no New Relic. Por exemplo

ms

,

By

,

s

,

%

,

1

<ATTRIBUTE_COLUMNS>

Colunas do resultado da consulta que se tornam rótulos/dimensões de métricas. Usado para filtrar e facetar no NRQL. Por exemplo

["state"]

Importante

Se o seu servidor PostgreSQL exigir TLS, defina sslmode adequadamente em additional_params (Abordagem 1) ou na string datasource (Abordagem 2) — por exemplo, sslmode: require. Quando omitido, o driver subjacente usa como padrão a negociação de SSL para conexões não locais, o que falha em um servidor que não está configurado para isso.

Convenção de nomenclatura

Os nomes das métricas devem começar com postgresql. para serem associados à entidade correta no New Relic. Métricas com um prefixo diferente serão ingeridas, mas não aparecerão sob a entidade do banco de dados.

Síntese de entidade

nrpostgresql sintetiza sua entidade de banco de dados a partir de server.address e server.port. Adicione um processador resource/add_host para registrar os mesmos valores server.address/server.port usados pelo receptor do banco de dados. Sem isso, as métricas personalizadas não serão vinculadas à entidade do banco de dados.

Adicione o processador na seção processors::

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

Importante

Se o seu pipeline nrpostgresql já tiver um processador resource/* definindo server.address/server.port (por exemplo, resource/postgresql), reutilize esse mesmo processador no pipeline metrics/custom abaixo em vez de duplicá-lo — ambos os receptores devem registrar valores idênticos para vincular à mesma entidade.

Configuração de Pipeline

Adicione um pipeline metrics/custom na seção service.pipelines: da configuração, junto aos pipelines existentes:

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]

Importante

Adicione resource/add_host antes de batch na lista de processadores.

NRQL para validar dados

Após reiniciar o coletor, execute o seguinte para confirmar se a métrica personalizada está chegando:

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

Resolução de problemas [#troubleshooting-postgresql]

ProblemaCausaConsertar
pq: SSL is not enabled on the serversslmode não definido, o driver assumiu como padrão a negociação de SSLDefina sslmode: disable (ou o modo que seu servidor suporta) em additional_params, ou na string datasource
pq: password authentication failed for userNome de usuário/senha incorretos ou caracteres especiais não escapados em uma string datasource brutaUse a Abordagem 1 (campos individuais) — o receiver faz o escape de URL de username/password automaticamente — ou faça o escape manual de caracteres especiais em datasource
Métrica não sob a entidade de banco de dadosNome da métrica sem o prefixo postgresql. obrigatório, ou server.address/server.port não definido ou incompatívelCertifique-se de que os nomes das métricas comecem com postgresql. e adicione resource/add_host (ou reutilize o processador de recursos nrpostgresql existente) com os valores corretos de host/porta

Se nenhuma das opções acima resolver o problema, verifique os logs do próprio coletor em busca de erros:

bash
$
sudo journalctl -u nrdot-collector -f
Copyright © 2026 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.