مستندات فنی پروژه
SCRIPTS · VERIFY PERSISTENCE

verify/verify_storage_consumer.sh — تأیید ماندگارسازی

← بازگشت به فهرست اسکریپت‌ها

مسیر فایل: scripts/verify/verify_storage_consumer.sh

۱. کاراییش به زبان ساده

بعد از یک دور crawl یا بعد از deploy کردن Storage Consumer، این سوال را جواب می‌دهد: «آیا چیزهایی که به Kafka رفته‌اند واقعاً در PostgreSQL نشسته‌اند؟» مکمل verify_network_metrics.sh است: آن یکی ثابت می‌کند Analyzer چیزی منتشر کرده؛ این یکی ثابت می‌کند ردیف‌ها ماندگار شده‌اند.

۲. کجا در پروژه کلی استفاده می‌شود؟

  • پس از چرخهٔ Crawler، وقتی لاگ می‌گوید پیام publish شده ولی DB خالی به نظر می‌رسد.
  • پس از deploy / restart سرویس storage-consumer.
  • در جریان عملیاتی توصیه‌شده در scripts/README.md کنار bring_up و check_infra.
  • هم‌راستا با مستند معماری Storage Consumer: این اسکریپت لایهٔ ops برای همان تضمین‌های persistence است.

۳. چیکارا می‌کند؟ (به ترتیب)

  1. اسکیما: آیا اشیاء اسکیمایی که این زیرسیستم مالک آن‌هاست در Postgres حاضرند؟
  2. سلامت کانتینر: آیا project_storage_consumer در حال اجرا و healthy است؟
  3. Lag کافکا: آیا consumer groupها (storage-consumer.*) عقب افتاده‌اند یا در حال همگام‌ماندن‌اند؟ آستانهٔ هشدار پیش‌فرض ۱۰۰۰ است.
  4. ردیف‌های ذخیره‌شده: شمارش / حضور داده در جدول‌های مقصد.
  5. Dead letters: چند پیام اخیر رد شده‌اند و (اختیاری) نمایش جزئیات آن‌ها.

Exit code 0 یعنی اسکیما هست، consumer سالم است و ردیف‌ها حاضرند؛ 1 یعنی حداقل یک چک الزامی شکست خورده.

۴. تصمیمات معماری

  • جدا از check_infra: infra سالم بودن ≠ دادهٔ business درست نشستن. این اسکریپت عمداً لایهٔ بالاتر را چک می‌کند.
  • Lag به‌عنوان سیگنال عملیاتی: قبل از نتیجه‌گیری «DB خالی است چون consumer خراب است»، باید دید آیا هنوز در حال خوردن backlog است.
  • Dead letters قابل مشاهده: پیام‌های reject‌شده نباید فقط در لاگ گم شوند؛ جدول dead letter منبع حقیقت برای «چرا ننشست» است.
  • پیشوند group قابل تنظیم: باید با STORAGE_CONSUMER_GROUP_PREFIX واقعی محیط یکی باشد؛ در غیر این صورت lag مربوط به گروه اشتباه خوانده می‌شود.
  • WARN در برابر FAIL: عبور lag از آستانه می‌تواند هشدار باشد بدون اینکه لزوماً کل verify را قرمز کند — تا نویز و سیگنال از هم جدا بمانند.

۵. دستورات

# بررسی معمول پس از بالا آمدن استک / بعد از crawl
./scripts/verify/verify_storage_consumer.sh

# بررسی عمیق‌تر پیام‌های ردشده
./scripts/verify/verify_storage_consumer.sh --dead-letters 25

# تغییر آستانهٔ هشدار lag
./scripts/verify/verify_storage_consumer.sh --lag-threshold 500

./scripts/verify/verify_storage_consumer.sh --help

پیش‌نیاز:

docker compose up -d postgres kafka storage-consumer

← create_topics.sh · فهرست اسکریپت‌ها · verify_network_metrics.sh →