From b5552bc4e57f73a80e990ee4182fb48fa4851ad3 Mon Sep 17 00:00:00 2001 From: DJ Mountney Date: Wed, 18 May 2016 08:48:48 -0700 Subject: [PATCH] Add health check feature documentation --- doc/README.md | 1 + doc/monitoring/health_check.md | 57 ++++++++++++++++++++++ doc/monitoring/img/health_check_token.png | Bin 0 -> 10884 bytes 3 files changed, 58 insertions(+) create mode 100644 doc/monitoring/health_check.md create mode 100644 doc/monitoring/img/health_check_token.png diff --git a/doc/README.md b/doc/README.md index e358da1c424..8aed060d247 100644 --- a/doc/README.md +++ b/doc/README.md @@ -41,6 +41,7 @@ - [Git LFS configuration](workflow/lfs/lfs_administration.md) - [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast. - [GitLab Performance Monitoring](monitoring/performance/introduction.md) Configure GitLab and InfluxDB for measuring performance metrics +- [Monitoring uptime](monitoring/health_check.md) Check the server status using the health check endpoint - [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md) Debug when Sidekiq appears hung and is not processing jobs - [High Availability](administration/high_availability/README.md) Configure multiple servers for scaling or high availability diff --git a/doc/monitoring/health_check.md b/doc/monitoring/health_check.md new file mode 100644 index 00000000000..bbfb63dd844 --- /dev/null +++ b/doc/monitoring/health_check.md @@ -0,0 +1,57 @@ +# Health Check +_**Note:** This feature was [introduced][ce-3888] in GitLab 8.8_ + +GitLab provides a health check endpoint for uptime monitoring on the `health_check` web +endpoint. The health check reports on the overall system status based on the status of +the database connection, the state of the database migrations, and the ability to write +and access the cache. This endpoint can be provided to uptime monitoring services like +[Pingdom][pindom], [Nagios][nagios-health], and [NewRelic][newrelic-health]. + +## Access Token + +A access token needs to be provided while accessing the health check endpoint. The current +accepted token can be found on the `admin/heath_check` page of your GitLab instance. + +![access token](img/health_check_token.png) + +The access token can be passed as a url parameter: + +`https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN` + +or as a http header: + +```bash +curl -H "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json +``` + +## Using the Endpoint + +Once you have the access token, health information can be retrieved as plain text, JSON, +or XML using the `health_check` endpoint: + +- `https://gitlab.example.com/health_check?token=ACCESS_TOKEN` +- `https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN` +- `https://gitlab.example.com/health_check.xml?token=ACCESS_TOKEN` + +You can also ask for the status of specific services: + +- `https://gitlab.example.com/health_check/cache.json?token=ACCESS_TOKEN` +- `https://gitlab.example.com/health_check/database.json?token=ACCESS_TOKEN` +- `https://gitlab.example.com/health_check/migrations.json?token=ACCESS_TOKEN` + +Example output: +```bash +curl -H "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json +{"healthy":true,"message":"success"} +``` + +## 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. Ideally your +uptime monitoring should look for the success message. + +[ce-3888]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3888 +[pingdom]: https://www.pingdom.com +[nagios-health]: https://nagios-plugins.org/doc/man/check_http.html +[newrelic-health]: https://docs.newrelic.com/docs/alerts/alert-policies/downtime-alerts/availability-monitoring diff --git a/doc/monitoring/img/health_check_token.png b/doc/monitoring/img/health_check_token.png new file mode 100644 index 0000000000000000000000000000000000000000..2daf8606b009aedda120af03baa13c36a195f07d GIT binary patch literal 10884 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 literal 0 HcmV?d00001