@PLUGIN@ health checks
==============

The @PLUGIN@ plugin registers the `pull-replication-outstanding-tasks`
healthcheck. This check will mark a gerrit instance as healthy upon
startup only when the node has caught up with all the outstanding
pull-replication tasks. The goal is to mark the node as healthy when it
is ready to receive write traffic. "Caught up" means:

- All pending & in-flight replication tasks across all sources (or
across a configurable set of repos) have completed
- There are no queued replication tasks pending and the above condition
lasts for at least N seconds (configurable)

See [Healthcheck based on replication tasks](https://issues.gerritcodereview.com/issues/312895374) for more details.

**It is worth noting that once the healthcheck eventually succeeds and
the instance is marked healthy, the check is then skipped (ie any
subsequent invocations will always mark the instance as healthy
irrespective of any pending or inflight tasks being present).**

Health check configuration
--------------------------

The configuration of the health check is split across two files.
- The "standard" properties commonly available to all other checks
of the `healthcheck` plugin. These are set in the `healthcheck` plugin's
[config file](https://gerrit.googlesource.com/plugins/healthcheck/+/refs/heads/master/src/main/resources/Documentation/config.md#settings).
- Settings specific to the check are set in the plugin's [config file](./config.md#file-pluginconfig).


The health check can be configured as follows:
- `healthcheck.@PLUGIN@-outstanding-tasks.projects`: The repo(s) that
the health check will track outstanding replication tasks against.
Multiple entries are supported. If not specified, all the outstanding
replication tasks are tracked.
- `healthcheck.@PLUGIN@-outstanding-tasks.periodOfTime`: The time for
which the check needs to be successful, in order for the instance to be
marked healthy. If the time unit is omitted it defaults to milliseconds.
Values should use common unit suffixes to express their setting:

* ms, milliseconds
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours

Default is 10s.

This example config will report the node healthy when there are no
pending tasks for the `foo` and `bar/baz` repos continuously for a
period of 5 seconds after the plugin startup.
```
[healthcheck "pull-replication-tasks"]
    projects = foo
    projects = bar/baz
    periodOfTime = 5 sec
```

Useful information
------------------

- The health check is registered only when the [healthcheck](https://gerrit.googlesource.com/plugins/healthcheck) plugin
is installed. If the `healthcheck` plugin is not installed, then the
check registration is skipped during load of the pull-replication
plugin.

> **Note** when the @@PLUGIN@@ plugin is installed as a lib (see [extension-point.md](extension-point.md)),
> then the healthcheck plugin jar should also be present in the `lib` directory,
> for the check registration to work.

- Because the pull-replication healthcheck depends on the `healthcheck` plugin, renaming/removing the `healthcheck`
jar file is not supported during runtime. Doing so can lead to unpredictable behaviour of your gerrit instance.