From 50f57f5f202816f54f21134b92ce1523bbc54d26 Mon Sep 17 00:00:00 2001
From: zzak <zzakscott@gmail.com>
Date: Mon, 16 Jan 2023 11:41:12 +0900
Subject: [PATCH] [#46936] Add documentation for Rails::HealthController

Co-authored-by: Hartley McGuire <skipkayhil@gmail.com>
---
 guides/source/action_controller_overview.md | 20 +++++++++++++
 railties/lib/rails/health_controller.rb     | 31 ++++++++++++++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index b4273238a5c48..22ef1f6c27e18 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -15,6 +15,7 @@ After reading this guide, you will know:
 * How to stream data directly to the user's browser.
 * How to filter sensitive parameters, so they do not appear in the application's log.
 * How to deal with exceptions that may be raised during request processing.
+* About the built-in health check end-point useful for load balancers and uptime monitors.
 
 --------------------------------------------------------------------------------
 
@@ -1284,3 +1285,22 @@ via HTTPS, you should do so by enabling the [`ActionDispatch::SSL`][] middleware
 
 [`config.force_ssl`]: configuring.html#config-force-ssl
 [`ActionDispatch::SSL`]: https://api.rubyonrails.org/classes/ActionDispatch/SSL.html
+
+Built-in Health Check Endpoint
+------------------------------
+
+Rails also comes with a built-in health check endpoint that is reachable at the `/up` path. This endpoint will return a 200 status code if the app has booted with no exceptions, and a 500 status code otherwise.
+
+In production, many services are required to report their status upstream, whether it's to an uptime monitor that will page an engineer when things go wrong, or a load balancer or Kubernetes controller used to determine a pod's health. This health check is designed to be a one-size fits all that will work in many situations.
+
+While any newly generated Rails applications will have the health check at `/up`, you can configure the path to be anything you'd like in your "config/routes.rb":
+
+```ruby
+Rails.application.routes.draw do
+  get "healthz" => "rails/health#show"
+end
+```
+
+The health check will now be accessible via the `/healthz` path.
+
+NOTE: This endpoint is not designed to give the status of all of your service's dependencies, such as the database or redis cluster. It is also not recommended to use those for health checks, in general, as it can lead to situations where your application is being restarted due to a third-party service going bad. Ideally, you should design your application to handle those outages gracefully.
\ No newline at end of file
diff --git a/railties/lib/rails/health_controller.rb b/railties/lib/rails/health_controller.rb
index 83f4abf5879e1..b65eb7136fcdd 100644
--- a/railties/lib/rails/health_controller.rb
+++ b/railties/lib/rails/health_controller.rb
@@ -1,6 +1,35 @@
 # frozen_string_literal: true
 
-class Rails::HealthController < ActionController::Base # :nodoc:
+# Built-in Health Check Endpoint
+#
+# Rails comes with a built-in health check endpoint that is reachable at the
+# `/up` path. This endpoint will return a 200 if the app has booted with no
+# exceptions, otherwise a 500 status code will be returned.
+#
+# In production, many services are required to report their status upstream,
+# whether it's to an uptime monitor that will page an engineer when things go
+# wrong, or a load balancer or Kubernetes controller used to determine a pods
+# health. This health check is designed to be a one-size fits all that will work
+# in many situations.
+#
+# For any newly generated Rails applications it will be enabled by default, but
+# you can configure it anywhere you'd like in your "config/routes.rb":
+#
+# ```ruby
+# Rails.application.routes.draw do
+#   get "healthz" => "rails/health#show"
+# end
+# ```
+#
+# The health check will now be accessible via the `/healthz` path.
+#
+# NOTE: This endpoint is not designed to give the status of all of your
+# service's dependencies, such as the database or redis cluster. It is also not
+# recommended to use those for health checks, in general, as it can lead to
+# situations where your application is being restarted due to a third-party
+# service going bad. Ideally, you should design your application to handle those
+# outages gracefully.
+class Rails::HealthController < ActionController::Base
   rescue_from(Exception) { render_down }
 
   def show