Dépanner le Snowflake Connector for Kafka¶

Le canal signale une augmentation de rows_error_count.¶

Si le canal Snowpipe Streaming signale une augmentation de rows_error_count, le comportement du connecteur dépend du paramètre errors.tolerance :

• Avec errors.tolerance=none (par défaut), la tâche du connecteur échoue avec ERROR_5030.

• Avec errors.tolerance=all, le connecteur continue de fonctionner, mais enregistre le nombre d’erreurs.

Pour enquêter :

1. Vérifiez la table d’erreurs associée à votre table cible pour identifier les enregistrements en échec. Voir Gestion des erreurs dans l’architecture hautes performances de Snowpipe Streaming pour plus de détails.

2. Utilisez la technique de recherche des écarts décrite dans Détecter les erreurs et y remédier à l’aide des décalages de métadonnées avec les informations de décalage Kafka provenant de la colonne RECORD_METADATA.

3. Examinez les journaux du connecteur pour obtenir des détails sur les erreurs (activez errors.log.enable=true pour obtenir des journaux complets).

La tâche du connecteur échoue avec ERROR _5030¶

ERROR_5030 indique que le connecteur a détecté une erreur d’ingestion de données. Les causes courantes sont les suivantes :

• Le type de données ne correspond pas entre l’enregistrement Kafka et le schéma de la table cible.

• Un canal créé par l’utilisateur existe alors que snowflake.validation=client_side est configurée. La validation côté client ne fonctionne qu’avec le canal par défaut.

• Les modifications du schéma dans les enregistrements Kafka ne peuvent pas être mises à jour automatiquement.

Pour résoudre cette erreur :

1. Examinez le message d’erreur et les journaux du connecteur pour en déterminer la cause exacte.

2. Si vous utilisez la validation côté client avec un canal défini par l’utilisateur, passez à snowflake.validation=server_side ou supprimez le canal défini par l’utilisateur.

3. Corrigez les données dans le sujet Kafka source ou ajustez le schéma de la table cible.

Problèmes d’évolution du schéma¶

Avec la validation côté serveur, l’évolution du schéma ne peut pas toujours déduire le type de données correct. Par exemple, il ne peut pas déduire de colonnes binaires et peut interpréter une chaîne comme "2026-04-13" en tant que DATE au lieu de TEXT.

Si l’évolution du schéma produit des types de colonnes inattendus :

• Utilisez la validation côté client (snowflake.validation=client_side) pour une meilleure inférence de type.

• Pré-créez la table avec le schéma correct avant de démarrer le connecteur.

Échecs d’authentification¶

Le connecteur v4 ne prend en charge que l’authentification par paire de clés. Problèmes d’authentification courants :

• Clé privée non valide : Vérifiez que la valeur snowflake.private.key est une clé privée PKCS#8 encodée en Base64 valide.

• Phrase secrète de clé : Si votre clé est chiffrée, définissez snowflake.private.key.passphrase sur la phrase secrète correcte.

• Privilèges de rôle : Vérifiez que le rôle spécifié dans snowflake.role.name dispose des privilèges requis. Voir Snowflake Connector for Kafka : Configurer Snowflake pour plus de détails.

Erreurs d’autorisation¶

Si le connecteur rencontre des erreurs d’autorisation depuis Snowflake, le comportement dépend du paramètre enable.task.fail.on.authorization.errors :

• Avec enable.task.fail.on.authorization.errors=false (par défaut), le connecteur effectue une nouvelle tentative.

• Avec enable.task.fail.on.authorization.errors=true, la tâche du connecteur échoue immédiatement.

Convertisseur non pris en charge avec la schématisation¶

Lorsque snowflake.enable.schematization=true (par défaut), StringConverter et ByteArrayConverter ne sont pas pris en charge en tant que convertisseurs de valeurs. Utilisez plutôt des convertisseurs structurés :

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

• io.confluent.connect.avro.AvroConverter

• io.confluent.connect.protobuf.ProtobufConverter

Suppression des propriétés de configuration de la v3¶

Si vous constatez des erreurs concernant des propriétés de configuration non reconnues, vérifiez si vous utilisez des propriétés qui ont été supprimées dans la v4. Consultez Migrer du connecteur Kafka v3 vers v4 pour obtenir la liste complète des configurations supprimées.

Échecs du validateur de compatibilité au démarrage¶

Si le connecteur échoue au démarrage avec des erreurs concernant des valeurs de configuration manquantes ou incompatibles, le validateur de compatibilité (snowflake.streaming.validate.compatibility.with.classic) vérifie votre configuration par rapport aux exigences de migration v3.

• Pour les nouvelles installations : Définissez snowflake.streaming.validate.compatibility.with.classic=false pour ignorer la vérification.

• Pour les migrations depuis v3 : Définissez explicitement toutes les propriétés de compatibilité requises. Consultez snowflake.streaming.validate.compatibility.with.classic pour obtenir la liste complète.

Délai d’ingestion prolongé¶

Si le latest-consumer-offset moins l’écart persisted-in-snowflake-offset augmente (visible à travers les métriques JMX), le connecteur est en retard.

Pour résoudre cette erreur :

• Ajouter des tâches : Définissez tasks.max sur une valeur plus proche du nombre total de partitions Kafka. La performance optimale est généralement de deux tâches par cœur de CPU sur le cluster Kafka Connect.

• Vérifier la contre-pression : Si la métrique backpressure-rewind-count augmente, le SDK Snowpipe Streaming a atteint sa capacité maximale. Envisagez de réduire votre cluster Kafka Connect.

• Examiner la mémoire de la JVM : Limitez la taille du tas de la JVM à environ 50 % de la mémoire disponible. Le SDK Snowpipe Streaming basé sur Rust utilise de la mémoire hors tas pour la mise en mémoire tampon, qui n’est pas gérée par la JVM.

Mise en cache des tables et des canaux¶

Le connecteur met en cache les contrôles d’existence des tables et des canaux afin de réduire les requêtes dans la base de données. Si vous rencontrez des problèmes avec le connecteur qui ne détecte pas les tables ou les canaux nouvellement créés, ajustez le délai d’expiration du cache :

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

Récupération soutenue des canaux¶

Les récupérations de canaux occasionnelles sont normales. Cependant, si la métrique channel-recovery-count augmente continuellement, cela peut indiquer :

• Des modifications du schéma de la table cible qui entrent en conflit avec le schéma mis en cache du connecteur.

• Des modifications d’autorisations qui affectent le rôle du connecteur.

• Une instabilité du réseau entre le cluster Kafka Connect et Snowflake.

Examinez les journaux du connecteur pour connaître les raisons précises de la récupération.

Fuite de clients SDK¶

Si la métrique sdk-client-count de la JMX augmente continuellement, le connecteur peut présenter une fuite de clients SDK Snowpipe Streaming. Chaque table cible distincte doit avoir un client SDK. Si le nombre total dépasse le nombre de tables distinctes, contactez le Support Snowflake.

Canal SSv1 introuvable lors de la migration des décalages¶

Si le connecteur échoue avec une erreur de canal non trouvé lors de l’utilisation de snowflake.streaming.classic.offset.migration=strict :

• Vérifiez que vous utilisez le même nom de connecteur que votre déploiement v3.

• Vérifiez si snowflake.streaming.classic.offset.migration.include.connector.name correspond à votre paramètre v3 pour snowflake.streaming.channel.name.include.connector.name.

• Basculez vers le mode best_effort si le canal a déjà été nettoyé, ou si vous ajoutez de nouveaux sujets qui n’existaient pas dans la v3.

Doublons après la migration¶

Si vous voyez des enregistrements en double après une migration depuis la v3 :

• Vérifiez que RECORD_METADATA contient des champs de sujet, de partition et de décalage.

• Utilisez la requête de déduplication dans Mise à niveau de v4 vers v3 pour supprimer les doublons.