کار با خط فرمان در تولید و مصرف پیام‌ها

دوره مبانی مهندسی داده جلسه ۴ : شروع کار با آپاچی کافکا – نسخه ۴ کار با خط فرمان در تولید و مصرف پیام‌ها

اگرچه امروز ابزارهای گرافیکی بسیاری مانند Kafka UI، Redpanda Console، AKHQ، Conduktor و Offset Explorer برای مدیریت و مشاهده داده‌ها وجود دارد، اما تجربه عملی نشان می‌دهد که در بسیاری از موارد—خصوصاً هنگام کار روی سرورها، محیط‌های Production یا عیب‌یابی لحظه‌ای—اتکا به ابزارهای خط فرمان ضروری و حتی سریع‌تر است. به همین دلیل آشنایی با ابزارهای CLI کافکا یکی از مهارت‌های پایه‌ای هر مهندس داده، DevOps و Backend محسوب می‌شود.

در این بخش با ابزارهای CLI، محل قرارگیری آن‌ها، پارامترهای مهم و سناریوهای واقعی کار با Kafka آشنا می‌شویم.

۱. محل قرارگیری ابزارهای CLI در Kafka

پس از دانلود و Extract کردن Kafka، تمام ابزارهای خط فرمان در مسیر زیر قرار می‌گیرند:

kafka_2.13-4.0.0/bin/

در سیستم‌های ویندوز، نسخه‌های BAT نیز وجود دارد:

kafka_2.13-4.0.0/bin/windows/

این ابزارها درواقع اسکریپت‌هایی هستند که یک کلاس Java را اجرا می‌کنند و هرکدام وظیفه مشخصی در مدیریت و بررسی کلاستر دارند.

۲. فهرست ابزارهای مهم CLI در کافکا

در نسخه ۴ Kafka مهم‌ترین ابزارها عبارت‌اند از:

ابزار	توضیح
`kafka-topics.sh`	ایجاد، حذف، لیست‌کردن، و تغییر تنظیمات Topic
`kafka-console-producer.sh`	ارسال پیام (Producer) از طریق CLI
`kafka-console-consumer.sh`	دریافت پیام (Consumer) از طریق CLI
`kafka-consumer-groups.sh`	مدیریت و مشاهده وضعیت Consumer Groupها
`kafka-configs.sh`	مدیریت تنظیمات کاربران، بروکرها و تاپیک‌ها
`kafka-storage.sh`	فرمت و مقداردهی اولیه Storage برای KRaft
`kafka-server-start.sh`	اجرای بروکر کافکا
`kafka-server-stop.sh`	توقف بروکر
`kafka-dump-log.sh`	مشاهده محتوای Segmentها (برای Debug عمیق)

این ابزارها در کنار هم، تقریباً تمام نیازهای عملیاتی شما در کار با Kafka را پوشش می‌دهند.

۳. پارامتر کلیدی: `--bootstrap-server`

مهم‌ترین پارامتری که تقریباً در تمام فرمان‌ها استفاده می‌شود:

--bootstrap-server localhost:9092

این پارامتر به ابزار CLI می‌گوید برای ارتباط با Kafka از کدام آدرس استفاده کند.
نکته مهم:

این پارامتر فقط برای «شروع ارتباط» استفاده می‌شود.
ابزار پس از اتصال، باقی نودهای کلاستر را از Kafka دریافت می‌کند.

از نسخه ۲.۴ به بعد، پارامتر قدیمی --zookeeper استفاده نمی‌شود و همه چیز با --bootstrap-server انجام می‌گیرد.

۴. سناریوهای واقعی کار با Kafka از طریق خط فرمان

در ادامه مجموعه‌ای از سناریوهای واقعی آورده شده است که در دنیای Production کاربرد روزانه دارند.

سناریو ۱: ایجاد یک Topic جدید

فرض کنید می‌خواهیم یک Topic به نام user-signup با ۶ پارتیشن بسازیم:

./bin/kafka-topics.sh \
  --create \
  --topic user-signup \
  --partitions 6 \
  --replication-factor 1 \
  --bootstrap-server localhost:9092

برای بررسی تاپیک:

./bin/kafka-topics.sh \
  --describe \
  --topic user-signup \
  --bootstrap-server localhost:9092

سناریو ۲: تغییر تنظیمات یک Topic

مثلاً افزایش Retention از مقدار پیش‌فرض به ۷ روز:

./bin/kafka-configs.sh \
  --alter \
  --topic user-signup \
  --bootstrap-server localhost:9092 \
  --add-config retention.ms=604800000

مشاهده تنظیمات:

./bin/kafka-configs.sh \
  --describe \
  --topic user-signup \
  --bootstrap-server localhost:9092 --all

سناریو ۳: تولید پیام از طریق CLI

ارسال چند پیام نمونه در Topic:

./bin/kafka-console-producer.sh \
  --bootstrap-server localhost:9092 \
  --topic user-signup

ورودی:

UserA registered
UserB registered
UserC registered

تولید پیام همراه با Key

./bin/kafka-console-producer.sh \
  --bootstrap-server localhost:9092 \
  --topic user-signup \
  --property parse.key=true \
  --property key.separator=,

ورودی:

۱,UserA registered
۲,UserB registered

سناریو ۴: مصرف پیام از Topic

مصرف پیام‌ها از ابتدا:

./bin/kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 \
  --topic user-signup \
  --from-beginning

نمایش Key و Timestamp:

./bin/kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 \
  --topic user-signup \
  --from-beginning \
  --property print.key=true \
  --property print.timestamp=true

سناریو ۵: مشاهده وضعیت Consumer Group

فرض کنید یک Consumer Group به نام email-service پیام‌های Topic user-signup را مصرف می‌کند.
برای مشاهده وضعیت:

./bin/kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --describe \
  --group email-service

این خروجی نشان می‌دهد:

هر پارتیشن چه Offsetی دارد
مصرف‌کنندگان چه مقدار پیام عقب هستند (Lag)
چه پارتیشن‌هایی به چه مصرف‌کننده‌ای اختصاص یافته‌اند

این ابزار مهم‌ترین ابزار برای عیب‌یابی Lag در Production است.

سناریو ۶: Reset کردن Offset یک Consumer Group

گاهی نیاز داریم یک سرویس را از ابتدا پیام‌ها را دوباره بخواند:

./bin/kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group email-service \
  --reset-offsets --to-earliest --execute

یا جلو بردن Offset:

--to-latest

سناریو ۷: حذف یک Topic

./bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 \
  --delete \
  --topic user-signup

۵. نکات عملی هنگام کار با CLI

برای کار روی سرورهای Production، همیشه از bootstrap-server داخلی استفاده کنید.
در محیط واقعی بهتر است ابزارهای CLI را پشت یک Alias یا PATH مناسب قرار دهید.
هنگام تولید یا مصرف حجم زیاد پیام در CLI، بهتر است از ابزارهای GUI یا برنامه‌های واقعی استفاده کنید.
Consumer Groupها یکی از مهم‌ترین نقاط عیب‌یابی هستند؛ با آن‌ها زیاد کار کنید.
هرگز Offsetها را بدون اطمینان Reset نکنید.

جمع‌بندی

ابزارهای خط فرمان کافکا یکی از پایه‌ای‌ترین مهارت‌هایی هستند که هر متخصص داده باید در اختیار داشته باشد. این ابزارها نه‌تنها امکان ایجاد، مدیریت و عیب‌یابی Topicها و Consumer Groupها را فراهم می‌کنند، بلکه در بسیاری از شرایط جایگزینی سریع و قابل‌اعتماد برای ابزارهای گرافیکی محسوب می‌شوند.

موضوع قبلی

بازگشت به درس

موضوع بعدی

دوره مبانی مهندسی داده