Health Probes & Monitoring
Relevant source files
The following files were used as context for generating this wiki page:
The Health Monitoring system implements Kubernetes-style probes to report the operational status of the Thoth platform. It provides endpoints to verify if the process is alive and if the service is ready to accept traffic based on internal lifecycle states and dependency reachability.
The monitoring logic is split across the API and Web applications, ensuring that platform components can be independently verified by orchestration tools or external monitors.
Sources: apps/api/spec/health.md:9-11, apps/web/spec/web.md:9-10
API Health Probes
The API service implements two primary health endpoints under the /health prefix. These probes monitor the application lifecycle and the connectivity of critical dependencies like the database.
Liveness Probe
The liveness probe reports whether the API process is running. It returns a 200 OK status with a simple JSON body when the process is active.
Sources: apps/api/spec/health.md:14-14, apps/api/test/modules/health/application/health.service.test.ts:13-16
Readiness Probe
The readiness probe determines if the API is capable of handling requests. This status depends on three conditions:
- The service has successfully completed its
start()sequence. - The service has not yet executed its
stop()sequence. - Downstream dependencies, specifically the database (DB), are reachable.
If these conditions are met, the probe returns 200 OK. If the service is starting, stopping, or the DB ping fails, it returns 503 Service Unavailable with a degraded status.
Sources: apps/api/spec/health.md:15-20, apps/api/test/modules/health/application/health.service.test.ts:18-36
Health Status Logic
The following diagram illustrates the decision flow for determining the readiness of the API service.
The system uses a HealthService to aggregate these checks and report a unified status.
Sources: apps/api/test/modules/health/application/health.service.test.ts:18-53
Web Health Probes
The Web application provides a health check endpoint at /health. The platform checks this endpoint to ensure the frontend service is operational. It returns a 200 OK response when the service is healthy.
Sources: apps/web/spec/web.md:12-12, apps/web/test/app/health.test.ts:6-12
Endpoint Summary
| Endpoint | App | Purpose | Success (200) | Failure (503) |
|---|---|---|---|---|
/health/live | API | Process is running | { status: "ok" } | N/A |
/health/ready | API | Traffic can be accepted | { status: "ok", checks: { db: "ok" } } | { status: "degraded", ... } |
/health | Web | Frontend is active | { status: "ok" } | N/A |
Sources: apps/api/spec/health.md:14-15, apps/web/spec/web.md:12-12, apps/api/test/infrastructure/http/server.integration.test.ts:98-111
Implementation Details
The HealthRouter mounts the health endpoints within the API's global AppRouter. The logic is encapsulated in the HealthService, which maintains internal state via start(), stop(), and setReady() methods.
Dependency Monitoring
The HealthService specifically monitors the database connectivity. A failing DB ping results in the checks.db field being marked as degraded and the overall service status moving to degraded.
Sources: apps/api/spec/health.md:19-20, apps/api/test/modules/health/application/health.service.test.ts:46-53
Conclusion
The Health Probes & Monitoring system provides automated validation for both the API and Web components. By implementing standard Kubernetes-style probes, it allows infrastructure to manage service lifecycle based on real-time process health and database availability.