Add documentation for the metrics feature

Change-Id: Iddb2cb009a2a56287dd2085b81fbc1d836b1fab0

Documentation/dev-plugins.txt

@@ -2175,6 +2175,49 @@ public class S3LargeFileRepository extends S3Repository {
 }
 ----
 
+[[metrics]]
+== Metrics
+
+=== Metrics Reporting
+
+To send Gerrit's metrics data to an external reporting backend, a plugin can
+get a `MetricRegistry` injected and register an instance of a class that
+implements the `Reporter` interface from link:http://metrics.dropwizard.io/[
+DropWizard Metrics].
+
+Metric reporting plugin implementations are provided for
+link:https://gerrit.googlesource.com/plugins/metrics-reporter-jmx/[JMX],
+link:https://gerrit.googlesource.com/plugins/metrics-reporter-elasticsearch/[Elastic Search],
+and link:https://gerrit.googlesource.com/plugins/metrics-reporter-graphite/[Graphite].
+
+There is also a working example of reporting metrics to the console in the
+link:https://gerrit.googlesource.com/plugins/cookbook-plugin/+/master/src/main/java/com/googlesource/gerrit/plugins/cookbook/ConsoleMetricReporter.jave[
+cookbook plugin].
+
+=== Providing own metrics
+
+Plugins may provide metrics to be dispatched to external reporting services by
+getting a `MetricMaker` injected and creating instances of specific types of
+metric:
+
+* Counter
++
+Metric whose value increments during the life of the process.
+
+* Timer
++
+Metric recording time spent on an operation.
+
+* Histogram
++
+Metric recording statistical distribution (rate) of values.
+
+Plugin metrics are recorded under `plugins/${plugin-name}/${metric-name}`.
+
+See the replication metrics in the
+link:https://gerrit.googlesource.com/plugins/replication/+/master/src/main/java/com/googlesource/gerrit/plugins/replication/ReplicationMetrics.java[
+replication plugin] for an example of usage.
+
 [[account-patch-review-store]]
 == AccountPatchReviewStore
 

Documentation/index.txt

@@ -52,6 +52,7 @@
 . link:cmd-index.html[Command Line Tools]
 . link:config-plugins.html#replication[Replication]
 . link:config-plugins.html[Plugins]
+. link:metrics.html[Metrics]
 . link:config-reverseproxy.html[Reverse Proxy]
 . link:config-auto-site-initialization.html[Automatic Site Initialization on Startup]
 . link:pgm-index.html[Server Side Administrative Tools]

Documentation/metrics.txt

@@ -0,0 +1,103 @@
+= Gerrit Code Review - Metrics
+
+Metrics about Gerrit's internal state can be sent to external monitoring systems
+via plugins. See the link:dev-plugins.html#metrics[plugin documentation] for
+details of plugin implementations.
+
+== Metrics
+
+The following metrics are reported.
+
+=== General
+
+* `build/label`: Version of Gerrit server software.
+* `events`: Triggered events.
+
+=== Process
+
+* `proc/birth_timestamp`: Time at which the Gerrit process started.
+* `proc/uptime`: Uptime of the Gerrit process.
+* `proc/cpu/usage`: CPU time used by the Gerrit process.
+* `proc/num_open_fds`: Number of open file descriptors.
+* `proc/jvm/memory/heap_committed`: Amount of memory guaranteed for user objects.
+* `proc/jvm/memory/heap_used`: Amount of memory holding user objects.
+* `proc/jvm/memory/non_heap_committed`: Amount of memory guaranteed for classes,
+etc.
+* `proc/jvm/memory/non_heap_used`: Amount of memory holding classes, etc.
+* `proc/jvm/memory/object_pending_finalization_count`: Approximate number of
+objects needing finalization.
+* `proc/jvm/gc/count`: Number of GCs.
+* `proc/jvm/gc/time`: Approximate accumulated GC elapsed time.
+* `proc/jvm/thread/num_live`: Current live thread count.
+
+=== Caches
+
+* `caches/memory_cached`: Memory entries.
+* `caches/memory_hit_ratio`: Memory hit ratio.
+* `caches/memory_eviction_count`: Memory eviction count.
+* `caches/disk_cached`: Disk entries used by persistent cache.
+* `caches/disk_hit_ratio`: Disk hit ratio for persistent cache.
+
+=== HTTP
+
+* `http/server/error_count`: Rate of REST API error responses.
+* `http/server/success_count`: Rate of REST API success responses.
+* `http/server/rest_api/count`: Rate of REST API calls by view.
+* `http/server/rest_api/error_count`: Rate of REST API calls by view.
+* `http/server/rest_api/server_latency`: REST API call latency by view.
+* `http/server/rest_api/response_bytes`: Size of REST API response on network
+(may be gzip compressed) by view.
+
+=== Query
+
+* `query/query_latency`: Successful query latency, accumulated over the life
+of the process.
+
+=== SSH sessions
+
+* `sshd/sessions/connected`: Number of currently connected SSH sessions.
+* `sshd/sessions/created`: Rate of new SSH sessions.
+* `sshd/sessions/authentication_failures`: Rate of SSH authentication failures.
+
+=== SQL connections
+
+* `sql/connection_pool/connections`: SQL database connections.
+
+=== JGit
+
+* `jgit/block_cache/cache_used`: Bytes of memory retained in JGit block cache.
+* `jgit/block_cache/open_files`: File handles held open by JGit block cache.
+
+=== Git
+
+* `git/upload-pack/request_count`: Total number of git-upload-pack requests.
+* `git/upload-pack/phase_counting`: Time spent in the 'Counting...' phase.
+* `git/upload-pack/phase_compressing`: Time spent in the 'Compressing...' phase.
+* `git/upload-pack/phase_writing`: Time spent transferring bytes to client.
+* `git/upload-pack/pack_bytes`: Distribution of sizes of packs sent to clients.
+
+=== NoteDb
+
+* `notedb/update_latency`: NoteDb update latency by table.
+* `notedb/stage_update_latency`: Latency for staging updates to NoteDb by table.
+* `notedb/read_latency`: NoteDb read latency by table.
+* `notedb/parse_latency`: NoteDb parse latency by table.
+* `notedb/auto_rebuild_latency`: NoteDb auto-rebuilding latency by table.
+* `notedb/auto_rebuild_failure_count`: NoteDb auto-rebuilding attempts that
+failed by table.
+
+=== Replication Plugin
+
+* `plugins/replication/replication_latency`: Time spent pushing to remote
+destination.
+* `plugins/replication/replication_delay`: Time spent waiting before pushing to
+remote destination.
+* `plugins/replication/replication_retries`: Number of retries when pushing to
+remote destination.
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------