# health checks

## Summary

This generates a health check request from the sidecar corresponding the cluster object's domain at the configured interval, path, and any other options specified to the upstream server being referenced by the cluster object. It uses the response to this request to determine upstream service health as configured by the `healthy_threshold` and `unhealthy_threshold` values.

If the cluster is pointing at another sidecar in the mesh, it is recommended (but not required) to set the [health check filter](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/filters/http#health-check) on the corresponding upstream sidecar's ingress listener so that it can distinguish the difference between the health check and a general request. Otherwise, the upstream will treat this health check request as any other request at the configured `path`.

### Example object

```javascript
{
  "timeout_msec": 1000,
  "interval_msec": 60000,
  "interval_jitter_msec": 1000,
  "unhealthy_threshold": 3,
  "healthy_threshold": 3,
  "health_checker": {
    "http_health_check": {
      "path": "/health"
    }
  }
}
```

### Fields

#### `timeout_msec`

TimeoutMsec is the time to wait for a health check response. If the timeout is reached without a response, the health check attempt will be considered a failure. This is a required field and must be greater than 0.

#### `interval_msec`

IntervalMsec is the interval between health checks. Note that the first round of health checks will occur during startup before any traffic is routed to a cluster. This means that the [`no_traffic_interval_msec`](#notrafficintervalmsec) value will be used as the first interval of health checks.

#### `interval_jitter_msec`

IntervalJitterMsec is an optional jitter amount that is added to each interval value calculated by the proxy. If not specified, defaults to 0.

#### `unhealthy_threshold`

UnhealthyThreshold is the number of unhealthy health checks required before a host is marked unhealthy. Note that for *http* health checking if a host responds with 503 this threshold is ignored and the host is considered unhealthy immediately.

#### `healthy_threshold`

HealthyThreshold is the number of healthy health checks required before a host is marked healthy. Note that during startup, only a single successful health check is required to mark a host healthy.

#### `reuse_connection`

ReuseConnection determines whether to reuse a health check connection between health checks. Default is true.

#### `no_traffic_interval_msec`

NoTrafficIntervalMsec is a special health check interval that is used when a cluster has never had traffic routed to it. This lower interval allows cluster information to be kept up to date, without sending a potentially large amount of active health checking traffic or no reason. Once a cluster has been used for traffic routing, The proxy will shift back to using the standard health check interval that is defined. Note that this interval takes precedence over any other. Defaults to 60s.

#### `unhealthy_interval_msec`

UnhealthyIntervalMsec is a health check interval that is used for hosts that are marked as unhealthy. As soon as the host is marked as healthy, the proxy will shift back to using the standard health check interval that is defined. This defaults to the same value as IntervalMsec if not specified.

#### `unhealthy_edge_interval_msec`

UnhealthyEdgeIntervalMsec is a special health check interval that is used for the first health check right after a host is marked as unhealthy. For subsequent health checks the proxy will shift back to using either "unhealthy interval" if present or the standard health check interval that is defined. Defaults to the same value as UnhealthIntervalMsec if not specified.

#### `healthy_edge_interval_msec`

HealthyEdgeIntervalMsec is a special health check interval that is used for the first health check right after a host is marked as healthy. For subsequent health checks the proxy will shift back to using the standard health check interval that is defined. Defaults to the same value as IntervalMsec if not specified

#### `health_checker`

Defines the types of health checking to use, options : `http_health_check` and `tcp_health_check`. An example of an http health check could be:

```javascript
{
  ...,
  "health_checker": {
    "http_health_check": {
      "path": "/health"
    }
  }
}
```