Docs The addons agent grpccheck

grpccheck

Ask a gRPC server whether it is serving, through the standard grpc.health.v1 Health/Check call, with connect, TLS and the call timed apart.

A port that accepts connections says little about a gRPC server whose handlers are stuck. This check makes the call your load balancer makes: one grpc.health.v1.Health/Check over HTTP/2, and it reads the serving status from the answer.

It runs on your own agents and on Pingtower’s servers as a hosted check.

Parameters

Parameter	Default	Meaning
`address`REQUIRED		`host:port`. There is no default port.
`service`		The service name to ask about. Empty asks about the server as a whole.
`tls`	`true`	Connect over TLS 1.2 or later. `false` speaks plain-text HTTP/2.
`server_name`	host from `address`	The TLS server name, when it differs from the host.
`max_rpc`		Call time above this is degraded.

On Pingtower’s servers, address may name only ports 80, 443, 8080, 8443, 9090 and 50051. Your own agent can name any port.

Status

The check is up when the server answers SERVING: serving, answered in 12ms. It is degraded when it answers SERVING slower than max_rpc.

It is down when:

the host does not resolve, the connection is refused or times out, or the TLS handshake fails;
the server answers something other than gRPC, such as server answered HTTP 404, not gRPC;
the call fails with a non-zero gRPC status;
the server answers NOT_SERVING, UNKNOWN or SERVICE_UNKNOWN, or does not know the named service.

Measurements

Key	Meaning
`dns_ms`	Resolution time, when `address` names a host rather than an IP
`connect_ms`	TCP connect time
`tls_ms`	TLS handshake time, when `tls` is on
`rpc_ms`	The health call itself
`total_ms`	The whole run
`serving_status`	Label: `serving`, `not_serving`, `unknown` or `service_unknown`

On your own agents the check needs addons agent 0.5.0 or later. On 0.4.0 a run can hang and never finish, so the check stops reporting instead of going down; upgrade the agent. An agent from before 0.4.0 reports it as an unknown addon.

Example

- id: orders-grpc
  addon: grpccheck
  interval: 30s
  with:
    address: orders.internal.acme.example:50051
    service: acme.orders.v1.Orders
    max_rpc: 200ms

A rule for it

{"name":"grpc-slow","match":{"tags":["addon:grpccheck"]},
 "conditions":[{"key":"rpc_ms","op":"gte","value":500}]}