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
SELECTem 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: doubleDefina os seguintes parâmetros para cada métrica:
Parâmetro | Descrição |
|---|---|
| Seu nome do host ou endereço IP. Por exemplo,
|
| O número da sua porta. O valor padrão é definido como
|
| Seu nome de usuário do banco de dados Oracle. Por exemplo
|
| A senha do seu banco de dados Oracle. |
| O nome do seu serviço Oracle. Por exemplo
|
| Com que frequência executar as consultas e coletar métricas. Por exemplo,
,
|
| A consulta SQL a ser executada. ImportanteCertifique-se de que as suas consultas personalizadas não coletem ou exponham PII ou dados confidenciais. |
| O nome da sua métrica exibido no New Relic. Use o prefixo
para consistência. Por exemplo
|
| A coluna do resultado da consulta cujo valor se torna o valor da métrica. Por exemplo
|
| Tipo de dados da coluna de valor. Opções:
,
. O padrão é
se omitido. Por exemplo
|
| Tipo de métrica OTLP. Use
para valores atuais/de snapshot. Use
para contadores cumulativos. O padrão é
se omitido. Por exemplo
|
| Unidade de medida do valor da métrica. Usado como metadados no New Relic. Por exemplo
,
,
,
,
|
| Colunas do resultado da consulta que se tornam rótulos/dimensões de métricas. Usado para filtrar e facetar no NRQL. Por exemplo
|
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: upsertConfiguraçã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 MetricWHERE otel.library.name LIKE '%sqlqueryreceiver%'AND metricName LIKE 'oracledb.%'SINCE 1 hour agoResolução de problemas [#troubleshooting]
| Problema | Causa | Consertar |
|---|---|---|
ORA-00942: table or view does not exist | Usuário do banco de dados sem privilégio SELECT | Conceda SELECT ON <VIEW_NAME> ao usuário |
missing port in address | # em nome de usuário/senha não codificados em URL | Substitua # por %23 na URL da fonte de dados |
| Nenhum dado no New Relic | server.address/server.port não definido ou incompatível | Adicione os processadores resource/add_event_name e resource/add_host com os valores corretos |
| Métrica não sob a entidade de banco de dados | Nome da métrica sem o prefixo obrigatório | Certifique-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:
$sudo journalctl -u nrdot-collector -fAdicione 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 |
|---|---|
| Nome do host ou endereço IP do seu servidor. Por exemplo,
|
| O número da porta do seu servidor. O valor padrão é definido como
|
| Seu nome de usuário do SQL Server. Omita para autenticação de domínio do Windows/GMSA. Por exemplo
|
| Sua senha do SQL Server. Omita para autenticação de domínio do Windows/GMSA. Por exemplo
|
| O nome do seu banco de dados para usar como contexto de conexão inicial. Por exemplo
|
| Com que frequência executar as consultas e coletar métricas. Por exemplo,
,
|
| A consulta SQL a ser executada. Por exemplo, ImportanteCertifique-se de que as suas consultas personalizadas não coletem ou exponham PII ou dados confidenciais. |
| O nome da sua métrica exibido no New Relic. Use o prefixo
para consistência. Por exemplo
|
| A coluna do resultado da consulta cujo valor se torna o valor da métrica. Por exemplo
|
| Tipo de dados da coluna de valor. Opções:
,
. O padrão é
se omitido. Por exemplo
|
| Tipo de métrica OTLP. Use
para valores atuais/de snapshot. Use
para contadores cumulativos. O padrão é
se omitido. Por exemplo
|
| Unidade de medida do valor da métrica. Usado como metadados no New Relic. Por exemplo
,
,
,
,
|
| Colunas do resultado da consulta que se tornam rótulos/dimensões de métricas. Usado para filtrar e facetar no NRQL. Por exemplo
|
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: upsertConfiguraçã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 MetricWHERE otel.library.name LIKE '%sqlqueryreceiver%'AND metricName LIKE 'sqlserver.%'SINCE 1 hour agoAdicione 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 |
|---|---|
| O nome do host ou endereço IP do seu MySQL. Por exemplo,
|
| O número da porta do MySQL. O valor padrão é
|
| O banco de dados ao qual se conectar. Por exemplo
|
| Seu nome de usuário de monitoramento do MySQL. Por exemplo
|
| Sua senha de monitoramento do MySQL. |
| Com que frequência executar as consultas e coletar métricas. Por exemplo,
,
|
| A consulta SQL a ser executada. ImportanteCertifique-se de que as suas consultas personalizadas não coletem ou exponham PII ou dados confidenciais. |
| O nome da sua métrica exibido no New Relic. Deve ser prefixado com
para consistência. Por exemplo
|
| A coluna do resultado da consulta cujo valor se torna o valor da métrica. Por exemplo
|
| Tipo de dados da coluna de valor. Opções:
,
. O padrão é
se omitido. Por exemplo
|
| Tipo de métrica OTLP. Use
para valores atuais/de snapshot. Use
para contadores cumulativos. O padrão é
se omitido. Por exemplo
|
| Unidade de medida do valor da métrica. Usado como metadados no New Relic. Por exemplo
,
,
,
,
|
| Colunas do resultado da consulta que se tornam rótulos/dimensões de métricas. Usado para filtrar e facetar no NRQL. Por exemplo
|
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 MetricWHERE otel.library.name LIKE '%sqlqueryreceiver%'AND metricName LIKE 'mysql.%'SINCE 1 hour agoResolução de problemas [#troubleshooting-mysql]
| Problema | Causa | Consertar |
|---|---|---|
| Erro 1045: acesso negado para o usuário | Nome de usuário/senha incorretos | Verifique 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 SQL | O SQL personalizado faz referência a uma tabela/coluna que não existe nesta versão do MySQL/MariaDB ou usa sintaxe não suportada | Teste 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 dados | Nome 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 TLS | O 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:
$sudo journalctl -u nrdot-collector -fAdicione 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 |
|---|---|
| Seu nome do host ou endereço IP. Por exemplo,
|
| Seu número de porta. O valor padrão é
|
| O nome do seu banco de dados para usar como contexto de conexão inicial. Por exemplo
|
| Seu nome de usuário do banco de dados PostgreSQL. Por exemplo
|
| Sua senha do banco de dados PostgreSQL. |
| Com que frequência executar as consultas e coletar métricas. Por exemplo,
,
|
| A consulta SQL a ser executada. ImportanteCertifique-se de que as suas consultas personalizadas não coletem ou exponham PII ou dados confidenciais. |
| O nome da sua métrica exibido no New Relic. Deve ser prefixado com
para consistência. Por exemplo
|
| A coluna do resultado da consulta cujo valor se torna o valor da métrica. Por exemplo
|
| Tipo de dados da coluna de valor. Opções:
,
. O padrão é
se omitido. Por exemplo
|
| Tipo de métrica OTLP. Use
para valores atuais/de snapshot. Use
para contadores cumulativos. O padrão é
se omitido. Por exemplo
|
| Unidade de medida do valor da métrica. Usado como metadados no New Relic. Por exemplo
,
,
,
,
|
| Colunas do resultado da consulta que se tornam rótulos/dimensões de métricas. Usado para filtrar e facetar no NRQL. Por exemplo
|
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: upsertImportante
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 MetricWHERE otel.library.name LIKE '%sqlqueryreceiver%'AND metricName LIKE 'postgresql.%'SINCE 1 hour agoResolução de problemas [#troubleshooting-postgresql]
| Problema | Causa | Consertar |
|---|---|---|
pq: SSL is not enabled on the server | sslmode não definido, o driver assumiu como padrão a negociação de SSL | Defina sslmode: disable (ou o modo que seu servidor suporta) em additional_params, ou na string datasource |
pq: password authentication failed for user | Nome de usuário/senha incorretos ou caracteres especiais não escapados em uma string datasource bruta | Use 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 dados | Nome da métrica sem o prefixo postgresql. obrigatório, ou server.address/server.port não definido ou incompatível | Certifique-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:
$sudo journalctl -u nrdot-collector -f