Health Check مش مجرد Endpoint بيرجع 200
Health check endpoint يجاوب سؤال تشغيلي: هل process شغالة؟ هل تقدر تستقبل traffic؟ هل dependency مهمة متاحة؟ الأسئلة دي مختلفة ولازم endpoints/consumers تفسرها بشكل مختلف. مجرد أن /health يرجع 200 لا يثبت أن business workflow سليم أو أن كل dependencies تعمل.
أهم ثلاث مفاهيم: Liveness هل process عالقة/غير قادرة على التقدم وتحتاج restart؟ Readiness هل instance جاهزة لاستقبال requests الآن؟ Startup هل التطبيق انتهى من initialization الطويلة؟ Dependency health تفحص خدمة خارجية مثل database أو broker، لكنها ليست بالضرورة liveness signal.
Liveness مقابل Readiness في رسمة
Liveness vs Readiness vs Startup
Liveness يجب تكون خفيفة ولا تعتمد عادة على DB/Redis/Service Bus. لو DB وقعت مؤقتًا وكل instances أصبحت liveness unhealthy، orchestrator قد يعمل restart لكل instances في نفس الوقت، فيزيد الضغط ويمنع recovery. Readiness يمكن أن تفشل عندما instance لا تستطيع خدمة requests بسبب dependency حرجة أو initialization، فيتوقف توجيه traffic إليها من غير restart بالضرورة.
Startup probe تحمي app من liveness checks المبكرة أثناء startup/migrations/cache warmup. من غير startup probe، liveness قد تقتل process بطيئة لكنها سليمة. اضبط thresholds و initial delay/period/timeout/failure threshold حسب measured startup time وليس أرقامًا من tutorial.
قرار هل DB failure يجعل readiness false يعتمد على API behavior. لو معظم endpoints لا تحتاج DB، ربما تظل ready مع degraded mode؛ لو كل request يحتاج DB، readiness false قد تكون مناسبة. لا تجعل health endpoint تخلق cascading failure عبر فحص كل dependency كل ثانية.
Liveness و Readiness و Startup: ثلاثة أسئلة مختلفة
Liveness: هل process عالقة أو غير قادرة على التقدم بحيث restart قد يساعد؟ لا تجعلها تفشل لمجرد أن database down؛ وإلا كل replicas تعيد التشغيل أثناء outage وتزيد الحمل. Readiness: هل هذه instance قادرة الآن على استقبال traffic؟ يمكن أن تفشل عند dependency أساسية غير متاحة أو أثناء warm-up. Startup: هل التطبيق انتهى من initialization الأولي؟ مفيدة عندما startup بطيء ولا تريد liveness تقتله مبكرًا.
Health endpoint ليس monitoring بديلًا ولا اختبار business transaction. اجعل response minimal ولا تكشف connection strings أو hostnames أو secrets للعامة. افصل endpoint داخليًا عن public API عند الحاجة، واحمِ diagnostics التفصيلية. حدد dependency criticality: database قد تكون لازمة للـ API، لكن telemetry exporter غالبًا لا ينبغي أن يجعل التطبيق unready.
Readiness Contract: ما الذي نعد به الـ Load Balancer؟
Readiness لا تعني أن كل dependency سليمة؛ تعني أن instance قادرة على خدمة traffic الموجه إليها وفق contract. إذا endpoint للقراءة يستطيع استخدام cache عند database outage، ربما يظل ready للقراءة لكنه ليس جاهزًا لعمليات الكتابة. يمكن أن يكون لديك separate capability health أو service-level readiness policy بدل Boolean واحد يعكس كل النظام.
لا تجعل load balancer يرسل traffic إلى instance أثناء migration أو warm-up أو draining. عند shutdown، أزل readiness أولًا، ثم توقف عن استقبال requests جديدة، ثم انتظر inflight requests ضمن grace period. اختبر race بين readiness update و traffic routing. هذا مهم خصوصًا مع rolling deployments و long-running HTTP requests.
تسجيل Health Checks في ASP.NET Core
ASP.NET Core Health Checks توفر AddHealthChecks() لإضافة checks، و MapHealthChecks() لنشر endpoints. Tags تسمح بتجميع checks مثل ready, live, external. يمكن استخدام package إضافية لفحص EF Core، لكن راجع package version مع .NET target لتجنب assembly mismatch.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks()
.AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])
.AddDbContextCheck<AppDbContext>("database", tags: ["ready"]);
var app = builder.Build();
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("live")
});
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("ready")
});
app.Run();أضف package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore المتوافقة مع target framework لاستخدام AddDbContextCheck. لا تجعل database check ضمن liveness. إذا لم تستخدم EF Core، اكتب custom IHealthCheck أو استخدم client probe مناسب.
تنفيذ Health Checks في ASP.NET Core
builder.Services.AddHealthChecks()
.AddDbContextCheck<AppDbContext>("database", tags: ["ready"]);
var app = builder.Build();
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
Predicate = _ => false
});
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("ready")
});
app.Run();تأكد من إضافة package الخاصة بـ EF health check عند استخدام AddDbContextCheck. لا تضع كل checks في liveness. يمكن أن تضيف external dependencies في readiness فقط لو عدم توفرها يمنع الخدمة فعلًا من العمل. اجعل timeout لكل check محدودًا، وامنع cascading checks التي تنتظر خدمة أخرى تنتظرها.
Custom IHealthCheck و Timeout
Custom check تنفذ IHealthCheck.CheckHealthAsync. يجب تحترم CancellationToken، وتستخدم timeout budget صغيرًا، وتعيد Healthy/Degraded/Unhealthy حسب impact. لا تنفذ query ثقيلة أو scan كبير في كل probe. استخدم SELECT 1 أو lightweight ping عند الحاجة، لكن انتبه أن connection pool exhaustion نفسها قد تجعل health probe تفشل.
public sealed class BrokerHealthCheck(IMessageBroker broker) : IHealthCheck
{
public async Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
timeout.CancelAfter(TimeSpan.FromSeconds(2));
try
{
await broker.PingAsync(timeout.Token);
return HealthCheckResult.Healthy("Broker reachable");
}
catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
{
return HealthCheckResult.Degraded("Broker probe timed out");
}
catch (Exception ex)
{
return HealthCheckResult.Unhealthy("Broker unavailable", ex);
}
}
}لا ترجع raw exception details للـ public response. HealthCheckResult description/data يمكن أن تحتوي معلومات داخلية؛ استخدم response writer آمنًا، ولا تعرض connection strings أو hostnames الحساسة. لو cancellation من host نفسه، لا تحولها تلقائيًا إلى Degraded؛ اترك cancellation semantics واضحة.
HTTP Status و Response Writer و Security
Health checks عادة ترجع 200 healthy، و503 unhealthy/degraded حسب response writer/status mapping. اجعل output minimal للعامة، واحتفظ بالتفاصيل في authenticated internal endpoint أو telemetry. لا تعرض أسماء hosts/ports/versions/connection errors لغير المخولين. Health endpoint قد تكون هدفًا لـ attacker لمعرفة topology.
لا تضع endpoint readiness public بلا حاجة. في Kubernetes/Container Apps/hosting platform، probe تصل من platform، ويمكن حماية endpoint عبر network/internal ingress أو route policy متوافقة مع probe mechanism. لا تطلب JWT من probe إذا platform لا تستطيع إرساله؛ استخدم private network/allow-list/management endpoint pattern.
ما الذي يجب فحصه؟ Database أم Redis أم Broker؟
ابدأ بسؤال: هل فشل dependency يمنع instance من خدمة requests الحرجة؟ Database غالبًا critical لـ CRUD API، لكن Redis cache قد يكون optional لو fallback إلى DB ممكن. Broker قد يكون critical لـ background worker لكنه لا يمنع API من قبول request إذا Outbox يسجل الحدث. External payment provider لا يجب غالبًا أن يجعل كل API readiness false؛ payment endpoint قد يرجع degraded/503 مع بقاء باقي API متاحة.
افصل health checks حسب service role: API readiness تعتمد على DB إن كانت critical؛ worker readiness تعتمد على broker subscription/consumer state؛ liveness تراقب process responsiveness. لا تفحص كل provider external بشكل متكرر من كل replica، لأن probe traffic قد يسبب load/cost ويؤدي إلى failure cascade.
سياسة Health Check: Dependency Degradation لا تساوي Process Death
Liveness يجيب: هل process نفسها عالقة لدرجة تحتاج restart؟ لذلك غالبًا لا تفحص SQL أو Redis. Readiness يجيب: هل instance جاهزة لاستقبال traffic الآن؟ يمكن أن يشمل dependency حرجة، لكن يجب أن يكون timeout قصيرًا وسياسة الفشل محسوبة. Startup probe تمنح initialization وقتًا كافيًا قبل liveness.
builder.Services.AddHealthChecks()
.AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])
.AddSqlServer(connectionString, name: "sql", tags: ["ready"]);
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("live")
});
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("ready")
});المثال يوضح فصل tags؛ تأكد من package الخاص بـ SQL health check ومن نسخة API المستخدمة. إذا فشل SQL مؤقتًا، readiness قد تجعل كل replicas غير جاهزة في نفس اللحظة؛ هذا قد يحوّل degradation إلى outage كامل. حدد dependency criticality، timeouts، caching للنتيجة عند الحاجة، و failure threshold/hysteresis في orchestrator.
Health response لا يجب أن يعرض connection string أو hostname داخلي أو exception message أو credentials. استخدم status code مناسبًا و response writer محدودًا، واحمِ endpoint إذا كان يكشف topology. اختبر timeout و exception و partial outage، وتأكد أن health probe لا تنشئ ضغطًا على database كل ثانية من كل replica.
تطبيق Live و Ready عمليًا في ASP.NET Core
في التطبيق الحقيقي افصل endpoint للـ liveness عن readiness. المثال التالي يضع self check في live، و DB check في ready، ويجعل response مختصرًا دون تفاصيل داخلية. تأكد من إضافة package المناسبة لـ EF Core health checks وبنفس major version للـ runtime.
using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using Microsoft.Extensions.Diagnostics.HealthChecks;
builder.Services.AddHealthChecks()
.AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])
.AddDbContextCheck<AppDbContext>("database", tags: ["ready"]);
var app = builder.Build();
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("live"),
ResultStatusCodes =
{
[HealthStatus.Healthy] = StatusCodes.Status200OK,
[HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
}
});
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("ready"),
ResultStatusCodes =
{
[HealthStatus.Healthy] = StatusCodes.Status200OK,
[HealthStatus.Degraded] = StatusCodes.Status200OK,
[HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
}
});هذا skeleton يحتاج using/registration مطابقين للـ packages في مشروعك. لو DB check يمكن أن يتأخر، ضع timeout مناسبًا ولا تجعل كل probe يفتح عمليات مكلفة بلا حدود. لا تعرض exception message أو connection string في response العام؛ التفاصيل تذهب إلى logs محمية مع redaction.
في Kubernetes اربط liveness بـ /health/live و readiness بـ /health/ready، وأضف startup probe لو initialization طويل. اختبر DB outage: هل readiness تفشل فقط؟ هل liveness تظل ناجحة؟ هل التطبيق يتعافى عند رجوع DB دون restart storm؟ هذه اختبارات تشغيلية أهم من مجرد أن endpoint يرجع 200 محليًا.
Degraded Mode: هل كل Dependency شرط للـ Readiness؟
تخيل API لقراءة المنتجات تعتمد على database و recommendation service و email provider. إذا recommendation service تعطلت، قد تظل API قادرة على تقديم catalog؛ جعل readiness تفشل سيوقف خدمة أساسية بلا ضرورة. أما لو database هي المصدر الوحيد للمنتجات ولا توجد cache/fallback، readiness قد تفشل. القرار يعتمد على capability التي ستتأثر وعلى ما إذا كان degraded response مقبولًا.
قسّم health checks حسب criticality، وميّز dependency failure عن application deadlock. لا تنفذ كل health check عبر dependency chain طويلة، ولا تجعل endpoint العام يكشف أسماء الموارد. أضف timeout و circuit breaker أو cached health state عند الحاجة. health check نفسه يجب أن يكون رخيصًا ولا يخلق load storm على database كل ثانية.
Docker و Kubernetes و Cloud Probes
Docker HEALTHCHECK يحدد command/interval/timeout/retries/start-period ويضع health status على container. لكنه لا يعني Docker restart unhealthy container تلقائيًا في كل setup؛ restart policy ترتبط process exit behavior. Compose يقدر يستخدم health status في depends_on condition حسب implementation.
Kubernetes لديه liveness/readiness/startup probes منفصلة: liveness restart، readiness توقف routing، startup تمنع liveness/readiness المبكرة. Azure Container Apps و Cloud Run لديهم startup/readiness/liveness probe options حسب platform. اربط كل probe بال endpoint الصحيح وبـ timeout/threshold measured. لا تستخدم DB readiness endpoint كـ liveness.
startupProbe:
httpGet:
path: /health/startup
port: 8080
periodSeconds: 5
failureThreshold: 24
livenessProbe:
httpGet:
path: /health/live
port: 8080
periodSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet:
path: /health/ready
port: 8080
periodSeconds: 5
failureThreshold: 2YAML sketch فقط؛ ضعه داخل container spec في Pod/Deployment، واضبط initial delays/timeouts وفق التطبيق. لو probe endpoint ترجع 503 أثناء warmup، readiness false متوقعة، لكن liveness لا تقتل app قبل startup success.
Kubernetes Probes و Failure Policy
Startup probe تسمح بوقت إقلاع طويل؛ liveness تبدأ بعد نجاحها. Readiness تتحكم في إدخال Pod إلى Service endpoints. اضبط initialDelaySeconds و periodSeconds و timeoutSeconds و failureThreshold بناءً على measured startup/latency، لا copy-paste. Probe path يجب يكون سريعًا ولا يعتمد على سلسلة dependencies طويلة.
startupProbe:
httpGet:
path: /health/live
port: 8080
periodSeconds: 5
failureThreshold: 30
livenessProbe:
httpGet:
path: /health/live
port: 8080
periodSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet:
path: /health/ready
port: 8080
periodSeconds: 5
failureThreshold: 2لو readiness تفشل لكل pods بسبب database outage، traffic يتوقف وهذا قد يكون صحيحًا أو قد يجعل النظام كله unavailable؛ القرار يعتمد على ما يمكن تقديمه degraded mode. لا تجعل liveness restart storm. راقب probe failures كإشارة مستقلة، واختبر سيناريو dependency outage.
Graceful Shutdown و Connection Draining
في rolling deployment، يجب أن تتوقف instance عن استقبال traffic جديد قبل إنهائها، بينما تكمل requests الحالية ضمن مهلة. في ASP.NET Core استخدم host lifetime و CancellationToken، واجعل BackgroundService يوقف polling ثم يكمل/يعيد الرسالة غير المكتملة. في Kubernetes اضبط termination grace period و preStop hook فقط عند الحاجة؛ sleep ثابت طويل قد يبطئ rollout بلا فائدة.
اختبر request طويلًا أثناء shutdown، و queue message أثناء cancellation، و database transaction أثناء termination. لا تعلن readiness false بعد أن يبدأ process الإغلاق بوقت متأخر جدًا؛ يجب أن تتوافق readiness و load balancer propagation مع draining window. اجعل operation قابلة للاستئناف أو idempotent لأن process قد تُقتل قبل اكتمالها.
Health Checks Across Load Balancers و Orchestrators
ASP.NET Core endpoint يحدد status؛ orchestrator أو load balancer يفسرها ويتخذ قرارًا. اختلاف path أو port أو auth بين التطبيق وال platform يجعل check تفشل رغم أن الخدمة تعمل. وثّق endpoint names، network reachability، expected status codes، TLS، timeout، و probe intervals. لا تستخدم authentication flow ثقيلًا لفحص داخلي، لكن لا تفتح diagnostics sensitive للعامة.
لو service تعمل خلف reverse proxy، افحص هل probe تضرب container مباشرة أم ingress. health check عبر ingress قد تفشل بسبب DNS/certificate قبل وصولها للتطبيق، وهذا يخلط صحة التطبيق بصحة edge. غالبًا platform probe المباشرة للـ Pod/container أفضل، مع synthetic external check منفصل يختبر المسار الكامل للمستخدم.
اختبار Health Checks و Failure Scenarios
- App تبدأ ببطء: startup probe تمنع restart مبكر.
- DB down: readiness false إذا DB critical، لكن liveness تظل healthy.
- Redis down مع cache fallback: readiness قد تظل healthy مع degraded metric.
- Broker timeout: worker readiness false، API قد تبقى ready إذا outbox يعمل.
- Probe storm: تأكد أن كل replica لا تنفذ expensive checks بتردد عالٍ.
- Cancellation/shutdown: check تحترم token ولا تترك background tasks.
- Unauthorized probe: platform تصل لل endpoint دون كشفه للعامة.
اختبر check implementations بـ fake dependencies و controlled timeout. استخدم integration test لـ mapped endpoints و status codes/response body. لا تختبر فقط أن endpoint يرجع 200 في test environment؛ اختبر failure semantics.
اختبار Health Checks: Failure Matrix
اكتب integration tests أو failure drills تغطي الحالات التالية، وسجّل expected status لكل endpoint. لا تخلط dependency outage مع process failure:
| الحالة | Live | Ready | التصرف المتوقع |
|---|---|---|---|
| API process سليمة و DB متاحة | 200 | 200 | تستقبل traffic |
| DB متوقفة و DB مطلوبة لكل request | 200 | 503 | تخرج من service endpoints |
| DB متوقفة لكن endpoint degraded mode متاح | 200 | قد تظل 200 | تعرض الوظائف المتاحة بوضوح |
| Process deadlocked/unresponsive | timeout/failure | timeout/failure | restart وفق liveness policy |
| Startup لم يكتمل | لا يُحكم عليها مبكرًا | 503 | startup probe تمنع restart المبكر |
أضف timeout و concurrency limit للـ checks، واستخدم caching قصيرًا عند الحاجة لتجنب ضغط dependencies. راقب check duration و failure rate كـ metrics. لا تستخدم readiness endpoint كـ public diagnostics page؛ اجعل الوصول والتفاصيل مناسبين للمنصة والتهديدات.
اختبار Health Policy تحت Failure Scenarios
اكتب integration tests أو chaos exercises للسيناريوهات: database latency، database unavailable، cache unavailable، slow startup، deadlocked worker، telemetry exporter down، dependency recovers، و shutdown أثناء request. المتوقع ليس دائمًا 503؛ اختبر القرار المقصود: هل تبقى readiness true في degraded mode؟ هل liveness لا تفشل بسبب dependency خارجية؟ هل probe timeout أقصر من platform timeout؟
اختبر كذلك أن endpoint لا يعرض تفاصيل حساسة، وأن health check لا يفتح connection جديدًا لكل probe بلا pooling أو rate control، وأن readiness recovery تحدث بعد عودة dependency. اجعل check names و statuses قابلة للتمييز في logs/metrics، مع عدم تسريب exception message للمستخدم العام.
Health Check Anti-Patterns
- Database query ثقيلة كل ثانية من كل replica: تتحول health check إلى load generator.
- Liveness تعتمد على كل external service: outage خارجي يسبب restart storm.
- Readiness ترجع Healthy دائمًا: load balancer يرسل traffic إلى instance غير جاهزة.
- Health endpoint يكشف exception messages أو connection strings للعامة.
- Probe timeout أطول من platform timeout أو threshold لا يناسب startup latency.
- كل dependency تُعامل critical رغم وجود fallback أو degraded mode.
صمم health endpoints مع platform operator: ما القرار الذي سيتخذه عند failure؟ إذا لا يوجد إجراء مفيد، ربما check مكانها dashboard/alert وليس readiness. راجع كل check بعد incident لمعرفة هل ساعدت على التشخيص أم زادت الضوضاء.
اختبر فهمك
هل liveness يجب تفحص قاعدة البيانات دائمًا؟
ما دور startup probe؟
هل Degraded تعني دائمًا 200؟
هل Redis cache down يجب توقف كل API؟
هل Docker HEALTHCHECK يعيد تشغيل container تلقائيًا؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
خريطة التغطية: 9 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.