Skip to main content
Lexicon
Lexicon
gRPC

gRPC

Difficulty: Intermediate
5 min read
Updated 2026-11-19

In plain English

Plain definition

gRPC is an open source RPC framework that lets a client call methods on a remote service through generated stubs, using Protocol Buffers over HTTP/2. It sets no deadline by default, so set one on every call, and check servers with the standard grpc.health.v1 health service.

gRPC is an open source remote procedure call framework: a client calls a method on a service running on another machine as if it were a local function. Services and messages are defined in a .proto file, Protocol Buffers carry the data by default, and calls travel over HTTP/2. The constraint that matters most in operations is that gRPC sets no deadline unless the client asks for one, so a call to a stuck server can wait forever. Set a deadline on every call, and check a server with its standard health service rather than an HTTP request.

gRPC in plain English

You describe a service once, as methods with their request and response messages. The protoc compiler and a gRPC plugin generate a client stub and server code in each language you use, so a Go client can call a Java server without either side writing networking code.

How it works on the wire

Each call is an HTTP/2 POST. The :path header names the method as /package.Service/Method, the content type is application/grpc, and the client’s deadline, if it set one, travels in a grpc-timeout header. The server sends its messages and then trailers carrying grpc-status and an optional message. The status always arrives in the trailers, even when the call succeeded.

A method takes one of four shapes: unary (one request, one response), server streaming, client streaming or bidirectional streaming. Message order is kept within a single call. Many calls share one HTTP/2 connection at once, through a client-side channel that holds the connection to a host and port.

Why admins care about deadlines and status codes

A call ends with one of seventeen status codes, and they tell you where to look:

  • DEADLINE_EXCEEDED means the client stopped waiting. For a call that changes state, the server may still have finished the work.
  • UNAVAILABLE is usually transient and can be retried with backoff, but retrying an operation that is not idempotent can repeat it.
  • UNIMPLEMENTED means the server does not implement that method or has not enabled it.
  • INVALID_ARGUMENT, NOT_FOUND, FAILED_PRECONDITION and a few others are never produced by the gRPC library itself, so seeing one means the application returned it.

When a deadline passes, the server cancels the call with CANCELLED, but the application must stop any work it started. Cancelling does not roll back changes already made.

Where it fits between clients, proxies and load balancers

Because one HTTP/2 connection carries many calls, a layer 4 load balancer, which only copies bytes between a client connection and one backend connection, sends every call on that connection to the same backend. A layer 7 proxy can spread the streams from one client across several backends. The alternative is client-side load balancing, where the client knows the backends and picks one per call. Why gRPC traffic piles onto one backend behind a layer 4 proxy, and how to fix it covers the options in depth.

An example health check with grpcurl

gRPC defines a standard health service, grpc.health.v1.Health, with a Check method and a streaming Watch method. An empty service name asks about the whole server. With grpcurl, against a server listening without TLS on port 50051, these read-only calls list the services and ask for overall health:

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

A healthy server answers with a status of SERVING; one that is up but not ready answers NOT_SERVING. Asking about a service name the server has not registered returns the gRPC status NOT_FOUND. Drop -plaintext for a server whose TLS certificate the machine already trusts.

Two things trip this up. grpcurl learns the API through server reflection, which is not switched on by default; without it, pass the .proto files with -import-path and -proto. And the health service only reports what the application tells it, so a server that never updates its status can report SERVING while broken.

The misconception that a 200 means success

A failed gRPC call normally still comes back with HTTP status 200. The real result is the grpc-status trailer. A proxy, access log or dashboard that only counts HTTP status codes will show a service returning errors as healthy. Count gRPC status codes instead, and treat a missing trailer as a failure.

Keepalive is not a health check either. It sends HTTP/2 PING frames to keep a connection open and spot a dead one, and says nothing about whether the service can do any work.

See also

  • Protocol Buffers, the default interface definition language and message format.
  • Server reflection, which lets tools discover a server’s API at run time.
  • Deadline propagation, passing a caller’s deadline on to downstream calls.
  • Kubernetes gRPC probes, stable since Kubernetes v1.27, which call the health service directly, over plaintext by default.

More on running gRPC services is collected under gRPC on KBY Technologies.

Learn more from the gRPC project

  • gRPC, Introduction to gRPC and Core concepts, architecture and lifecycle (grpc.io).
  • gRPC, Status Codes, Deadlines, Health Checking and Reflection guides (grpc.io).
  • gRPC over HTTP2 and the GRPC Health Checking Protocol, in the grpc/grpc repository.
  • The grpcurl README, and the Kubernetes page on configuring liveness, readiness and startup probes.

Before calling a gRPC service down

Ask the instance, not the proxy: run the health Check against it, read the grpc-status the client logged, and see whether the client set a deadline. A call that hangs with no deadline, or a dashboard that shows only 200s, is a client or monitoring fault rather than an outage. None of these checks change anything.

About this page

Credited to

Dates

Published

Corrections

No corrections are listed for this page. Some review sweeps corrected pages without naming each one; those are in the corrections log.

Was this useful?

Reports go to the site owner and are used to correct pages. Corrections are listed at /corrections.