finalize_cycle_reports.py | مستندات اسکریپت‌ها

مسیر فایل: scripts/reports/finalize_cycle_reports.py

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

وقتی گزارش‌های چرخه فعال باشند، Crawler پس از هر دور crawl یک فایل JSON در data/reports/pending/ می‌نویسد. این اسکریپت آن فایل‌ها را برنمی‌دارد تا وقتی lag کافکای Storage Consumer روی تاپیک‌های app-stats و reviews به صفر برسد؛ بعد یک خط به data/reports/cycles.jsonl اضافه می‌کند، verdict می‌زند، و فایل را به done/ منتقل می‌کند. معمولاً دستی اجرا نمی‌شود — سرویس Compose به نام cycle-reporter همین فایل را mount و در حلقه اجرا می‌کند.

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

فعال‌سازی از طریق ./scripts/bring_up.sh --with-cycle-reports (کامنت‌های docker-compose.yml هم همین را می‌گویند).
سرویس cycle-reporter با entrypoint مستقیم روی همین اسکریپت پایتون.
پل بین «خلاصهٔ crawl سمت producer» و «اطمینان از اینکه consumer backlog را خالی کرده» — یعنی گزارش end-to-end واقعی، نه فقط لاگ کراولر.
روی host هم قابل اجراست وقتی استک بالاست و Kafka از localhost:9092 در دسترس است.

۳. چیکارا می‌کند؟

پوشه‌های pending / done را در مسیر گزارش‌ها آماده می‌کند.
برای هر *.json در pending:
- منتظر lag=0 روی گروه‌های storage-consumer.app-stats و storage-consumer.reviews (با timeout قابل تنظیم، پیش‌فرض ۶۰۰ ثانیه).
- اختیاری: شمارش dead letterهایی که از شروع چرخه به بعد ثبت شده‌اند (اگر Postgres در دسترس باشد).
- ساخت گزارش نهایی با فیلدهای lag، مدت end-to-end، و verdict.
- Append یک خط JSON به cycles.jsonl و انتقال فایل به done/.
حالت --loop: همین کار را در بازهٔ زمانی تکرار می‌کند (پیش‌فرض ۶۰ ثانیه / env).

معنای verdictها (خلاصه):

verdict	شرایط تقریبی
`ok`	lag صفر، بدون dead letter جدید، و crawl برای stats/reviews کامل موفق.
`partial`	بخشی از crawl شکست خورده، یا dead letter بعد از شروع چرخه وجود دارد.
`failed`	هیچ stats و هیچ reviews موفقی در چرخه نبوده.
`persist_lagging`	تا پایان timeout هنوز lag صفر نشده.

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

چرا pending فقط بعد از پایان crawl ساخته می‌شود؟ تا mid-cycle lag=0 باعث finalize زودهنگام نشود — در میانهٔ چرخه ممکن است موقتاً صف خالی به نظر برسد در حالی که producer هنوز پیام می‌فرستد.
دو منبع حقیقت جدا: Crawler آمار تولید خودش را می‌نویسد؛ این اسکریپت بُعد persist را اضافه می‌کند. گزارش نهایی بدون ادغام این دو ناقص است.
jsonl به‌جای DB جدا: سبک، append-only، مناسب tail کردن توسط اپراتور و ابزارهای ساده؛ نیاز به اسکیمای گزارش جدا ندارد.
مسیر گزارش وابسته به محیط: روی host معمولاً data/reports؛ داخل کانتینر وقتی POSTGRES_HOST=postgres باشد مسیر /data/reports؛ قابل override با env.
سرویس Compose جدا (cycle-reporter): منطق finalize داخل imageهای crawler/consumer قاطی نشود؛ یک job ops با mount فقط همین اسکریپت.

۵. دستورات

# فعال‌سازی از طریق bring-up
./scripts/bring_up.sh --with-cycle-reports
docker compose logs -f cycle-reporter
tail -n 20 data/reports/cycles.jsonl

# اجرای یک‌باره روی host (استک بالا، Kafka روی localhost:9092)
./scripts/reports/finalize_cycle_reports.py

# حلقهٔ دستی
./scripts/reports/finalize_cycle_reports.py --loop --interval 60

# تنظیم timeout انتظار برای lag
./scripts/reports/finalize_cycle_reports.py --lag-timeout 300

پیش‌نیاز host: بستهٔ kafka-python (و برای dead-letter count، psycopg2). استک باید بالا باشد.

← analyze_pcaps.sh · فهرست اسکریپت‌ها · run_tests_in_docker.sh →

reports/finalize_cycle_reports.py — نهایی‌سازی گزارش چرخه