# grpccheck

Source: https://www.pingtower.com/docs/addons/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](/docs/service/checks/).

## Parameters

| Parameter | Default | Meaning |
| --- | --- | --- |
| `address`<span class="req">REQUIRED</span> | | `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](/docs/addons/install/#upgrading). An agent from before 0.4.0 reports it as an unknown addon.

## Example

```yaml
- 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

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