دسکتاپ، Worker و محاسبات محلی · فصل ۳ — Identity، Health، Lease و SQLite Spool · 183
Heartbeat, Inventory و Health Telemetry
اپ یا worker محلی را اجرا می‌کند اما device identity، privilege، offline state و fleet behavior را طراحی نکرده است. موضوع جاری: «Heartbeat, Inventory و Health Telemetry». می‌تواند «Heartbeat, Inventory و Health Telemetry» را برای یک node محلی با identity، state، privilege و recovery boundary مناسب طراحی کند.
خلاصهٔ درس
اپ یا worker محلی را اجرا می‌کند اما device identity، privilege، offline state و fleet behavior را طراحی نکرده است. موضوع جاری: «Heartbeat, Inventory و Health Telemetry».
می‌تواند «Heartbeat, Inventory و Health Telemetry» را برای یک node محلی با identity، state، privilege و recovery boundary مناسب طراحی کند.
خروجی این درس
می‌تواند «Heartbeat, Inventory و Health Telemetry» را برای یک node محلی با identity، state، privilege و recovery boundary مناسب طراحی کند.
پیش‌نیازها
1. مسئله واقعی: heartbeat تازه مساوی node سالم نیست
یک heartbeat تازه فقط می‌گوید یک فرستنده در یک بازه زمانی اخیر توانسته signal بفرستد. همین node ممکن است inventory قدیمی، service با وضعیت NOT_SERVING، دیسک کم، فشار حافظه، version drift یا identity generation منسوخ داشته باشد. خروجی این درس Node Heartbeat, Inventory & Health Evidence Matrix v1 است: ماتریسی که liveness، inventory، service health و resource observation را جدا نگه می‌دارد و تصمیم health را فقط به اندازه evidence موجود قوی می‌کند.
2. مرز مالکیت LOC-010
LOC-010 مالک heartbeat، زمان مشاهده/دریافت، inventory snapshot و generation آن، service instance/version/health، resource observations، freshness و health synthesis است. Enrollment و credential generation در LOC-009 قرار دارد؛ lease و work authority در LOC-011؛ durable offline spool در LOC-012. Telemetry observed state را توصیف می‌کند و به‌تنهایی مجوز اجرای privileged action نمی‌دهد.
3. Telemetry باید به identity و generation درست bind شود
حداقل worker_id، identity_generation، heartbeat_sequence، observed_at و received_at را ثبت کنید. timestamp تازه، identity قدیمی را معتبر نمی‌کند. اگر worker بعد از re-enrollment روی generation 8 است، heartbeat مربوط به generation 7 حتی با timestamp جدید باید stale/quarantined باقی بماند تا telemetry یک instance قدیمی به node فعلی نسبت داده نشود.
4. OpenTelemetry Resource و service identity چه کمکی می‌کنند
در OpenTelemetry، Resource موجودیتی را توصیف می‌کند که telemetry برای آن تولید شده است. Service semantic conventions نیز بین service منطقی و service.instance.id متمایز می‌شوند و service.version را جدا ثبت می‌کنند. این semantics برای correlation و provenance مفیدند، اما policy سلامت MAKNOW را تعریف نمی‌کنند؛ node health همچنان باید از contract همین درس محاسبه شود.
5. Heartbeat فقط liveness evidence است
برای heartbeat یک liveness_window صریح داشته باشید و heartbeat_age را از clock policy اعلام‌شده محاسبه کنید. اگر heartbeat در window باشد، state می‌تواند LIVE باشد؛ اگر نه STALE یا UNKNOWN. LIVE هرگز shortcut برای «inventory current»، «service serving» یا «resource safe» نیست. transport keepalive یا اتصال شبکه نیز معادل service health نیست.
6. Inventory آهسته‌تر تغییر می‌کند، اما باید freshness مستقل داشته باشد
Inventory شامل فیلدهایی مانند host_id، OS/arch، ظرفیت CPU/Memory، service version و generation snapshot است. این داده ممکن است با cadence آهسته‌تری نسبت به heartbeat جمع شود، اما inventory_age و inventory_generation باید مستقل ثبت شوند. اگر TTL محلی 30 دقیقه است و snapshot شش‌ساعته است، نتیجه INVENTORY_STALE است؛ نه اینکه مقادیر قدیمی را current فرض کنیم.
7. gRPC Health یک service signal است، نه whole-node verdict
gRPC Health عملیات Check و Watch را تعریف می‌کند و برنامه مسئول به‌روزرسانی SERVING و NOT_SERVING است. این signal نشان می‌دهد یک service آیا آماده پذیرش request است یا نه. heartbeat تازه در کنار NOT_SERVING باید health تصمیم را پایین بیاورد؛ heartbeat اجازه ندارد service state را override کند.
8. Resource observations باید provenance و missing state داشته باشند
CPU، memory، disk free و process uptime نمونه‌هایی از observations هستند. برای هر observation مشخص کنید چه زمانی، از چه source و با چه policy جمع شده است. اگر disk_free برای decision لازم است ولی signal وجود ندارد، مقدار حدسی نسازید. state باید UNKNOWN یا DEGRADED بماند و recheck trigger روشن باشد.
9. Semantic conventionها schema ابدی نیستند
OpenTelemetry برای system metrics هنوز بخش‌هایی با وضعیت Development و برای process metrics بخش‌هایی با Release Candidate دارد. بنابراین نام metricها را reference convention بدانید، نه schema تغییرناپذیر MAKNOW. contract داخلی باید semantic مورد نیاز خود را version کند تا upstream rename یا stability change باعث تفسیر اشتباه historical evidence نشود.
10. Version drift یک evidence dimension مستقل است
service.version و inventory generation را با desired/expected version policy محلی مقایسه کنید. Version drift ممکن است node را فوراً dead نکند، ولی می‌تواند health را DEGRADED یا admission را محدود کند. آن را در reason ثبت کنید و از قاطی‌کردن «service پاسخ می‌دهد» با «version مورد انتظار اجرا می‌شود» پرهیز کنید.
11. Resource pressure باید با policy محلی سنجیده شود
هیچ threshold جهانی CPU/Memory/Disk در این درس اختراع نمی‌شود. fixture یا deployment policy باید floor/ceiling را بدهد. اگر disk free زیر floor محلی یا memory pressure بالای ceiling محلی است، state را DEGRADED کنید حتی اگر heartbeat و service health تازه باشند. عدد بدون policy فقط observation است، نه verdict.
12. Health synthesis باید fail-closed یا degrade شود
یک تصمیم bounded می‌تواند فقط وقتی HEALTHY باشد که identity generation درست، heartbeat fresh، inventory current، service SERVING و observations decisive موجود و در policy باشند. اگر یک dimension decisive stale/missing/conflicting است، health باید STALE_REJECTED، INVENTORY_STALE، UNKNOWN یا DEGRADED شود. میانگین‌گیری از signalها برای پنهان‌کردن failure مجاز نیست.
13. Evidence Matrix تصمیم را قابل بازتولید می‌کند
برای هر case این ستون‌ها را نگه دارید: Worker ID، Identity Generation، Heartbeat Sequence، Observed/Received At، Heartbeat Age/Liveness، Inventory Generation/Age، Service Instance/Version/Health، CPU، Memory، Disk Free، Process Uptime، Missing Signal، Version Drift، Resource Pressure، Health Decision و Reason. Reviewer باید بدون hidden reasoning بتواند تصمیم را از روی همین evidence بازسازی کند.
14. Failure Probeهای تعیین‌کننده
چهار shortcut را بشکنید: (1) heartbeat fresh ولی service NOT_SERVING → HEALTHY ممنوع؛ (2) heartbeat/service fresh ولی inventory از TTL عبور کرده → INVENTORY_STALE؛ (3) heartbeat تازه با identity generation قبلی → stale binding reject/quarantine؛ (4) همه چیز خوب ولی disk_free برای policy لازم و missing است → UNKNOWN/DEGRADED، نه imputation. Lab label نهایی را از learner پنهان نگه می‌دارد.
15. Transfer از push heartbeat به pull/streaming collector
Transport را عوض کنید اما contract را نه. در pull/streaming نیز source identity، identity generation، observation time، received time، freshness window، inventory generation، service health و missing-signal semantics باید حفظ شوند. Sampling cadence جدید می‌تواند ageها را تغییر دهد؛ بنابراین health باید از evidence جدید دوباره محاسبه شود و verdict baseline کپی نشود.
ارزیابی
پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.
Q1 application
Build the Node Heartbeat, Inventory & Health Evidence Matrix from the supplied synthetic fixture without inventing missing observations.
Q2 diagnosis
Explain why a fresh heartbeat plus NOT_SERVING service health cannot be HEALTHY.
Q3 decision
Issue a typed health decision for stale inventory and name the recheck trigger.
Q4 transfer
Recompute the decision after moving from push heartbeat to pull/streaming collection with a different sampling cadence.
ملاک‌های ارزیابی (rubric)
- Identity binding — critical: worker identity and identity generation are explicit.
- Freshness separation — critical: heartbeat age and inventory age use separate declared windows.
- Service/resource evidence — critical: service health and required resource observations remain separate from liveness.
- Typed non-success — critical: stale, missing, conflict, pressure, or old-generation evidence is not coerced into healthy.
- Bounded decision — critical: the decision is no stronger than visible evidence and names a recheck trigger.
- Transfer — critical: the changed transport/cadence causes recomputation rather than copying the baseline verdict.
منابع و تازگی
مطالعهٔ موارد (case studies)
تصاویر درس
فایل‌های آزمایشگاه
Build a function evaluate_health(case) in starter.py. Preserve identity-generation binding, heartbeat freshness, inventory freshness, service health, resource observations, missing signals and local thresholds as separate evidence dimensions.
The fixtures are synthetic and offline. They intentionally do not include final expected decisions. Run python run_checks.py to confirm only the learner-facing structure.