Merge branch 'docs-health-check-failure-examples' into 'master'

Docs health check failure examples

Closes #64193

See merge request gitlab-org/gitlab-ce!31945

1 files changed, 69 insertions, 13 deletions

diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md
index 333d2fb42b3..a3f4bc774ce 100644
--- a/doc/user/admin_area/monitoring/health_check.md
+++ b/doc/user/admin_area/monitoring/health_check.md
@@ -21,28 +21,71 @@ traffic until the system is ready or restart the container as needed.
 To access monitoring resources, the requesting client IP needs to be included in a whitelist.
 For details, see [how to add IPs to a whitelist for the monitoring endpoints](../../../administration/monitoring/ip_whitelist.md).
 
-## Using the endpoints
+## Using the endpoints locally
 
 With default whitelist settings, the probes can be accessed from localhost using the following URLs:
 
-- `http://localhost/-/health`
-- `http://localhost/-/readiness`
-- `http://localhost/-/liveness`
+```text
+GET http://localhost/-/health
+```
+```text
+GET http://localhost/-/readiness
+```
+```text
+GET http://localhost/-/liveness
+```text
+GET http://localhost/-/health
+```
+
+```text
+GET http://localhost/-/readiness
+```
 
-The first endpoint, `health`, only checks whether the application server is running. It does not verify the database or other services are running. A successful response will return a 200 status code with the following message:
+```text
+GET http://localhost/-/liveness
+```
+
+## Health
+
+Checks whether the application server is running. It does not verify the database or other services are running.
+
+```text
+GET /-/health
+```
+
+Example request:
+
+```sh
+curl 'https://gitlab.example.com/-/health'
+```
+
+Example response:
 
 ```text
 GitLab OK
 ```
 
-The readiness and liveness probes will provide a report of system health in JSON format.
+## Readiness
+
+The readiness probe checks whether the Gitlab instance is ready to use. It checks the dependent services (Database, Redis, Gitaly etc.) and gives a status for each.
+
+```text
+GET /-/readiness
+```
+
+Example request:
+
+```sh
+curl 'https://gitlab.example.com/-/readiness'
+```
 
-`readiness` probe example output:
+Example response:
 
 ```json
 {
    "db_check":{
-      "status":"ok"
+      "status":"failed",
+      "message": "unexpected Db check result: 0"
    },
    "redis_check":{
       "status":"ok"
@@ -65,7 +108,23 @@ The readiness and liveness probes will provide a report of system health in JSON
    }
 ```
 
-`liveness` probe example output:
+## Liveness
+
+The liveness probe checks whether the application server is alive. Unlike the [`health`](#health) check, this check hits the database.
+
+```text
+GET /-/liveness
+```
+
+Example request:
+
+```sh
+curl 'https://gitlab.example.com/-/liveness'
+```
+
+Example response:
+
+On success, the endpoint will return a valid successful HTTP status code, and a response like below.
 
 ```json
 {
@@ -90,10 +149,7 @@ The readiness and liveness probes will provide a report of system health in JSON
 }
 ```
 
-## Status
-
-On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint
-will return a valid successful HTTP status code, and a `success` message.
+On failure, the endpoint will return a `500` HTTP status code.
 
 ## Access token (Deprecated)