cpp/md_doc_health-checking.html - third_party/grpc - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.8.17"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>GRPC C++: GRPC Health Checking Protocol</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
 <link href="search/search.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="search/searchdata.js"></script>
 <script type="text/javascript" src="search/search.js"></script>
 <link href="doxygen.css" rel="stylesheet" type="text/css" />
 </head>
 <body>
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 <div id="titlearea">
 <table cellspacing="0" cellpadding="0">
  <tbody>
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">GRPC C++
    &#160;<span id="projectnumber">1.71.0</span>
    </div>
   </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.8.17 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 var searchBox = new SearchBox("searchBox", "search",false,'Search');
 /* @license-end */
 </script>
 <script type="text/javascript" src="menudata.js"></script>
 <script type="text/javascript" src="menu.js"></script>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 $(function() {
   initMenu('',true,false,'search.php','Search');
   $(document).ready(function() { init_search(); });
 });
 /* @license-end */</script>
 <div id="main-nav"></div>
 <!-- window showing the filter options -->
 <div id="MSearchSelectWindow"
      onmouseover="return searchBox.OnSearchSelectShow()"
      onmouseout="return searchBox.OnSearchSelectHide()"
      onkeydown="return searchBox.OnSearchSelectKey(event)">
 </div>

 <!-- iframe showing the search results (closed by default) -->
 <div id="MSearchResultsWindow">
 <iframe src="javascript:void(0)" frameborder="0"
         name="MSearchResults" id="MSearchResults">
 </iframe>
 </div>

 </div><!-- top -->
 <div class="PageDoc"><div class="header">
   <div class="headertitle">
 <div class="title">GRPC Health Checking Protocol </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p>Health checks are used to probe whether the server is able to handle rpcs. The client-to-server health checking can happen from point to point or via some control system. A server may choose to reply “unhealthy” because it is not ready to take requests, it is shutting down or some other reason. The client can act accordingly if the response is not received within some time window or the response says unhealthy in it.</p>
 <p>A GRPC service is used as the health checking mechanism for both simple client-to-server scenario and other control systems such as load-balancing. Being a high level service provides some benefits. Firstly, since it is a GRPC service itself, doing a health check is in the same format as a normal rpc. Secondly, it has rich semantics such as per-service health status. Thirdly, as a GRPC service, it is able reuse all the existing billing, quota infrastructure, etc, and thus the server has full control over the access of the health checking service.</p>
 <h1><a class="anchor" id="autotoc_md104"></a>
 Service Definition</h1>
 <p>The server should export a service defined in the following proto:</p>
 <div class="fragment"><div class="line">syntax = &quot;proto3&quot;;</div>
 <div class="line"> </div>
 <div class="line">package grpc.health.v1;</div>
 <div class="line"> </div>
 <div class="line">message HealthCheckRequest {</div>
 <div class="line">  string service = 1;</div>
 <div class="line">}</div>
 <div class="line"> </div>
 <div class="line">message HealthCheckResponse {</div>
 <div class="line">  enum ServingStatus {</div>
 <div class="line">    UNKNOWN = 0;</div>
 <div class="line">    SERVING = 1;</div>
 <div class="line">    NOT_SERVING = 2;</div>
 <div class="line">    SERVICE_UNKNOWN = 3;  // Used only by the Watch method.</div>
 <div class="line">  }</div>
 <div class="line">  ServingStatus status = 1;</div>
 <div class="line">}</div>
 <div class="line"> </div>
 <div class="line">service Health {</div>
 <div class="line">  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);</div>
 <div class="line"> </div>
 <div class="line">  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);</div>
 <div class="line">}</div>
 </div><!-- fragment --><p>A client can query the server’s health status by calling the <code>Check</code> method, and a deadline should be set on the rpc. The client can optionally set the service name it wants to query for health status.</p>
 <p>The server should register all the services manually and set the individual status, including an empty service name and its status. For each request received, if the service name can be found in the registry, a response must be sent back with an <code>OK</code> status and the status field should be set to <code>SERVING</code> or <code>NOT_SERVING</code> accordingly. If the service name is not registered, the server returns a <code>NOT_FOUND</code> GRPC status.</p>
 <p>The server should use an empty string as the key for server's overall health status, so that a client not interested in a specific service can query the server's status with an empty request. The server can just do exact matching of the service name without support of any kind of wildcard matching. However, the service owner has the freedom to implement more complicated matching semantics that both the client and server agree upon.</p>
 <p>A client can declare the server as unhealthy if the rpc is not finished after some amount of time. The client should be able to handle the case where server does not have the Health service.</p>
 <p>A client can call the <code>Watch</code> method to perform a streaming health-check. The server will immediately send back a message indicating the current serving status. It will then subsequently send a new message whenever the service's serving status changes. </p>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
 Generated on Thu Mar 13 2025 18:13:56 for GRPC C++ by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.17
 </small></address>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
	<meta http-equiv="X-UA-Compatible" content="IE=9"/>
	<meta name="generator" content="Doxygen 1.8.17"/>
	<meta name="viewport" content="width=device-width, initial-scale=1"/>
	<title>GRPC C++: GRPC Health Checking Protocol</title>
	<link href="tabs.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="jquery.js"></script>
	<script type="text/javascript" src="dynsections.js"></script>
	<link href="search/search.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="search/searchdata.js"></script>
	<script type="text/javascript" src="search/search.js"></script>
	<link href="doxygen.css" rel="stylesheet" type="text/css" />
	</head>
	<body>
	<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
	<div id="titlearea">
	<table cellspacing="0" cellpadding="0">
	<tbody>
	<tr style="height: 56px;">
	<td id="projectalign" style="padding-left: 0.5em;">
	<div id="projectname">GRPC C++
	<span id="projectnumber">1.71.0</span>
	</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.8.17 -->
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	var searchBox = new SearchBox("searchBox", "search",false,'Search');
	/* @license-end */
	</script>
	<script type="text/javascript" src="menudata.js"></script>
	<script type="text/javascript" src="menu.js"></script>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(function() {
	initMenu('',true,false,'search.php','Search');
	$(document).ready(function() { init_search(); });
	});
	/* @license-end */</script>
	<div id="main-nav"></div>
	<!-- window showing the filter options -->
	<div id="MSearchSelectWindow"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	onkeydown="return searchBox.OnSearchSelectKey(event)">
	</div>

	<!-- iframe showing the search results (closed by default) -->
	<div id="MSearchResultsWindow">
	<iframe src="javascript:void(0)" frameborder="0"
	name="MSearchResults" id="MSearchResults">
	</iframe>
	</div>

	</div><!-- top -->
	<div class="PageDoc"><div class="header">
	<div class="headertitle">
	<div class="title">GRPC Health Checking Protocol </div> </div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><p>Health checks are used to probe whether the server is able to handle rpcs. The client-to-server health checking can happen from point to point or via some control system. A server may choose to reply “unhealthy” because it is not ready to take requests, it is shutting down or some other reason. The client can act accordingly if the response is not received within some time window or the response says unhealthy in it.</p>
	<p>A GRPC service is used as the health checking mechanism for both simple client-to-server scenario and other control systems such as load-balancing. Being a high level service provides some benefits. Firstly, since it is a GRPC service itself, doing a health check is in the same format as a normal rpc. Secondly, it has rich semantics such as per-service health status. Thirdly, as a GRPC service, it is able reuse all the existing billing, quota infrastructure, etc, and thus the server has full control over the access of the health checking service.</p>
	<h1><a class="anchor" id="autotoc_md104"></a>
	Service Definition</h1>
	<p>The server should export a service defined in the following proto:</p>
	<div class="fragment"><div class="line">syntax = "proto3";</div>
	<div class="line"> </div>
	<div class="line">package grpc.health.v1;</div>
	<div class="line"> </div>
	<div class="line">message HealthCheckRequest {</div>
	<div class="line"> string service = 1;</div>
	<div class="line">}</div>
	<div class="line"> </div>
	<div class="line">message HealthCheckResponse {</div>
	<div class="line"> enum ServingStatus {</div>
	<div class="line"> UNKNOWN = 0;</div>
	<div class="line"> SERVING = 1;</div>
	<div class="line"> NOT_SERVING = 2;</div>
	<div class="line"> SERVICE_UNKNOWN = 3; // Used only by the Watch method.</div>
	<div class="line"> }</div>
	<div class="line"> ServingStatus status = 1;</div>
	<div class="line">}</div>
	<div class="line"> </div>
	<div class="line">service Health {</div>
	<div class="line"> rpc Check(HealthCheckRequest) returns (HealthCheckResponse);</div>
	<div class="line"> </div>
	<div class="line"> rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);</div>
	<div class="line">}</div>
	</div><!-- fragment --><p>A client can query the server’s health status by calling the <code>Check</code> method, and a deadline should be set on the rpc. The client can optionally set the service name it wants to query for health status.</p>
	<p>The server should register all the services manually and set the individual status, including an empty service name and its status. For each request received, if the service name can be found in the registry, a response must be sent back with an <code>OK</code> status and the status field should be set to <code>SERVING</code> or <code>NOT_SERVING</code> accordingly. If the service name is not registered, the server returns a <code>NOT_FOUND</code> GRPC status.</p>
	<p>The server should use an empty string as the key for server's overall health status, so that a client not interested in a specific service can query the server's status with an empty request. The server can just do exact matching of the service name without support of any kind of wildcard matching. However, the service owner has the freedom to implement more complicated matching semantics that both the client and server agree upon.</p>
	<p>A client can declare the server as unhealthy if the rpc is not finished after some amount of time. The client should be able to handle the case where server does not have the Health service.</p>
	<p>A client can call the <code>Watch</code> method to perform a streaming health-check. The server will immediately send back a message indicating the current serving status. It will then subsequently send a new message whenever the service's serving status changes. </p>
	</div></div><!-- contents -->
	</div><!-- PageDoc -->
	<!-- start footer part -->
	<hr class="footer"/><address class="footer"><small>
	Generated on Thu Mar 13 2025 18:13:56 for GRPC C++ by  <a href="http://www.doxygen.org/index.html">
	<img class="footer" src="doxygen.png" alt="doxygen"/>
	</a> 1.8.17
	</small></address>
	</body>
	</html>