Kafka Topic Advanced: Konvensi Penamaan Topic Kafka

Konvensi Penamaan Topik Kafka

Dalam Apache Kafka, topik adalah unit dasar untuk mengatur dan menyimpan data. Anda bebas memilih nama topik apa pun, tetapi menetapkan konvensi penamaan yang konsisten di seluruh organisasi sangat penting untuk menjaga organisasi, kejelasan, dan skalabilitas sistem. Konvensi penamaan yang baik memudahkan pengelolaan topik, debugging, dan kolaborasi antar tim. Artikel ini akan menjelaskan pentingnya konvensi penamaan topik Kafka, karakter yang valid, struktur penamaan hierarkis yang umum, serta panduan praktis untuk menerapkannya dengan contoh lengkap menggunakan alat CLI Kafka.

Mengapa Konvensi Penamaan Penting?

• Konsistensi: Nama topik yang konsisten memudahkan tim untuk memahami tujuan dan konteks topik tanpa dokumentasi tambahan.

• Skalabilitas: Dalam klaster dengan ratusan atau ribuan topik, konvensi penamaan yang terstruktur mencegah kekacauan dan mempermudah pencarian.

• Kejelasan: Nama topik yang jelas mengindikasikan data yang disimpan, formatnya, dan tim yang bertanggung jawab.

• Pencegahan Konflik: Konvensi yang baik menghindari masalah seperti tabrakan namespace metrik, yang dapat terjadi jika karakter tertentu (misalnya, titik dan garis bawah) dicampur secara tidak konsisten.

• Kolaborasi: Memudahkan komunikasi antar tim, terutama dalam organisasi besar dengan banyak departemen.

Untuk inspirasi lebih lanjut tentang konvensi penamaan, Anda dapat membaca artikel berikut: How to Paint the Bike Shed: Kafka Topic Naming Conventions.

Karakter yang Valid untuk Nama Topik

Nama topik Kafka hanya boleh menggunakan karakter berikut:

• Alfanumerik ASCII: Huruf (a–z, A–Z) dan angka (0–9).

• Karakter Khusus: Titik (.), garis bawah (_), dan tanda hubung (-).

Peringatan

• Hindari Mencampur Titik dan Garis Bawah: Menggunakan titik (.) dan garis bawah (_) dalam nama topik yang serupa dapat menyebabkan tabrakan namespace metrik di Kafka, yang menghasilkan kesalahan seperti:

  org.apache.kafka.common.errors.InvalidTopicException: Topic 'test.1' collides with existing topics: test_1

  • Solusi: Pilih salah satu pemisah (misalnya, hanya titik atau hanya tanda hubung) dan gunakan secara konsisten di seluruh klaster.

• Panjang Nama: Nama topik sebaiknya tidak terlalu panjang untuk menjaga kejelasan, tetapi Kafka mengizinkan hingga 249 karakter (termasuk pemisah).

• Hindari Karakter Khusus Lain: Karakter seperti spasi, tanda baca lain (misalnya, !, @, #), atau karakter non-ASCII (misalnya, é, ñ) tidak diperbolehkan.

Struktur Penamaan Hierarkis

Struktur penamaan hierarkis adalah praktik umum untuk topik Kafka, terutama di organisasi besar. Struktur ini biasanya mengikuti pola berikut:

<nama_departemen>.<nama_tim>.<nama_dataset>.<format_data>

• nama_departemen: Menunjukkan departemen atau unit bisnis yang memiliki topik (misalnya, finance, marketing).

• nama_tim: Mengidentifikasi tim spesifik dalam departemen yang bertanggung jawab atas topik (misalnya, billing, analytics).

• nama_dataset: Menjelaskan jenis data yang disimpan dalam topik (misalnya, transactions, user_events).

• format_data: Menunjukkan format data untuk memudahkan konsumer memahami cara memproses pesan (misalnya, avro, json, text, protobuf, csv, log).

Contoh Nama Topik

Berikut adalah beberapa contoh nama topik berdasarkan struktur hierarkis:

• finance.billing.transactions.avro: Topik yang menyimpan data transaksi dari tim penagihan di departemen keuangan dalam format Avro.

• marketing.analytics.user_events.json: Topik yang menyimpan peristiwa pengguna dari tim analitik di departemen pemasaran dalam format JSON.

• it.monitoring.server_logs.text: Topik yang menyimpan log server dari tim pemantauan di departemen IT dalam format teks.

Variasi Struktur

Anda dapat menyesuaikan struktur sesuai kebutuhan organisasi, misalnya:

• Sederhana: <nama_dataset>.<format_data> (misalnya, orders.json untuk organisasi kecil).

• Dengan Lingkungan: <lingkungan>.<nama_departemen>.<nama_dataset>.<format_data> (misalnya, prod.finance.transactions.avro untuk lingkungan produksi).

• Dengan Aplikasi: <nama_aplikasi>.<nama_dataset>.<format_data> (misalnya, crm.customers.json untuk data pelanggan dari aplikasi CRM).

Praktik Penamaan Topik

Berikut adalah langkah-langkah praktis untuk menerapkan konvensi penamaan topik Kafka, lengkap dengan contoh pembuatan topik menggunakan alat CLI.

Prasyarat

• Pastikan klaster Kafka berjalan (mode Zookeeper atau KRaft).

• Gunakan ekstensi CLI yang sesuai: .sh untuk Linux/Mac, .bat untuk Windows.

• Pastikan broker Kafka aktif di localhost:9092 (atau alamat lain sesuai konfigurasi Anda).

• Tentukan konvensi penamaan untuk organisasi Anda sebelum membuat topik.

Contoh Kasus Penggunaan

Misalkan Anda bekerja di perusahaan dengan tiga departemen: Keuangan (finance), Pemasaran (marketing), dan IT. Anda ingin membuat topik untuk:

1. Data transaksi penagihan dalam format Avro, dikelola oleh tim penagihan di departemen keuangan.

2. Peristiwa pengguna dalam format JSON, dikelola oleh tim analitik di departemen pemasaran.

3. Log server dalam format teks, dikelola oleh tim pemantauan di departemen IT.

Kami akan menggunakan struktur penamaan: <nama_departemen>.<nama_tim>.<nama_dataset>.<format_data> dengan pemisah titik (.) secara konsisten.

Langkah-langkah Praktis

1. Buat Topik dengan Konvensi Penamaan

Buat tiga topik dengan konfigurasi yang sesuai menggunakan kafka-topics.sh. Kami akan menggunakan 3 partisi dan faktor replikasi 3 untuk ketahanan dan distribusi yang baik.

# Topik untuk transaksi penagihan (finance.billing.transactions.avro)
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic finance.billing.transactions.avro \
--partitions 3 --replication-factor 3 \
--config cleanup.policy=delete --config retention.ms=604800000

# Topik untuk peristiwa pengguna (marketing.analytics.user_events.json)
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic marketing.analytics.user_events.json \
--partitions 3 --replication-factor 3 \
--config cleanup.policy=compact --config min.cleanable.dirty.ratio=0.001 --config segment.ms=5000

# Topik untuk log server (it.monitoring.server_logs.text)
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic it.monitoring.server_logs.text \
--partitions 3 --replication-factor 3 \
--config cleanup.policy=delete --config retention.ms=86400000

Penjelasan Konfigurasi:

• finance.billing.transactions.avro:

  • Menggunakan cleanup.policy=delete dengan retensi 1 minggu (retention.ms=604800000) karena data transaksi perlu disimpan sementara.

• marketing.analytics.user_events.json:

  • Menggunakan cleanup.policy=compact untuk menyimpan hanya peristiwa terbaru per kunci (misalnya, ID pengguna), dengan min.cleanable.dirty.ratio=0.001 dan segment.ms=5000 untuk mempercepat kompaksi.

• it.monitoring.server_logs.text:

  • Menggunakan cleanup.policy=delete dengan retensi 1 hari (retention.ms=86400000) karena log server tidak perlu disimpan lama.

2. Verifikasi Konfigurasi Topik

Periksa konfigurasi topik untuk memastikan semuanya diterapkan dengan benar:

kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic finance.billing.transactions.avro
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic marketing.analytics.user_events.json
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic it.monitoring.server_logs.text

Contoh Keluaran:

Topic: finance.billing.transactions.avro TopicId: XYZ123 PartitionCount: 3 ReplicationFactor: 3 Configs: cleanup.policy=delete,retention.ms=604800000
Topic: finance.billing.transactions.avro Partition: 0 Leader: 1 Replicas: 1,2,3 Isr: 1,2,3
...

Topic: marketing.analytics.user_events.json TopicId: ABC456 PartitionCount: 3 ReplicationFactor: 3 Configs: cleanup.policy=compact,min.cleanable.dirty.ratio=0.001,segment.ms=5000
Topic: marketing.analytics.user_events.json Partition: 0 Leader: 2 Replicas: 2,3,1 Isr: 2,3,1
...

Topic: it.monitoring.server_logs.text TopicId: DEF789 PartitionCount: 3 ReplicationFactor: 3 Configs: cleanup.policy=delete,retention.ms=86400000
Topic: it.monitoring.server_logs.text Partition: 0 Leader: 3 Replicas: 3,1,2 Isr: 3,1,2
...

3. Produksi dan Konsumsi Data (Contoh)

Untuk menguji topik, jalankan produser dan konsumer konsol untuk setiap topik.

a. Topik finance.billing.transactions.avro

Jalankan produser:

kafka-console-producer.sh --bootstrap-server localhost:9092 \
--topic finance.billing.transactions.avro \
--property parse.key=true \
--property key.separator=,

Kirim pesan (misalnya, ID transaksi sebagai kunci, data transaksi sebagai nilai):

tx123,{"amount": 1000, "date": "2025-08-01"}
tx124,{"amount": 2500, "date": "2025-08-01"}

Jalankan konsumer:

kafka-console-consumer.sh --bootstrap-server localhost:9092 \
--topic finance.billing.transactions.avro \
--from-beginning \
--property print.key=true \
--property key.separator=,

b. Topik marketing.analytics.user_events.json

Jalankan produser:

kafka-console-producer.sh --bootstrap-server localhost:9092 \
--topic marketing.analytics.user_events.json \
--property parse.key=true \
--property key.separator=,

Kirim pesan dengan kunci duplikat untuk menguji kompaksi:

user1,{"event": "login", "timestamp": "2025-08-01T10:00:00"}
user2,{"event": "click", "timestamp": "2025-08-01T10:01:00"}
user1,{"event": "logout", "timestamp": "2025-08-01T10:02:00"}

Jalankan konsumer untuk melihat hasil kompaksi:

kafka-console-consumer.sh --bootstrap-server localhost:9092 \
--topic marketing.analytics.user_events.json \
--from-beginning \
--property print.key=true \
--property key.separator=,

Keluaran setelah kompaksi (hanya nilai terbaru per kunci):

user1,{"event": "logout", "timestamp": "2025-08-01T10:02:00"}
user2,{"event": "click", "timestamp": "2025-08-01T10:01:00"}

c. Topik it.monitoring.server_logs.text

Jalankan produser:

kafka-console-producer.sh --bootstrap-server localhost:9092 \
--topic it.monitoring.server_logs.text

Kirim pesan log:

2025-08-01T10:00:00 Server1: CPU usage 75%
2025-08-01T10:00:01 Server2: Disk full

Jalankan konsumer:

kafka-console-consumer.sh --bootstrap-server localhost:9092 \
--topic it.monitoring.server_logs.text \
--from-beginning

4. Pantau dan Kelola Topik

• Pantau Metrik: Gunakan alat seperti Kafka Manager atau metrik JMX untuk memantau metrik seperti BytesInPerSec, BytesOutPerSec, dan UnderReplicatedPartitions.

• Periksa Direktori Log: Verifikasi struktur direktori topik di log.dirs (misalnya, /tmp/kafka-logs):

  ls -l /tmp/kafka-logs/

  Pastikan nama topik muncul sebagai subdirektori (misalnya, finance.billing.transactions.avro-0).

Praktik Terbaik

1. Tetapkan Konvensi Penamaan Organisasi:

   • Dokumentasikan konvensi penamaan (misalnya, <nama_departemen>.<nama_tim>.<nama_dataset>.<format_data>) dan terapkan secara konsisten di seluruh tim.

   • Contoh dokumen konvensi:

     Konvensi Penamaan Topik Kafka
     - Struktur: <nama_departemen>.<nama_tim>.<nama_dataset>.<format_data>
     - Pemisah: Titik (.)
     - Format Data: avro, json, text, protobuf, csv, log
     - Contoh: finance.billing.transactions.avro

2. Gunakan Pemisah Konsisten:

   • Pilih titik (.) atau tanda hubung (-) sebagai pemisah dan hindari mencampur dengan garis bawah (_) untuk mencegah tabrakan namespace metrik.

3. Sertakan Format Data:

   • Tambahkan sufiks format data (misalnya, .avro, .json) untuk memberikan petunjuk kepada konsumer tentang cara memproses pesan.

4. Gunakan Nama Deskriptif:

   • Pastikan nama topik jelas dan mencerminkan data yang disimpan, seperti finance.billing.transactions alih-alih topic1.

5. Sertakan Lingkungan (Opsional):

   • Untuk lingkungan produksi dan pengujian, pertimbangkan menambahkan prefiks lingkungan (misalnya, prod.finance.billing.transactions.avro).

6. Uji Konvensi Penamaan:

   • Uji pembuatan topik di lingkungan non-produksi untuk memastikan nama tidak menyebabkan kesalahan atau konflik.

7. Pantau dan Audit Topik:

   • Secara berkala periksa semua topik untuk memastikan kepatuhan terhadap konvensi penamaan:

     kafka-topics.sh --bootstrap-server localhost:9092 --list

8. Pertimbangkan Mode KRaft:

   • Dalam mode KRaft (Kafka tanpa Zookeeper), manajemen topik lebih efisien, tetapi konvensi penamaan tetap penting untuk organisasi dan kejelasan.

Penjelasan Tambahan

Hubungan dengan Operasi Kafka

• Metrik dan Pemantauan: Nama topik yang konsisten memudahkan konfigurasi alat pemantauan seperti Prometheus atau Grafana, karena metrik Kafka menggunakan nama topik sebagai bagian dari namespace.

• Manajemen Topik: Konvensi penamaan yang terstruktur mempermudah operasi seperti menghapus, memodifikasi, atau memindahkan topik di klaster besar.

• Integrasi dengan Schema Registry: Jika menggunakan format seperti Avro, nama topik dengan sufiks .avro membantu mengaitkan topik dengan skema di Confluent Schema Registry atau sistem serupa.

Pemecahan Masalah

Jika terjadi kesalahan seperti InvalidTopicException:

• Periksa Nama Topik:

  • Pastikan nama hanya menggunakan karakter valid (alfanumerik, ., _, -).

  • Hindari nama yang mirip dengan pemisah berbeda (misalnya, test.1 vs. test_1).

• Periksa Konflik:

  • Gunakan perintah berikut untuk melihat daftar topik:

    kafka-topics.sh --bootstrap-server localhost:9092 --list

  • Jika ada konflik, hapus topik yang bermasalah:

    kafka-topics.sh --bootstrap-server localhost:9092 --delete --topic test.1

Jika topik tidak muncul seperti yang diharapkan:

• Periksa konfigurasi broker di server.properties untuk memastikan log.dirs dapat diakses.

• Verifikasi status topik:

  kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic finance.billing.transactions.avro

Kesimpulan

Konvensi penamaan topik Kafka adalah praktik penting untuk menjaga konsistensi, kejelasan, dan skalabilitas dalam klaster Kafka. Dengan menggunakan struktur hierarkis seperti <nama_departemen>.<nama_tim>.<nama_dataset>.<format_data> dan karakter valid seperti titik atau tanda hubung, Anda dapat membuat nama topik yang informatif dan mudah dikelola. Contoh praktis menunjukkan cara membuat topik dengan konfigurasi yang sesuai untuk kasus penggunaan nyata, seperti transaksi keuangan, peristiwa pengguna, dan log server. Dengan mengikuti praktik terbaik seperti mendokumentasikan konvensi, menggunakan pemisah konsisten, dan memantau topik, Anda dapat memastikan pengelolaan klaster Kafka yang efisien dan bebas masalah.