summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDJ Mountney <david@twkie.net>2016-05-18 08:48:48 -0700
committerDJ Mountney <david@twkie.net>2016-05-18 11:43:16 -0700
commitb5552bc4e57f73a80e990ee4182fb48fa4851ad3 (patch)
treea2d1d5fa34d15d006e655056eb6acbc6a24900b9 /doc
parentda8ac1635f1c12e9455e7517bee29678c754d492 (diff)
downloadgitlab-ce-b5552bc4e57f73a80e990ee4182fb48fa4851ad3.tar.gz
Add health check feature documentation
Diffstat (limited to 'doc')
-rw-r--r--doc/README.md1
-rw-r--r--doc/monitoring/health_check.md57
-rw-r--r--doc/monitoring/img/health_check_token.pngbin0 -> 10884 bytes
3 files changed, 58 insertions, 0 deletions
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 00000000000..2daf8606b00
--- /dev/null
+++ b/doc/monitoring/img/health_check_token.png
Binary files differ