Verständnis der Kafka-Befehlszeilen-Tools: CLI-Referenzhandbuch

Die Befehlszeilen-Tools von Kafka sind der schnellste Weg, um grundlegende betriebliche Fragen zu beantworten: Existiert dieses Thema, welcher Broker führt diese Partition, was befindet sich in dem Thema, warum hinkt diese Verbrauchergruppe hinterher und kann dieser Client sich beim Cluster authentifizieren? Sie werden nicht für jede Aufgabe benötigt, und die meisten Produktionsänderungen sollten weiterhin automatisiert erfolgen, aber bei einem fehlgeschlagenen Deployment oder einer nächtlichen Datenfrage ist die CLI oft der kürzeste Weg zu Fakten.

Die folgenden Beispiele gehen davon aus, dass die Skripte in Ihrem PATH sind. In vielen Installationen befinden sie sich im bin/-Verzeichnis von Kafka, sodass derselbe Befehl auch als bin/kafka-topics.sh ausgeführt werden kann. Für gesicherte Cluster benötigen die meisten Befehle auch --command-config client.properties, wobei diese Datei SASL-, SSL- und andere Client-Einstellungen enthält.

Kern-Kafka-CLI-Tools

Kafka-Distributionen enthalten typischerweise ein bin/-Verzeichnis mit verschiedenen Skripten und ausführbaren Dateien. Wir konzentrieren uns auf die am häufigsten verwendeten für eine effektive Kafka-Verwaltung.

1. kafka-topics.sh

Dies ist wohl das am häufigsten verwendete Befehlszeilen-Tool. Es ermöglicht Ihnen, Kafka-Themen zu erstellen, aufzulisten, zu beschreiben, zu löschen, zu ändern und zu verwalten. Die Themenverwaltung ist grundlegend für die Organisation von Datenströmen in Kafka.

Häufige Unterbefehle und Argumente:

• --create: Erstellt ein neues Thema.
• --list: Listet alle Themen im Cluster auf.
• --describe: Liefert detaillierte Informationen zu bestimmten Themen.
• --delete: Löscht ein oder mehrere Themen.
• --alter: Ändert die Konfiguration eines vorhandenen Themas.
• --topic <topic_name>: Gibt den Themennamen an.
• --partitions <num_partitions>: Legt die Anzahl der Partitionen für ein Thema fest (wird mit --create verwendet).
• --replication-factor <factor>: Legt den Replikationsfaktor für ein Thema fest (wird mit --create verwendet).
• --bootstrap-server <host:port>: Gibt den Kafka-Broker an, zu dem eine Verbindung hergestellt werden soll.

Beispiele:

• Erstellen Sie ein Thema namens my_topic mit 3 Partitionen und einem Replikationsfaktor von 2:

  kafka-topics.sh --create --topic my_topic --partitions 3 --replication-factor 2 --bootstrap-server kafka-broker-1:9092,kafka-broker-2:9092
  

• Listen Sie alle Themen im Cluster auf:

  kafka-topics.sh --list --bootstrap-server kafka-broker-1:9092
  

• Beschreiben Sie ein Thema namens my_topic:

  kafka-topics.sh --describe --topic my_topic --bootstrap-server kafka-broker-1:9092
  

  Dies zeigt Details wie Partitionen, Leader, Replikate und ISRs (In-Sync Replicas) an.

• Löschen Sie ein Thema namens old_topic:

  kafka-topics.sh --delete --topic old_topic --bootstrap-server kafka-broker-1:9092
  

  Hinweis: Das Löschen von Themen muss in den Kafka-Broker-Konfigurationen aktiviert sein (delete.topic.enable=true).

2. kafka-console-producer.sh

Dieses Tool ermöglicht es Ihnen, Nachrichten von der Standardeingabe an ein Kafka-Thema zu senden. Es ist unverzichtbar zum Testen von Produzenten, zum Einspielen von Beispieldaten oder zum manuellen Veröffentlichen von Nachrichten.

Häufige Argumente:

• --topic <topic_name>: Gibt das Zielthema an.
• --bootstrap-server <host:port>: Gibt den Kafka-Broker an, zu dem eine Verbindung hergestellt werden soll.
• --property <key>=<value>: Ermöglicht das Setzen von Produzenteneigenschaften (z.B. key.serializer, value.serializer).
• --producer-property <key>=<value>: Ähnlich wie --property, aber speziell für produzentenseitige Konfigurationen.

Beispiele:

• Senden Sie Nachrichten an my_topic:

  kafka-console-producer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092
  

  Nach der Ausführung können Sie Nachrichten Zeile für Zeile eingeben. Drücken Sie Strg+C, um zu beenden.

• Senden Sie Nachrichten mit Schlüsseln (JSON-Format):

  kafka-console-producer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092 --property parse.key=true --property key.separator=':'
  

  Jetzt können Sie key:value-Paare eingeben, und Kafka sendet sie mit dem angegebenen Schlüssel.

3. kafka-console-consumer.sh

Dieses Tool abonniert ein oder mehrere Kafka-Themen und gibt die empfangenen Nachrichten auf der Standardausgabe aus. Es ist unverzichtbar zum Testen von Verbrauchern, zum Überprüfen von Daten in Themen und zum Debuggen von Produzenten-/Verbraucheranwendungen.

Häufige Argumente:

• --topic <topic_name>: Gibt das/die Thema/Themen an, von dem/denen konsumiert werden soll.
• --bootstrap-server <host:port>: Gibt den Kafka-Broker an, zu dem eine Verbindung hergestellt werden soll.
• --group-id <group_id>: Gibt die Verbrauchergruppen-ID an. Dies ist wichtig für die Verwaltung von Offsets und ermöglicht es mehreren Verbrauchern, die Konsumlast zu teilen.
• --from-beginning: Liest Nachrichten vom Anfang des Themenprotokolls.
• --offset <offset>: Beginnt mit dem Konsumieren ab einem bestimmten Offset.
• --partition <partition_id>: Konsumiert von einer bestimmten Partition.
• --property <key>=<value>: Ermöglicht das Setzen von Verbrauchereigenschaften (z.B. value.deserializer).

Beispiele:

• Konsumieren Sie alle Nachrichten von my_topic:

  kafka-console-consumer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092
  

• Konsumieren Sie Nachrichten vom Anfang von my_topic für die Verbrauchergruppe my_group:

  kafka-console-consumer.sh --topic my_topic --group-id my_group --from-beginning --bootstrap-server kafka-broker-1:9092
  

• Konsumieren Sie Nachrichten mit gedruckten Offsets und Schlüsseln:

  kafka-console-consumer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092 --property print.key=true --property key.separator="\t" --property print.offset=true --property print.headers=true
  

4. kafka-consumer-groups.sh

Dieses Tool wird verwendet, um Verbrauchergruppen zu verwalten und zu überprüfen. Es ist entscheidend für das Verständnis von Verbraucherverzögerungen, die Neuzuweisung von Partitionen und die Fehlerbehebung bei Konsumproblemen.

Häufige Unterbefehle und Argumente:

• --list: Listet alle Verbrauchergruppen im Cluster auf.
• --describe: Liefert Details zu bestimmten Verbrauchergruppen, einschließlich Verzögerung.
• --bootstrap-server <host:port>: Gibt den Kafka-Broker an, zu dem eine Verbindung hergestellt werden soll.
• --group <group_id>: Gibt die Verbrauchergruppen-ID an.
• --reset-offsets: Setzt Offsets für eine Verbrauchergruppe zurück.
• --topic <topic_name>: Gibt das Thema für den Offset-Reset an.
• --to-earliest: Setzt Offsets auf die früheste verfügbare Nachricht zurück.
• --to-latest: Setzt Offsets auf die neueste verfügbare Nachricht zurück.
• --execute: Führt den Offset-Reset-Vorgang aus.

Beispiele:

• Listen Sie alle Verbrauchergruppen auf:

  kafka-consumer-groups.sh --list --bootstrap-server kafka-broker-1:9092
  

• Beschreiben Sie eine Verbrauchergruppe my_group und zeigen Sie ihre Verzögerung an:

  kafka-consumer-groups.sh --describe --group my_group --bootstrap-server kafka-broker-1:9092
  

  Die Ausgabe zeigt das Thema, die Partition, den aktuellen Offset, den Log-End-Offset und die Verzögerung.

• Setzen Sie Offsets für my_group auf my_topic auf die früheste verfügbare Nachricht zurück:

  kafka-consumer-groups.sh --group my_group --topic my_topic --reset-offsets --to-earliest --execute --bootstrap-server kafka-broker-1:9092
  

  Verwenden Sie diesen Befehl mit Vorsicht, da er beeinflusst, wo Verbraucher zu lesen beginnen.

5. kafka-log-dirs.sh

Dieses Tool hilft bei der Überprüfung der Log-Verzeichnisse auf Kafka-Brokern. Es kann nützlich sein, um die Festplattennutzung zu verstehen und Themendaten zu lokalisieren.

Häufige Argumente:

• --bootstrap-server <host:port>: Gibt den Kafka-Broker an, zu dem eine Verbindung hergestellt werden soll.
• --topic <topic_name>: Filtert die Ausgabe, um Verzeichnisse für ein bestimmtes Thema anzuzeigen.

Beispiele:

• Listen Sie Log-Verzeichnisse auf einem Broker auf:

  kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092
  

• Zeigen Sie Log-Verzeichnisse für ein bestimmtes Thema an:

  kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092 --topic my_topic
  

6. kafka-preferred-replica-election.sh

Dieses Skript initiiert bevorzugte Replikatwahlen für Themen. Ein bevorzugtes Replikat ist der Broker, der basierend auf seinem Replikationsfaktor als Leader für eine Partition ausgewählt wird. Wenn ein Broker ausfällt und ein nicht bevorzugtes Replikat zum Leader wird, kann dieses Tool verwendet werden, um die Führung zurück zum bevorzugten Replikat zu verschieben.

Häufige Argumente:

• --topic <topic_name>: Gibt das Thema an, für das bevorzugte Replikate gewählt werden sollen.
• --broker-list <broker_id1,broker_id2,...>: Gibt eine durch Kommas getrennte Liste von Broker-IDs an.
• --bootstrap-server <host:port>: Gibt den Kafka-Broker an, zu dem eine Verbindung hergestellt werden soll.

Beispiele:

• Wählen Sie bevorzugte Replikate für my_topic:

  kafka-preferred-replica-election.sh --topic my_topic --bootstrap-server kafka-broker-1:9092
  

• Wählen Sie bevorzugte Replikate für mehrere Themen:

  kafka-preferred-replica-election.sh --topic topic1,topic2 --bootstrap-server kafka-broker-1:9092
  

Wichtige Überlegungen und bewährte Verfahren

• --bootstrap-server ist entscheidend: Stellen Sie immer sicher, dass Sie das richtige --bootstrap-server-Argument angeben, um eine Verbindung zu Ihrem Kafka-Cluster herzustellen. Dies ist normalerweise eine durch Kommas getrennte Liste von host:port für Ihre Broker.
• Umgebung: Diese Befehle befinden sich normalerweise im bin/-Verzeichnis Ihrer Kafka-Installation. Sie müssen zu diesem Verzeichnis navigieren oder sicherstellen, dass das bin-Verzeichnis von Kafka in Ihrem System-PATH ist.
• Berechtigungen: Stellen Sie sicher, dass der Benutzer, der diese Befehle ausführt, den erforderlichen Netzwerkzugriff hat, um die Kafka-Broker zu erreichen.
• Konfiguration: Viele CLI-Tools können Kafka-Client-Konfigurationen über --property- oder --producer-property/--consumer-property-Argumente akzeptieren. Dies ist nützlich, um Standard-Serialisierer/Deserialisierer zu überschreiben oder andere spezifische Client-Konfigurationen festzulegen.
• Sicherheit: Für sichere Kafka-Cluster (z.B. mit SSL/TLS oder SASL-Authentifizierung) müssen Sie diesen Tools zusätzliche sicherheitsrelevante Argumente (wie --command-config, das auf eine Client-Eigenschaftendatei verweist) übergeben.
• Themenlöschung: Denken Sie daran, dass das Löschen von Themen ein sensibler Vorgang ist und explizit in der server.properties-Datei des Kafka-Brokers mit delete.topic.enable=true aktiviert werden muss.

Ein sicherer Weg, die CLI in der Produktion zu verwenden

Verwenden Sie die CLI zuerst als Inspektionswerkzeug und dann als Mutationswerkzeug. --list, --describe und kurze Konsolenlesevorgänge sind risikoarm. --delete, --alter, Partitionserhöhungen und Offset-Resets ändern das Clusterverhalten und sollten, wann immer möglich, denselben Überprüfungsweg wie Anwendungsänderungen durchlaufen.

Eine praktische Produktionssitzung beginnt normalerweise mit einer Client-Konfigurationsdatei:

cat client.properties
# security.protocol=SASL_SSL
# sasl.mechanism=SCRAM-SHA-512
# sasl.jaas.config=...

Dann enthält jeder Befehl sie:

kafka-topics.sh --bootstrap-server kafka-1:9093 --command-config client.properties --describe --topic orders

Für Konsolenverbraucher vermeiden Sie es, versehentlich einer echten Anwendungsgruppe beizutreten. Verwenden Sie eine temporäre Gruppen-ID, wenn Sie Daten überprüfen, und verwenden Sie --max-messages, damit der Befehl beendet wird:

kafka-console-consumer.sh \
  --bootstrap-server kafka-1:9093 \
  --command-config client.properties \
  --topic orders \
  --group debug-orders-$(date +%s) \
  --from-beginning \
  --max-messages 5 \
  --property print.key=true \
  --property print.offset=true

Diese kleine Gewohnheit verhindert, dass ein Debug-Befehl Partitionen von einem Live-Dienst stiehlt. Sie hinterlässt auch eine sauberere Prüfspur, da der Gruppenname die Absicht offensichtlich macht.

Die CLI ist am besten, wenn sie langweilig ist: ein Befehl zum Überprüfen, ein Befehl zum Bestätigen und eine klare Aufzeichnung jedes Befehls, der den Zustand ändert.

Alltägliche Rezepte zur Fehlerbehebung

Wenn ein Produzent sagt, dass er erfolgreich schreibt, aber das Verbraucherteam nichts sieht, beginnen Sie mit dem Thema:

kafka-topics.sh --bootstrap-server kafka-1:9092 --describe --topic orders

Bestätigen Sie den Themennamen, die Partitionsanzahl, die Leader-Verfügbarkeit und die synchronen Replikate. Ein Tippfehler in einem Themennamen kann genau wie eine defekte Pipeline aussehen, wenn die automatische Themenerstellung in einem Entwicklungschuster aktiviert ist. In der Produktion weisen Themen mit Offline-Partitionen oder schrumpfenden ISRs auf ein Broker- oder Replikationsproblem hin, bevor sie auf Anwendungscode hinweisen.

Lesen Sie als nächstes eine kleine Stichprobe mit einer temporären Gruppe:

kafka-console-consumer.sh \
  --bootstrap-server kafka-1:9092 \
  --topic orders \
  --group debug-orders-$(date +%s) \
  --max-messages 10 \
  --property print.key=true \
  --property print.timestamp=true \
  --property print.offset=true

Wenn dort Datensätze erscheinen, hat Kafka die Daten, und das Problem ist wahrscheinlich die eigentliche Verbrauchergruppe, ihre Offsets, ihre Abonnements oder ihre Verarbeitungslogik. Wenn keine Datensätze erscheinen, überprüfen Sie das Produzententhema, die Serialisierer, die Authentifizierung und ob der Produzent in einen anderen Cluster schreibt.

Bei Verzögerungsfragen gehen Sie direkt zur Gruppe:

kafka-consumer-groups.sh --bootstrap-server kafka-1:9092 --describe --group orders-writer

Halten Sie nicht bei der Gesamtverzögerung an. Vergleichen Sie Partitionen. Eine einzelne Partition mit großer Verzögerung bedeutet ein anderes Problem als jede Partition mit moderater Verzögerung. Eine einzelne Partitionsverzögerung bedeutet oft eine Schlüsselschiefe oder eine schlechte Verbraucherzuweisung. Eine gleichmäßige Verzögerung bedeutet normalerweise, dass die gesamte Anwendung langsamer ist als die Eingaberate.

Für "Was hat sich geändert?"-Fragen überprüfen Sie die Themenkonfiguration:

kafka-configs.sh \
  --bootstrap-server kafka-1:9092 \
  --entity-type topics \
  --entity-name orders \
  --describe

Hier fangen Sie Aufbewahrungsänderungen, Überraschungen bei der Bereinigungsrichtlinie, Komprimierungsüberschreibungen und Nachrichtengrößeneinstellungen, die von den Annahmen des Dienstes abweichen.

Die CLI-Ausgabe ist kein Ersatz für die Überwachung, aber sie ist hervorragend geeignet, um Unsicherheiten zu reduzieren. In einem echten Vorfall können ein paar Befehlsausgaben, die in das Ticket eingefügt werden, allen die Debatte ersparen, ob das Thema existiert, ob Datensätze vorhanden sind und ob die Gruppe tatsächlich läuft.

Befehle, die mit Vorsicht zu behandeln sind

Einige Kafka-CLI-Befehle sehen harmlos aus, weil sie kurz sind. Sie sind nicht harmlos.

kafka-topics.sh --alter --partitions erhöht nur die Partitionsanzahl; es verkleinert sie nicht später, wenn Sie die Änderung bereuen. Mehr Partitionen können die Verbraucherparallelität verbessern, aber sie können auch die Schlüsselverteilung für neue Datensätze ändern und Annahmen in Systemen brechen, die erwarteten, dass alle Ereignisse für einen Schlüsselbereich in einer kleineren Anzahl von Partitionen landen.

kafka-consumer-groups.sh --reset-offsets --execute ändert, wo eine Gruppe als nächstes liest. Verwenden Sie zuerst --dry-run, stoppen Sie die betroffenen Verbraucher und zeichnen Sie die alten Offsets auf. Ein Zurücksetzen auf den frühesten Stand kann Daten in Systeme wiedergeben, die nicht idempotent sind. Ein Zurücksetzen auf den neuesten Stand kann Daten überspringen, die das Geschäft noch zu verarbeiten erwartet.

kafka-topics.sh --delete hängt von der Clusterkonfiguration und -richtlinie ab, aber wenn das Löschen erlaubt ist, sollte es wie das Löschen einer Datenbanktabelle behandelt werden. Überprüfen Sie den Cluster, überprüfen Sie das Thema und überprüfen Sie, ob eine andere Umgebung dieselbe Namenskonvention verwendet. Ein Produktionsthema namens orders-test ist immer noch Produktion, wenn reale Dienste davon abhängen.

Für wiederholbare Vorgänge setzen Sie den Befehl in ein Runbook oder Skript mit expliziten Variablen für Cluster, Thema, Gruppe und Befehlskonfiguration. Die CLI ist großartig für Untersuchungen, aber Produktionsmutationen sollten langweilig, überprüft und leicht zu auditieren sein.