gRPC Monitoring: A Practical Guide for Small SaaS Teams
Key takeaways
- HTTP uptime checks miss gRPC failures because gRPC status codes travel in HTTP/2 trailers, not response headers, so a 200 OK can hide 100% INTERNAL errors.
- Implement the grpc.health.v1 protocol with Check for point-in-time polling and Watch for streaming status updates, probing named services rather than the empty default.
- Page on server-caused codes like UNAVAILABLE, DEADLINE_EXCEEDED, and INTERNAL; ignore client-caused codes like INVALID_ARGUMENT and NOT_FOUND, but watch UNAUTHENTICATED spikes.
- Unary health checks can pass while streams are broken, so streaming services need probes that open a real bidirectional call with heartbeat messages and idle timeouts.
- Behind a load balancer, run one external probe through the ingress and one internal probe bypassing it, alerting only when both agree.
If your Pingdom or Statuspage check hits a URL and shows green, your gRPC service can still be failing customers right now. Real gRPC monitoring means protocol-level health checks, status-code-based alerting, and streaming awareness, not HTTP pings. This guide shows what to monitor, which codes should page you, and how to pick a tool that understands gRPC.
grpc monitoring
gRPC monitoring means probing your services at the protocol level: sending real RPCs over HTTP/2, checking the grpc.health.v1 health-check protocol, and reading gRPC status codes rather than just watching for a 200 response. A URL check tells you the port is open. It cannot tell you that Unavailable is spiking, that a streaming call stalls mid-stream, or that your health service reports NOT_SERVING while the homepage still loads.
That distinction matters because most HTTP-first tools treat a gRPC endpoint as a black box. For a deeper walkthrough of health checks over HTTP/2 and HTTP/3, see our guide to gRPC health monitoring.
Why doesn't standard HTTP monitoring work for gRPC endpoints?
Because gRPC rides on HTTP/2 and fails in ways a 200 OK never reveals. Your uptime check pings a URL, gets a green status code, and reports all systems operational while every RPC behind it is failing.
HTTP/2 and trailers: what a 200 OK hides
gRPC communicates status through HTTP trailers, not headers. The server sends a 200 OK first, then delivers the actual gRPC status code (OK, UNAVAILABLE, DEADLINE_EXCEEDED) in the trailer block after the body. Most HTTP-based uptime checkers never read trailers, so a service returning 100% INTERNAL errors still shows as up. Your monitoring says green; your customers say otherwise.
When an HTTP check gives you a false green
A /healthz endpoint on your API gateway can return 200 while the gRPC backend behind it is dead: broken service registration, a crashed pod the load balancer hasn't noticed, or a serialization change breaking every call. URL checks test reachability, not the protocol. That gap is exactly why protocol-level probes exist, and why the grpc.health.v1 standard matters. We break down how to implement it in our guide to the grpc.health.v1 standard.
What is the grpc.health.v1 health-check protocol and how do you implement it?
grpc.health.v1 is the standard health-check service in the gRPC spec. Instead of probing a URL and assuming a 200 means healthy, your monitor makes an actual RPC and reads back a serving status. Most HTTP checks can't do this, which is why a gRPC service can fail while your Pingdom-style monitor stays green.
The Check and Watch RPCs
The protocol defines two methods. Check is a unary RPC: the monitor sends a HealthCheckRequest and gets a HealthCheckResponse with a status of UNKNOWN, SERVING, or NOT_SERVING. Watch is server-streaming: the client subscribes and receives an update every time the status changes, so you can page on transitions rather than polling. Treat NOT_SERVING the way you'd treat a 5xx, and note that an unimplemented method or a DEADLINE_EXCEEDED on the health call itself is also a failure signal, not a probe to ignore. The full list of gRPC status codes lives in the official status code reference.
Serving statuses and per-service health
The HealthCheckRequest carries an optional service field, so one health endpoint can report per-service status: database-backed API SERVING, background worker NOT_SERVING. Implement it with the built-in health library in grpc-go, grpc-java, or grpcio, register each service by name, and wire your probes to check the specific service name rather than the empty default. That granularity is what lets a status page show partial degradation instead of a blanket outage, and it's the difference between paging your on-call for a worker blip versus a real API incident. StatusPulse's protocol-level probes target named services this way; the gap to be honest about is that our free tier caps you at 5 probes, so a large service mesh will need the Starter plan or a self-hosted option like Uptime Kuma. For teams keeping customer-facing pages in the EU, see our note on EU data residency for monitoring tools.
How do you monitor gRPC streaming calls differently from unary RPCs?
A unary health check only proves the server accepts a request and sends one response back. Streams fail differently: a client or server stream can hang mid-call, a bidi stream can stop delivering messages in both directions, and flow-control backpressure can silently stall a connection that still looks "open". None of these show up as a failed unary RPC.
Why a unary health check can pass while streams are broken
A grpc.health.v1 check returns SERVING without opening a stream, so a proxy that kills long-lived connections, a broken load balancer idle timer, or a dead write path can all hide behind a green unary probe. If your product depends on streaming, a passing health check is a false positive.
Practical stream probes: heartbeat messages and idle timeouts
Probe a real stream: open a bidirectional call on a schedule, send a heartbeat message, and require an echo within a timeout. Set idle timeouts so a stalled stream fails the probe instead of waiting forever. The same logic applies to WebSockets, which we cover in our deep dive on WebSocket monitoring.
Which gRPC metrics matter most: latency, error codes, or in-flight requests?
Track error codes first. A gRPC call that returns UNAVAILABLE or DEADLINE_EXCEEDED is a customer-visible failure regardless of what your HTTP uptime check says, because gRPC status codes travel in HTTP/2 trailers that arrive after the body, not in the response headers most monitoring tools read (gRPC over HTTP/2 spec).
Latency comes second, and measure it at the p95 and p99, not the average. One slow dependency behind a fast median will hide until it pages you.
In-flight requests matter least for a small team, but a sustained climb without a matching traffic climb is your earliest signal of a stuck connection pool or a deadlock.
The catch: most probe tools only see trailers if they speak gRPC natively. A plain HTTP check on your health endpoint misses all three metrics, which is why protocol-level probes exist.
What gRPC status codes should trigger alerts versus pass silently?
Most gRPC failures never touch HTTP status codes, so your alerting has to key off gRPC status codes instead. The split is simple: codes caused by your server's health mean an outage, codes caused by the caller mean normal traffic.
| Code | Meaning | Alert? |
|---|---|---|
UNAVAILABLE | Server can't handle the call | Yes, page on-call |
DEADLINE_EXCEEDED | Server too slow or hung | Yes, page |
INTERNAL / UNKNOWN | Server-side bug | Yes, page |
RESOURCE_EXHAUSTED | Quota or rate limit hit | Degraded, warn only |
INVALID_ARGUMENT | Client sent bad input | No |
NOT_FOUND | Client asked for a missing resource | No |
UNAUTHENTICATED | Client credentials missing/expired | No |
CANCELLED | Client hung up | No |
Two edge cases deserve attention. A spike in UNAUTHENTICATED can mean your auth service is broken even though the code is client-caused, so watch the rate, not just the code. And RESOURCE_EXHAUSTED at sustained high volume often means you're shedding paying customers' requests, which is a capacity incident even though nothing is "down."
How do you evaluate gRPC monitoring tools for your stack?
Most "gRPC support" in monitoring tools is an HTTP/2 endpoint that returns 200. That tells you the port is open, not that your service can answer a grpc.health.v1/Check call with SERVING. If the tool cannot speak the protocol, it will page you on a dead port and stay silent when your service is wedged.
A 6-point checklist for gRPC monitoring tools
- Native health checks: does it implement
grpc.health.v1, or just hit a URL? - Status-code alerting: can you page on UNAVAILABLE and DEADLINE_EXCEEDED while ignoring INVALID_ARGUMENT?
- Streaming probes: can it open a server-streaming call and alert if the stream stalls or closes early?
- TLS and reflection: can it connect to TLS endpoints and discover services without you hand-writing descriptors?
- Alert routing: does it reach PagerDuty, Slack, or webhooks in under a minute?
- Status page included: can customers see incidents without a second subscription?
How the tools line up, including where StatusPulse falls short
UptimeRobot, Hyperping, and Better Stack are strong on HTTP probes and alerting, but none publishes documented protocol-level gRPC health checking as a first-class probe type. Atlassian Statuspage handles communication, not probing. StatusPulse runs real protocol-level probes rather than URL checks, which covers the checklist's first two points, and bundles a status page from $5/mo. Where it falls short: streaming-call probes and service reflection are not there yet, so for stream-heavy services you will still need a probe you run yourself. Kubernetes users can partially sidestep tooling gaps entirely: the gRPC health probe documentation shows kubelet calling grpc.health.v1 natively, which covers in-cluster liveness even if your external monitoring does not.
How do you monitor gRPC services behind an ingress or load balancer?
When gRPC sits behind Envoy, NGINX, or a cloud load balancer, your probe results describe the LB, not your services. A load balancer returns 200 OK or a healthy gRPC status as long as its own listener is up, even if every backend pod behind it is crashing. That is the blind spot: HTTP checks against the ingress tell you the front door opens, nothing about the rooms inside.
Why the LB can be healthy while backends are dead
Most load balancers pass through health-check results from their own probes, but those probes often use different endpoints, intervals, or thresholds than yours. Envoy can report upstream health per cluster, so probe the gRPC service directly through the ingress with the real grpc.health.v1 check, not a plain HTTP GET on the port.
Practical setup: run one external probe through the LB (catches routing and TLS failures) plus one internal probe bypassing it (catches dead backends). Alert only when both agree, which cuts the false positives that make on-call ignore downtime alerts. StatusPulse's protocol-level probes work for the external leg; for the internal leg you may still need a self-hosted probe inside the cluster, since most hosted monitors cannot reach private endpoints.
FAQ
Can Pingdom or UptimeRobot monitor gRPC endpoints?
Not at the protocol level. They run HTTP checks against a URL, so they see a 200 response and report green even when every RPC behind it fails. Because gRPC status codes travel in HTTP/2 trailers, an HTTP-first checker cannot see UNAVAILABLE or DEADLINE_EXCEEDED. You need a tool that sends real gRPC probes and reads the status codes back.
Does gRPC use HTTP/2 and can I health-check it over HTTP?
Yes, gRPC rides on HTTP/2, and the status code arrives in the trailer block after the response body, not in the headers. That is why a plain HTTP GET on the port can return 200 while the service is broken. Health checking works when the probe speaks the protocol itself, calling grpc.health.v1/Check over HTTP/2 and reading the serving status.
What is the difference between grpc.health.v1 Check and Watch?
Check is a unary RPC: your monitor sends a request and gets one response with a status of UNKNOWN, SERVING, or NOT_SERVING. It is a point-in-time answer you poll on a schedule. Watch is server-streaming: the client subscribes once and receives an update every time the status changes, which lets you alert on transitions instead of polling.
How do I expose gRPC health checks in Kubernetes without false alarms?
Use the kubelet's native gRPC liveness and readiness probes, which call grpc.health.v1 directly, so a 200 from the ingress never masks a dead pod. Register each service by name in the health service and probe the specific name, not the empty default. Keep external probes separate so a routing failure and a backend failure are distinguishable rather than conflated.
What's the cheapest way to get gRPC monitoring plus a status page for a small SaaS?
StatusPulse bundles protocol-level gRPC probes with a status page from $5/mo, though the free tier caps you at 5 probes and streaming probes are not there yet. Self-hosted Uptime Kuma costs nothing but requires you to run it yourself. Kubernetes-native health probes cover in-cluster liveness for free, leaving only the external probe to buy or build.