Solução de problemas do conector¶

Resolução de problemas durante a instalação do conector¶

Os problemas mais comuns durante a instalação do conector estão relacionados ao conjunto de ACLs nas tabelas de metadados, como sys_db_object, sys_dictionary e sys_glide_object. Além disso, o conector requer acesso à tabela sys_table_rotation para determinar a estratégia de ingestão correta e, opcionalmente, à tabela de diário (geralmente sys_audit_delete) para propagar a exclusão de dados.

# checking access to the sys_db_object table
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_db_object?sysparm_limit=1"

# checking access to the sys_db_object table
# expected fields in the result object: sys_id, super_class, name
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_db_object?sysparm_fields=sys_id,super_class,name&sysparm_limit=1&sysparm_query=name=sys_db_object"

# checking access to the sys_dictionary table
# expected fields in the result object: sys_id, name, element, internal_type
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_dictionary?sysparm_fields=sys_id,name,element,internal_type&sysparm_limit=1&sysparm_query=name=sys_dictionary"

# checking access to the sys_glide_object table
# expected fields in the result object: sys_id, name, scalar_type
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_glide_object?sysparm_fields=sys_id,name,scalar_type&sysparm_limit=1&sysparm_query=name=datetime"

# checking access to the sys_table_rotation table
# expected fields in the result object: sys_id, name
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_table_rotation?sysparm_fields=sys_id,name&sysparm_limit=1&sysparm_query=name=syslog"

# (optional) - check only if deletions auditing is going to be used
# checking access to the journal table
# if known, "&sysparm_query=tablename=<table_name>" or "&sysparm_query=documentkey=<sys_id>" can be appended to the request
# expected fields in the result object: sys_id, sys_created_on, documentkey, tablename
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/<journal_table>?sysparm_fields=sys_id,sys_created_on,documentkey,tablename&sysparm_limit=1"

Verificação da conexão com a instância do ServiceNow®¶

Para verificar se Snowflake Connector for ServiceNow® pode acessar a instância de ServiceNow®, chame o procedimento armazenado TEST_CONNECTION:

CALL TEST_CONNECTION();

Se o conector estiver configurado corretamente, o procedimento armazenado retornará a seguinte resposta:

{
  "responseCode": "OK",
  "message": "Test request to ServiceNow succeeded."
}

Verificação do acesso à tabela específica na instância do ServiceNow®¶

Para verificar se Snowflake Connector for ServiceNow® pode acessar dados da tabela específica na instância de ServiceNow®, chame o procedimento armazenado TEST_TABLE_ACCESS:

CALL TEST_TABLE_ACCESS('<table_name>');

Onde:

table_name

Especifica o nome de uma tabela na instância do ServiceNow®.

Se o conector estiver configurado corretamente e os dados estiverem disponíveis para o usuário utilizado pelo conector, o procedimento armazenado retornará a seguinte resposta:

{
  "responseCode": "OK",
  "message": "Test request to ServiceNow® succeeded."
}

Comparação de contagem de linhas de tabela no ServiceNow® e no Snowflake¶

Para comparar a contagem atual de linhas de uma tabela no ServiceNow® e Snowflake, chame o procedimento CHECK_ROW_COUNT:

CALL CHECK_ROW_COUNT('<table_name>');

ou

CALL CHECK_ROW_COUNT('<table_name>', <max_sys_created_on>);

Onde:

table_name

Especifica o nome de uma tabela na instância do ServiceNow®.

max_sys_created_on

Especifica filtro opcional adicional no valor máximo da coluna sys_created_on. Somente linhas que corresponderem a este filtro serão contadas. O valor padrão deste parâmetro é NULL, o que significa que o filtro não será aplicado. Este parâmetro ajuda a comparar apenas contagens de registros já ingeridos no Snowflake, sem levar em conta os registros criados recentemente no ServiceNow®, mas ainda não ingeridos no Snowflake.

O exemplo a seguir mostra como chamar o procedimento armazenado CHECK_ROW_COUNT com o parâmetro max_sys_created_on:

CALL CHECK_ROW_COUNT('sys_db_object', '2021-09-10 12:34:56');

Se o tempo do procedimento expirar, o procedimento não poderia usar a stats API para determinar a contagem de linhas da tabela no ServiceNow®. Isto pode significar que o número de linhas nesta tabela seja muito grande para ser contado por esta API.

Verificação do status da ingestão de uma linha¶

Para verificar o status da ingestão de uma linha em todos os lugares possíveis no ServiceNow® e Snowflake, chame o procedimento CHECK_RECORD_HISTORY:

CALL CHECK_RECORD_HISTORY('<table_name>', '<sys_id>');

Onde:

table_name

Especifica o nome de uma tabela na instância do ServiceNow®.

sys_id

Especifica o sys_id da linha a ser verificada.

O procedimento devolve um objeto JSON contendo as seguintes propriedades:

Como determinar se uma tabela foi auditada para exclusão¶

O Snowflake Connector for ServiceNow® depende de auditoria para propagar a exclusão de registros para o Snowflake.

Para verificar se uma determinada tabela no ServiceNow® está configurada para auditar a exclusão de registros, chame o procedimento armazenado CHECK_IF_AUDIT_ENABLED:

CALL CHECK_IF_AUDIT_ENABLED('<table_name>');

Onde:

table_name

Especifica o nome de uma tabela na instância do ServiceNow®.

O procedimento devolve um objeto JSON contendo as seguintes propriedades:

CALL GET_TROUBLESHOOTING_DATA(<from_timestamp>, <to_timestamp>);

CALL GET_TROUBLESHOOTING_DATA('2024-02-05 10:00:00', '2024-02-10 22:30:00');

Recuperação de um objeto inacessível¶

O conector requer vários objetos de banco de dados que são externos ao aplicativo do conector. Se esses objetos não estiverem disponíveis, o conector falhará ou deixará de funcionar corretamente. Situações em que os objetos podem ficar indisponíveis incluem:

• Descarte de objetos.

• Recriação de um objeto sem manter ou restaurar as concessões necessárias.

• Revogação das concessões necessárias para que o conector utilize esses objetos.

Na maioria dos casos, você pode restaurar estes objetos manualmente recriando-os e concedendo os privilégios necessários. As seções a seguir descrevem como restaurar diferentes objetos.

Erro ao ingerir dados da tabela. A solicitação para ServiceNow® falhou após 2 tentativas.¶

O erro ocorre devido a uma falha na ingestão da tabela. Você pode verificar isso na exibição CONNECTOR_ERRORS. A mensagem de erro pode incluir as seguintes frases:

• Erro ao ingerir dados da tabela

• O tamanho mínimo de página de 1 foi atingido

• A solicitação para ServiceNow® falhou após 2 tentativas

• Solicitação para ServiceNow® com tempo esgotado

O erro significa que o conector tentou realizar solicitações para ServiceNow® API. ServiceNow® API não conseguiu responder corretamente a nenhuma dessas solicitações. Isso geralmente indica um problema de desempenho com a API. Há várias soluções possíveis para esse problema:

• Aumentar o tempo limite da API no lado do ServiceNow®:

  1. Faça login na instância do ServiceNow®.

  2. Navegue até o painel Transaction Quota Rules.

  3. Localize e abra a regra REST Table API request timeout.

  4. Aumente o valor de Maximum Duration (seconds). A duração máxima que o conector pode suportar é de 120 segundos. Valores de duração mais altos não são compatíveis e resultarão em tempos limite no lado do conector.

• Certifique-se de que não haja ACLs desnecessários na tabela. Os ACLs têm um grande impacto no desempenho da API. O ideal é que o usuário do conector não tenha ACLs definidos na tabela. Se houver necessidade de omitir algumas linhas da tabela ingerida, considere o uso da filtragem de linhas.

• Na tabela do ServiceNow®, crie um índice composto nas colunas sys_updated_on e sys_id ou nas colunas sys_created_on e sys_id, se a coluna sys_updated_on não estiver presente.

• Investigue os registros do ServiceNow® para descobrir por que a API demorou a responder. Um bom ponto de partida é o registro de transações no ServiceNow®. Para ver as solicitações de conectores:

  1. Faça login na instância do ServiceNow®.

  2. Navegue até o painel System Logs > Transactions (all user).

  3. Filtre a tabela pela coluna Created by definida como usuário do conector e pela coluna URL que contém o nome da tabela ingerida.

  4. Verifique se a coluna Response time apresenta um tempo de resposta anormalmente alto, superior ao tempo limite de solicitação da API da tabela REST definido na etapa anterior.

  5. Investigue outras transações suspeitas para identificar possíveis gargalos.

Determinação do motivo da ausência de colunas em exibições niveladas¶

O conector cria exibições niveladas no esquema de destino com base nos metadados do ServiceNow®. Há vários motivos pelos quais uma coluna pode estar ausente no lado do Snowflake.

SELECT * FROM <dest_db>.<dest_schema>.sys_dictionary__view WHERE name = '<table_name>' AND element = '<column_name>';

SELECT
    sys_id,
    name,
    PARSE_JSON(super_class):value::string AS super_class_sys_id
FROM <dest_db>.<dest_schema>.sys_db_object__view
START WITH name = '<table_name>'
CONNECT BY sys_id = PRIOR super_class_sys_id;

SELECT flattened_views_status, flattened_views_last_updated FROM tables_state WHERE table_name = '<table_name>';

https://<servicenow_instance>.service-now.com/api/now/table/sys_dictionary?sysparm_query=name=<table_name>^element=<column_name>

Tabela com cronograma contínuo desativada pelo conector¶

O conector desativa automaticamente as tabelas com cronograma contínuo quando detecta que a ingestão nessa tabela falhou por 10 vezes consecutivas, e a causa de todas as execuções de ingestão com falha está relacionada à instância do ServiceNow®. Esse mecanismo evita a sobrecarga da instância do ServiceNow® quando muitas tabelas com cronograma contínuo são ativadas e permite que a instância do ServiceNow® se recupere depois que a tabela é desativada. O conector não habilita a tabela novamente de forma automática, ela deve ser habilitada manualmente pelo usuário.

A informação de que uma tabela está automaticamente desativada fica visível na exibição CONNECTOR_ERRORS ao filtrar pelo código TABLE_INGESTION_DISABLED. Quando o erro ocorrer, investigue por que as execuções de ingestão na tabela falharam. Você pode encontrar informações detalhadas sobre os erros na exibição CONNECTOR_ERRORS após filtrar pelo código INGESTION_FAILED.

Depois que a causa do erro for investigada e resolvida, a tabela poderá ser habilitada novamente chamando o procedimento ENABLE_TABLE ou ENABLE_TABLES.

Conector indisponível¶

O conector pode entrar em um estado de ERROR, o que pode acontecer por vários motivos. Por exemplo, o erro interno do conector, que não pode ser recuperado. Nessas situações, a mensagem de erro Connector unavailable será exibida ao examinar o estado do conector.

Atualmente, não há mecanismo de recuperação automática para esse estado. No entanto, ainda é possível executar diversas funções de conector, incluindo o procedimento EXPORT_CONNECTOR_STATE.

Para examinar se o conector está em um estado ERROR, execute a consulta:

CALL GET_CONNECTOR_STATUS();

Além disso, entre em contato com o suporte Snowflake para nos ajudar a entender melhor o problema ou determinar como ele pode ser evitado. Também é necessário executar a reinstalação manual do conector para restaurar o conector para um estado de funcionamento. Observe que os dados ingeridos anteriormente não são perdidos e o conector pode continuar a ingestão de onde parou anteriormente.