Documentation
Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.
A gRPC monitor calls the standard gRPC health-checking service on your server — one unary Check on grpc.health.v1.Health — and records what came back. SERVING means up. NOT_SERVING means the server itself says it is not ready, which is a very different signal from a dead port.
What It Is For
A backend that only speaks gRPC
An internal service with no HTTP surface at all: no URL to request, no page to load, nothing a browser could open. The health service is the one thing it exposes that answers a yes-or-no question, and this monitor asks it.
The same health check your orchestrator already makes
If your pods have a gRPC readiness or liveness probe, the server already implements grpc.health.v1.Health. This monitor makes the same call from outside your cluster, so you see what Kubernetes sees, plus everything between you and the cluster that Kubernetes never touches.
One service inside a server that hosts several
The health protocol is per-service: a process can report orders.v1.Orders as serving while billing.v1.Billing is not. Give the monitor a service name and it asks about that one service, so a partly broken process is a red monitor instead of a green one.
Services that are reachable only from inside
Most gRPC lives on a private network and is never exposed to the internet. A private probe runs gRPC checks too, so you can monitor a service in your own cluster without opening a port to the world.
What It Is Not For
The monitor makes exactly one call, and it is always the health call. It is not a gRPC client for your own methods:
| You want to know | Use instead |
|---|---|
| Is my REST or JSON API answering? It speaks HTTP, not gRPC, and a health call to it goes nowhere | HTTP / HTTPS monitor |
| Is the port open at all? Your server has no health service registered, so there is nothing for a gRPC check to call | TCP monitor on the gRPC port |
| When does the certificate on my TLS gRPC endpoint expire? The health call never looks at the certificate, only at whether the handshake worked today | TLS/SSL certificate monitor |
| Does a sequence of calls still work end to end, with a value from one call used in the next? | API check monitor, which chains requests and passes values between them |
Does my own RPC return the right data? PingZen calls Check and nothing else — it has no copy of your protobufs and cannot invoke your methods | A heartbeat monitor, called by a job of yours that makes the real call |
What the Check Does
- Works out the target from the address, adding port
50051if you did not give one. - Opens a channel — with TLS if you turned it on, plain HTTP/2 otherwise. Channels are pooled and reused between checks, so the connection is normally set up once, not on every check.
- Calls
Checkongrpc.health.v1.Health, passing your service name, with the monitor’s timeout as the call deadline. - Turns the serving status — or the gRPC error — into a check result.
The numeric code is stored with every check and returned by the API: the serving-status number when the server answered the health call, the gRPC status code when the call itself failed. What you read on the monitor page is the message next to it, such as “Service is NOT_SERVING” or “Health check not implemented by service”.
The recorded response time covers the call, including connecting when a new connection is needed. Once the connection is warm, it is the round trip of the health call itself.
The Service Name
The health protocol takes a service name, and an empty name is meaningful: it asks for the health of the whole server. That is what the monitor sends when you leave the field blank, and for most servers it is the right choice.
Fill the field in only with a name the server actually registered — your own fully-qualified service, such as orders.v1.Orders. A name the server does not know is not an error on your side of the wire: the server answers politely with SERVICE_UNKNOWN, and the monitor treats that as a failure, because a monitor that cannot name the thing it is watching is not watching anything.
The grey example text in the form is only an example. Copying it, or any other name your server did not register, gives you a permanently red monitor on a perfectly healthy service.
TLS and Client Certificates
TLS is a single switch: Use TLS on the monitor. On it, the connection uses TLS and the server certificate is verified against the system trust store; off, the connection is plain HTTP/2 with no encryption.
Two things about that are worth knowing before you debug a red monitor:
- The address scheme does not turn TLS on. Writing
grpcs://selects the gRPC monitor type and sets the host and port, and that is all it does. If the switch is off, the check still connects in plain text and your TLS server will refuse it. Set the switch. - There is no field for a custom CA. Certificates are verified against the public trust store, so a server with a self-signed certificate or a private internal CA is not trusted and the connection fails. For such endpoints, monitor without TLS from inside the network with a private probe.
Mutual TLS is a half-finished feature. The checker supports a client certificate and key, and uses them when they are present, but no part of the interface, the REST API or the MCP tools can set them — so in practice an endpoint that requires a client certificate cannot be monitored today. It fails with “Authentication required (missing credentials)” or “Permission denied (check mTLS certificates)”, both red.
Status Logic
A gRPC monitor has no degraded state. Every check ends up up, down or timed out.
| What the server answered | Status |
|---|---|
| SERVING | UP |
| NOT_SERVING — the server is alive and says it is not ready to serve | DOWN |
| SERVICE_UNKNOWN — the server has a health service but no such service name | DOWN |
| UNIMPLEMENTED — the server does not implement the health service at all ("Health check not implemented by service") | DOWN |
| UNAVAILABLE — the connection could not be established ("Service unavailable (connection failed)") | DOWN |
| UNAUTHENTICATED or PERMISSION_DENIED — the endpoint wants credentials the monitor cannot send | DOWN |
| RESOURCE_EXHAUSTED, INTERNAL or any other gRPC error code | DOWN |
| The name did not resolve, the connection was refused, or anything else went wrong before an answer | DOWN |
| DEADLINE_EXCEEDED — no answer within the monitor's timeout | TIMEOUT |
Note the one case that differs from HTTP monitoring: a rate limit here is RESOURCE_EXHAUSTED and counts as down. An HTTP 429 makes a monitor DEGRADED and costs no uptime; the gRPC equivalent has no such treatment.
Down and timeout both count as downtime and both open an incident — after the confirmation threshold, three consecutive failing checks by default.
Configuration
Address
Host and port, as api.example.com:50051. A grpc:// or grpcs:// scheme is accepted and stripped, IPv6 goes in brackets as [2001:db8::1]:50051, and a bare host with no port becomes port 50051. An http:// or https:// URL is accepted too: only its host and port survive (https:// defaults to 443, http:// to 80) and any path is dropped, because gRPC connects to a host and port rather than to a URL. The scheme never decides TLS — the TLS switch does.
gRPC Service
The service name to ask about, up to 255 characters. Empty means the whole server, which is the sensible default. Only put a name here if the server registered exactly that name.
Use TLS
Off by default. On, the connection is TLS and the server certificate is checked against the public trust store. Off, it is plain HTTP/2. This switch is the only thing that decides it.
Timeout
Five seconds by default, and it is the deadline on the health call. A server that answers slower than this records a timeout, not a slow success.
Interval
Sixty seconds by default. gRPC has no protocol-specific minimum — a health call is cheap, and the connection is reused, so a short interval costs your server very little.
There is no method box on the form. The check always calls Check, because that and Watch are the only methods the health protocol defines, and calling a method of your own would need a copy of your protobuf descriptors.
Key Features
- The standard
grpc.health.v1health-checking protocol, the same one Kubernetes probes use - Per-service health, or the whole server when the service name is left empty
- Plain or TLS connections, with pooled channels so repeated checks do not re-handshake
- Every gRPC status code turned into a readable message — not serving, unknown service, no health service, unavailable, unauthenticated
- Runs from PingZen regions or from a private probe inside your own network
Common Questions
What protocols can I monitor?
PingZen supports 23 protocols: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, TLS/SSL certificates, Email (SMTP/IMAP/POP3), FTP/FTPS, DNSBL, PageSpeed, SOCKS5, MTProxy, API Check, and Transaction. You can monitor websites, APIs, servers, databases, and any network service.
How fast can I get alerts?
Telegram alerts are delivered within 1-2 seconds of detection. Slack and Discord notifications arrive almost instantly. You can configure multiple alert channels for redundancy.
Can I organize monitors by project?
Yes! PingZen supports workspaces, which let you organize monitors by project, environment, or team. Each workspace can have its own alert configurations and team members.
Is there an API for automation?
Absolutely. PingZen provides a full REST API with OpenAPI documentation. You can create, update, and delete monitors programmatically.
How do status pages work?
Status pages are public, branded pages showing your services' uptime. You can display real-time status and allow customers to subscribe for updates.
What happens if I reach my monitor limit?
We'll notify you when approaching your limit. You can pause some monitors or contact us for increased capacity. We never stop monitoring without warning, ensuring your critical services stay protected.
Ready to stop missing downtime?
Join thousands of teams who trust PingZen. Setup takes 30 seconds.