How to use HTTP/2 PING-based keepalives in gRPC.


How to use HTTP/2 PING-based keepalives in gRPC.


HTTP/2 PING-based keepalives are a way to keep an HTTP/2 connection alive even when there is no data being transferred. This is done by periodically sending a PING frame to the other end of the connection. HTTP/2 keepalives can improve performance and reliability of HTTP/2 connections, but it is important to configure the keepalive interval carefully.


TCP keepalive is a well-known method of maintaining connections and detecting broken connections. When TCP keepalive was enabled, either side of the connection can send redundant packets. Once ACKed by the other side, the connection will be considered as good. If no ACK is received after repeated attempts, the connection is deemed broken.

Unlike TCP keepalive, gRPC uses HTTP/2 which provides a mandatory PING frame which can be used to estimate round-trip time, bandwidth-delay product, or test the connection. The interval and retry in TCP keepalive don’t quite apply to PING because the transport is reliable, so they’re replaced with timeout (equivalent to interval * retry) in gRPC PING-based keepalive implementation.

How configuring keepalive affects a call

Keepalive is less likely to be triggered for unary RPCs with quick replies. Keepalive is primarily triggered when there is a long-lived RPC, which will fail if the keepalive check fails and the connection is closed.

For streaming RPCs, if the connection is closed, any in-progress RPCs will fail. If a call is streaming data, the stream will also be closed and any data that has not yet been sent will be lost.

Common situations where keepalives can be useful

gRPC HTTP/2 keepalives can be useful in a variety of situations, including but not limited to:

  • When sending data over a long-lived connection which might be considered as idle by proxy or load balancers.
  • When the network is less reliable (For example, mobile applications).
  • When using a connection after a long period of inactivity.

Keepalive configuration specification

OptionsAvailabilityDescriptionClient DefaultServer Default
KEEPALIVE_TIMEClient and ServerThe interval in milliseconds between PING frames.INT_MAX (Disabled)7200000 (2 hours)
KEEPALIVE_TIMEOUTClient and ServerThe timeout in milliseconds for a PING frame to be acknowledged. If sender does not receive an acknowledgment within this time, it will close the connection.20000 (20 seconds)20000 (20 seconds)
KEEPALIVE_WITHOUT_CALLSClientIs it permissible to send keepalive pings from the client without any outstanding streams.0 (false)N/A
PERMIT_KEEPALIVE_WITHOUT_CALLSServerIs it permissible to send keepalive pings from the client without any outstanding streams.N/A0 (false)
PERMIT_KEEPALIVE_TIMEServerMinimum allowed time between a server receiving successive ping frames without sending any data/header frame.N/A300000 (5 minutes)
MAX_CONNECTION_IDLEServerMaximum time that a channel may have no outstanding rpcs, after which the server will close the connection.N/AINT_MAX (Infinite)
MAX_CONNECTION_AGEServerMaximum time that a channel may exist.N/AINT_MAX (Infinite)
MAX_CONNECTION_AGE_GRACEServerGrace period after the channel reaches its max age.N/AINT_MAX (Infinite)

Language guides and examples

C++C++ ExampleC++ Documentation
GoGo ExampleGo Documentation
JavaJava ExampleJava Documentation
PythonPython ExamplePython Documentation

Additional Resources