Problembehandlung eines Snowflake Connector for Kafka¶

Kanal meldet eine Erhöhung von rows_error_count¶

Wenn der Snowpipe Streaming-Kanal ansteigende rows_error_count meldet, hängt das Verhalten des Konnektors von der errors.tolerance-Einstellung ab:

• Mit errors.tolerance=none (Standard) scheitert die Konnektoraufgabe mit ERROR_5030.

• Mit errors.tolerance=all fährt der Konnektor fort, protokolliert aber die Fehleranzahl.

Zur Untersuchung:

1. Überprüfen Sie die Fehlertabelle, die mit Ihrer Zieltabelle verbunden ist, um die fehlerhaften Datensätze zu identifizieren. Weitere Informationen dazu finden Sie unter Fehlerbehandlung bei der leistungsstarken Snowpipe Streaming-Architektur.

2. Verwenden Sie die unter Metadaten-Offsets zum Erkennen und Wiederherstellen von Fehlern verwenden beschriebene Lückensuche-Technik mit Kafka-Offset-Informationen aus der RECORD_METADATA-Spalte

3. Überprüfen Sie die Konnektorprotokolle auf Fehlerdetails (aktivieren Sie errors.log.enable=true für ausführliche Protokollierung).

Konnektoraufgabe schlägt mit ERROR_5030 fehl.¶

ERROR_5030 zeigt an, dass der Konnektor einen Datenaufnahmefehler festgestellt hat. Zu den häufigsten Ursachen gehören:

• Datentypen zwischen dem Kafka-Datensatz und dem Schema der Zieltabelle stimmen nicht überein.

• Eine vom Benutzer erstellte Pipe existiert, während snowflake.validation=client_side konfiguriert ist. Die clientseitige Validierung funktioniert nur mit der Standard-Pipe.

• Schemaänderungen in den Kafka-Datensätzen, die nicht automatisch weiterentwickelt werden können.

Zur Behebung:

1. Überprüfen Sie die Fehlermeldung und die Protokolle des Konnektors auf die spezifische Ursache.

2. Wenn Sie die clientseitige Validierung mit einer benutzerdefinierten Pipe verwenden, wechseln Sie zu snowflake.validation=server_side oder entfernen Sie die benutzerdefinierte Pipe.

3. Korrigieren Sie die Daten im Kafka-Quellthema, oder passen Sie das Schema der Zieltabelle an.

Probleme bei der Schemaentwicklung¶

Bei der serverseitigen Validierung kann die Schemaentwicklung nicht immer den richtigen Datentyp ermitteln. So kann es zum Beispiel keine binären Spalten ableiten und kann eine Zeichenfolge wie "2026-04-13" als DATE anstelle von TEXT interpretieren.

Wenn die Schemaentwicklung unerwartete Spaltentypen erzeugt:

• Verwenden Sie clientseitige Validierung (snowflake.validation=client_side) zur besseren Typ-Inferenz.

• Erstellen Sie vorab die Tabelle mit dem korrekten Schema, bevor Sie den Konnektor starten.

Authentifizierungsfehler¶

Der v4-Konnektor unterstützt nur die Authentifizierung mit Schlüsselpaaren. Häufige Probleme bei der Authentifizierung:

• Ungültiger privater Schlüssel: Überprüfen Sie, ob der snowflake.private.key-Wert ein gültiger Base64-kodierter privater PKCS #8-Schlüssel ist.

• Schlüsselpassphrase: Wenn Ihr Schlüssel verschlüsselt ist, stellen Sie snowflake.private.key.passphrase auf die korrekte Passphrase ein.

• Berechtigungen von Rollen Überprüfen Sie, ob die in snowflake.role.name angegebene Rolle über die erforderlichen Berechtigungen verfügt. Weitere Informationen dazu finden Sie unter Snowflake Connector for Kafka: Snowflake konfigurieren.

Autorisierungsfehler¶

Wenn der Konnektor auf Autorisierungsfehler von Snowflake stößt, hängt das Verhalten von der enable.task.fail.on.authorization.errors-Einstellung ab:

• Mit enable.task.fail.on.authorization.errors=false (Standard) versucht der Konnektor es erneut.

• Mit enable.task.fail.on.authorization.errors=true schlägt die Konnektor-Aufgabe sofort fehl.

Nicht unterstützter Konverter mit Schematisierung¶

Wenn snowflake.enable.schematization=true (der Standardwert), werden StringConverter und``ByteArrayConverter`` nicht als Wertkonverter unterstützt. Verwenden Sie stattdessen strukturierte Konverter:

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

• io.confluent.connect.avro.AvroConverter

• io.confluent.connect.protobuf.ProtobufConverter

Die Konfigurationseigenschaften von v3 wurden entfernt¶

Wenn Sie Fehlermeldungen zu nicht erkannten Konfigurationseigenschaften erhalten, prüfen Sie, ob Sie Eigenschaften verwenden, die in v4 entfernt wurden. Siehe Migration vom Kafka-Konnektor v3 auf v4 für eine vollständige Liste der entfernten Konfigurationen.

Fehler des Kompatibilitätsvalidators beim Start¶

Wenn der Konnektor beim Start mit Fehlern über fehlende oder inkompatible Konfigurationswerte fehlschlägt, überprüft der Kompatibilitätsvalidator (snowflake.streaming.validate.compatibility.with.classic) Ihre Konfiguration anhand der Migrationsanforderungen von v3.

• Für Neuinstallationen: Legen Sie snowflake.streaming.validate.compatibility.with.classic=false fest, um die Prüfung zu überspringen.

• Für Migrationen von v3: Legen Sie alle erforderlichen Kompatibilitätseigenschaften explizit fest. Siehe snowflake.streaming.validate.compatibility.with.classic für die vollständige Liste.

Datenaufnahmeverzögerung nimmt zu¶

Wenn die Lücke latest-consumer-offset minus persisted-in-snowflake-offset größer wird (sichtbar durch JMX-Kennzahlen) fällt der Konnektor zurück.

Zur Behebung:

• Aufgaben erhöhen: Legen Sie tasks.max näher an der Gesamtzahl der Kafka-Partitionen fest. Die optimale Leistung ist normalerweise 2 Aufgaben pro CPU-Kern für den Kafka Connect-Cluster.

• Rückdruck prüfen: Wenn die backpressure-rewind-count-Kennzahl steigt, ist das Snowpipe Streaming-SDK ausgelastet. Ziehen Sie in Erwägung, Ihr Kafka Connect-Cluster horizontal zu skalieren.

• JVM-Speicher überprüfen: Begrenzen Sie JVM-Heap auf etwa 50 % des verfügbaren Arbeitsspeichers. Die auf Rust basierende Snowpipe Streaming-SDK verwendet Off-Heap-Speicher für die Pufferung, welcher nicht von der JVM verwaltet wird.

Tabellen- und Pipe-Caching¶

Der Konnektor speichert Überprüfungen auf das Vorhandensein von Tabellen und Pipes im Cache, um Datenbankabfragen zu reduzieren. Wenn Sie Probleme damit haben, dass der Konnektor neu erstellte Tabellen oder Pipes nicht erkennt, passen Sie die Cache-Ablaufzeit an:

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

Anhaltende Wiederherstellung des Kanals¶

Gelegentliche Wiederherstellungen des Kanals sind normal. Wenn jedoch die channel-recovery-count-Kennzahl kontinuierlich steigt, kann dies Folgendes anzeigen:

• Schemaänderungen in der Zieltabelle, die mit dem zwischengespeicherten Schema des Konnektors in Konflikt stehen.

• Berechtigungsänderungen, die sich auf die Rolle des Konnektors auswirken.

• Netzwerkinstabilität zwischen dem Kafka Connect-Cluster und Snowflake.

Überprüfen Sie die Konnektorprotokolle auf bestimmte Gründe für die Wiederherstellung.

SDK-Client-Leck¶

Wenn die sdk-client-count JMX-Kennzahl kontinuierlich steigt, lässt der Konnektor möglicherweise Snowpipe Streaming-SDK-Clients durchsickern. Jede einzelne Zieltabelle sollte einen SDK-Client haben. Falls die Anzahl die Zahl der eindeutigen Tabellen überschreitet, kontaktieren Sie bitte den Snowflake-Support.

SSv1-Kanal während Offset-Migration nicht gefunden¶

Wenn der Konnektor bei Verwendung von snowflake.streaming.classic.offset.migration=strict mit einem „Kanal nicht gefunden“-Fehler fehlschlägt:

• Vergewissern Sie sich, dass Sie denselben Konnektornamen wie Ihre v3-Bereitstellung verwenden.

• Prüfen Sie, ob snowflake.streaming.classic.offset.migration.include.connector.name mit Ihrer v3-Einstellung für snowflake.streaming.channel.name.include.connector.name übereinstimmt.

• Wechseln Sie in den best_effort-Modus, wenn der Kanal bereits bereinigt wurde oder wenn Sie neue Themen hinzufügen, die in v3 nicht existierten.

Duplikate nach der Migration¶

Wenn Sie nach der Migration von v3 doppelte Datensätze sehen:

• Überprüfen Sie, ob RECORD_METADATA Themen-, Partitions- und Offsetfelder enthält.

• Verwenden Sie die Abfrage zur Deduplizierung in:ref:label-downgrade-v4-to-v3 zum Entfernen von Duplikaten.