Document metrics
Change-Id: Iebf3b09b99b0d6bb62c7570c860fe0a1b4025e30
diff --git a/src/main/resources/Documentation/metrics.md b/src/main/resources/Documentation/metrics.md
new file mode 100644
index 0000000..d957574
--- /dev/null
+++ b/src/main/resources/Documentation/metrics.md
@@ -0,0 +1,90 @@
+Metrics
+=======
+
+The @PLUGIN@ plugin reports the status of its internal components
+to Gerrit metric system.
+
+The metrics are all prefixed with @PLUGIN@ and then divided in groups,
+depending on the component involved.
+
+### plugins/@PLUGIN@/events
+
+This prefix represents the component involved in the processing of incoming
+ref-update events from Gerrit or other event-broker sources.
+
+- `queued_before_startup` Counter of the number of events that have been received
+ when the plugin was still in its starting phase and not ready yet to process events.
+
+### plugins/@PLUGIN@/tasks/<metric>/<source>
+
+This prefix represents the tasks scheduling and execution system, also
+known as _replication queue_. The replication task represents one operation
+performed against a Git repository from a remote source. The task may involve
+one or more refs.
+
+The `<metric>` field can have one of the values described here below,
+while the `<source>` represent the replication source endpoint.
+
+> Bear in mind that the _replication queue_ is a lot more than a simple
+> queueing system, as it contains the logic for selecting, merging, retrying
+> and cancelling incoming tasks.
+
+- `scheduled`: (counter) number of tasks triggered and scheduled for
+ execution.
+
+- `started`: (counter) number of tasks started.
+
+- `rescheduled`: (counter) number of tasks re-scheduled for execution.
+
+- `cancelled`: (counter) number of tasks that were previously scheduled
+ and then cancelled before being executed.
+
+- `failed`: (counter) number of tasks executed but failed altogether or
+ partially. A total failure is when the entire operation returned an
+ error and none of the operations took place; a partial failure is when
+ some of the operations in the tasks succeeded but other failed.
+
+- `retrying`: (counter) number of tasks being retired for execution.
+
+- `not_scheduled`: (counter) number of tasks which have been discarded before
+ being executed, because redundant (duplicate of existing scheduled tasks)
+ or not needed anymore (e.g. ref updated already by other means or other
+ checks)
+
+- `completed`: (counter) number of tasks completed successfully.
+
+- `merged`: (counter) number of tasks not being executed because they had
+ been consolidated with an existing scheduled task.
+
+- `max_retries`: (counter) number of tasks that have reached their maximum
+ retry count but never succeeded.
+
+### plugins/@PLUGIN@
+
+- `apply_object_latency`: (timer) execution time statistics for the
+ synchronous replication using the _apply-object_ REST-API.
+
+- `apply_object_end_2_end_latency`: (timer) execution time statistics
+ for the end-2-end replication from when the event is triggered in
+ Gerrit until the successful execution of the synchronous replication
+ using the _apply-object_ REST-API.
+
+- `apply_object_max_api_payload_reached`: (counter) number of times that
+ the apply-object REST-API did fallback to the fetch REST-API because
+ it reached its maximum payload to transfer.
+
+- `replication_latency`: (timer) execution time statistics for the
+ synchronous replication using a _git fetch_.
+
+- `replication_end_2_end_latency`: (timer) execution time statistics
+ for the end-2-end replication from when the event is triggered in
+ Gerrit until the successful execution of the _git fetch_ for the
+ associated refs.
+
+- `replication_delay`: (timer) interval from when the ref-update event
+ is triggered to the start of the _git fetch_ command.
+
+- `replication_retries`: (counter) number of times that a replication task
+ has been retried.
+
+
