Solucionar problemas do Snowflake Connector for Kafka¶

Canal relata aumento de rows_error_count¶

Se o canal do Snowpipe Streaming relatar um aumento de rows_error_count, o comportamento do conector dependerá da configuração errors.tolerance:

• Com errors.tolerance=none (padrão), a tarefa do conector falha com ERROR_5030.

• Com errors.tolerance=all, o conector continua, mas registra a contagem de erros.

Para investigar:

1. Verifique a tabela de erros associada à sua tabela de destino para identificar os registros com falha. Consulte Tratamento de erros na arquitetura de alto desempenho do Snowpipe Streaming para obter mais detalhes.

2. Use a técnica de localização de lacunas descrita em Detecção e recuperação de erros usando offsets de metadados com as informações de deslocamento do Kafka na coluna RECORD_METADATA.

3. Analise os logs do conector para obter detalhes de erros (habilite errors.log.enable=true para registro detalhado).

Falha na tarefa do conector com ERROR_5030¶

ERROR_5030 indica que o conector detectou um erro de ingestão de dados. As causas comuns incluem:

• Incompatibilidades de tipo de dados entre o registro do Kafka e o esquema da tabela de destino.

• Um canal criado pelo usuário existe enquanto snowflake.validation=client_side é configurado. A validação do lado do cliente funciona apenas com o canal padrão.

• Alterações de esquema nos registros do Kafka que não podem ser evoluídas automaticamente.

Para resolver:

1. Revise a mensagem de erro e os logs do conector para ver a causa específica.

2. Se estiver usando a validação do lado do cliente com um canal definido pelo usuário, mude para snowflake.validation=server_side ou remova o canal definido pelo usuário.

3. Corrija os dados no tópico de origem do Kafka ou ajuste o esquema da tabela de destino.

Problemas de evolução de esquema¶

Com a validação do lado do servidor, a evolução de esquema nem sempre pode inferir o tipo de dados correto. Por exemplo, ela não pode inferir colunas binárias e pode interpretar uma cadeia de caracteres no formato "2026-04-13" como DATE em vez de TEXT.

Se a evolução de esquema produzir tipos de colunas inesperados:

• Use a validação do lado do cliente (snowflake.validation=client_side) para melhorar a inferência de tipo.

• Crie previamente a tabela com o esquema correto antes de iniciar o conector.

Falhas na autenticação¶

O conector v4 oferece suporte apenas à autenticação de par de chaves. Problemas comuns de autenticação:

• Chave privada inválida: verifique se o valor snowflake.private.key é uma chave privada PKCS#8 válida codificada em Base64.

• Frase secreta da chave: se a sua chave está criptografada, defina snowflake.private.key.passphrase como a frase secreta correta.

• Privilégios da função: verifique se a função especificada em snowflake.role.name tem os privilégios necessários. Consulte Snowflake Connector for Kafka: Configurar o Snowflake para obter mais detalhes.

Erros de autorização¶

Se o conector encontrar erros de autorização do Snowflake, o comportamento dependerá da configuração enable.task.fail.on.authorization.errors:

• Com enable.task.fail.on.authorization.errors=false (padrão), o conector tenta novamente.

• Com enable.task.fail.on.authorization.errors=true, a tarefa do conector falha imediatamente.

Conversor incompatível com esquematização¶

Quando snowflake.enable.schematization=true (o padrão), StringConverter e ByteArrayConverter não são compatíveis como conversores de valor. Em vez disso, use conversores estruturados:

• org.apache.kafka.connect.json.JsonConverter

• io.confluent.connect.avro.AvroConverter

• io.confluent.connect.protobuf.ProtobufConverter

Propriedades de configuração da v3 removidas¶

Se você encontrar erros de propriedades de configuração não reconhecidas, verifique se está usando propriedades que foram removidas da v4. Consulte Migrar do conector Kafka v3 para v4 para conferir a lista completa de configurações removidas.

Falhas do validador de compatibilidade na inicialização¶

Se o conector falhar na inicialização com erros de valores de configuração ausentes ou incompatíveis, o validador de compatibilidade (snowflake.streaming.validate.compatibility.with.classic) está verificando sua configuração em relação aos requisitos de migração da v3.

• Para novas instalações: defina snowflake.streaming.validate.compatibility.with.classic=false para ignorar a verificação.

• Para migrações da v3: defina explicitamente todas as propriedades de compatibilidade necessárias. Consulte snowflake.streaming.validate.compatibility.with.classic para conferir a lista completa.

Aumento de atraso na ingestão¶

Se latest-consumer-offset menos a lacuna persisted-in-snowflake-offset está aumentando (visível pelas métricas JMX), o conector está atrasado.

Para resolver:

• Aumento de tarefas: defina tasks.max mais próximo do número total de partições do Kafka. Normalmente, o desempenho ideal é 2 tarefas por núcleo de CPU no cluster Kafka Connect.

• Verificação de backpressure: se a métrica backpressure-rewind-count está aumentando, o SDK do Snowpipe Streaming está no limite da capacidade. Considere expandir o cluster Kafka Connect.

• Revisão da memória da JVM: limite o heap da JVM a aproximadamente 50% da memória disponível. O SDK do Snowpipe Streaming baseado em Rust usa memória fora do heap para buffer, que não é gerenciada pela JVM.

Armazenamento em cache de tabelas e canais¶

O conector armazena em cache as verificações de existência de tabelas e canais para reduzir consultas ao banco de dados. Se você tiver problemas com o conector que não detecta tabelas ou canais recém-criados, ajuste o tempo de expiração do cache:

snowflake.cache.table.exists.expire.ms=60000
snowflake.cache.pipe.exists.expire.ms=60000

Recuperação do canal mantida¶

As recuperações ocasionais de canal são normais. Entretanto, se a métrica channel-recovery-count estiver aumentando continuamente, isso poderá indicar:

• Alterações de esquema na tabela de destino que entram em conflito com o esquema armazenado em cache do conector.

• Alterações de permissão que afetam a função do conector.

• Instabilidade de rede entre o cluster Kafka Connect e o Snowflake.

Revise os logs do conector para verificar os motivos específicos da recuperação.

Vazamento de cliente SDK¶

Se a métrica JMX sdk-client-count aumentar continuamente, o conector talvez esteja vazando clientes SDK do Snowpipe Streaming. Cada tabela de destino distinta deve ter um cliente SDK. Se a contagem exceder o número de tabelas distintas, entre em contato com o suporte Snowflake.

Canal SSv1 não encontrado durante a migração de deslocamento¶

Se o conector falhar com um erro de canal não encontrado ao usar snowflake.streaming.classic.offset.migration=strict:

• Verifique se você está usando o mesmo nome do conector que a sua implantação da v3.

• Verifique se snowflake.streaming.classic.offset.migration.include.connector.name corresponde à configuração da v3 para snowflake.streaming.channel.name.include.connector.name.

• Mude para o modo best_effort se o canal já tiver sido limpo ou se você estiver adicionando novos tópicos que não existiam na v3.

Duplicatas após a migração¶

Se você encontrar registros duplicados depois de migrar da v3:

• Verifique se RECORD_METADATA contém campos de tópico, partição e deslocamento.

• Use a consulta de desduplicação em Fazendo downgrade de v4 para v3 para remover as duplicatas.