Add REST endpoint to get server summary
Change-Id: Ibd24b2c13d3b791c90b49fe8e9a14688a26c36f4
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/rest-api-config.txt b/Documentation/rest-api-config.txt
index 8d9b34c..270c540 100644
--- a/Documentation/rest-api-config.txt
+++ b/Documentation/rest-api-config.txt
@@ -455,6 +455,90 @@
HTTP/1.1 200 OK
----
+[[get-summary]]
+=== Get Summary
+--
+'GET /config/server/summary'
+--
+
+Retrieves a summary of the current server state.
+
+The caller must be a member of a group that is granted the
+link:access-control.html#capability_administrateServer[Administrate
+Server] capability.
+
+The following options are supported:
+
+* `jvm`:
++
+Includes a JVM summary.
+
+* `gc`:
++
+Requests a Java garbage collection before computing the information
+about the Java memory heap.
+
+.Request
+----
+ GET /config/server/summary?jvm HTTP/1.0
+----
+
+As result a link:#summary-info[SummaryInfo] entity is returned.
+
+.Response
+----
+ HTTP/1.1 200 OK
+ Content-Type: application/json;charset=UTF-8
+
+ )]}'
+ {
+ "task_summary": {
+ "total": 2,
+ "sleeping": 2
+ },
+ "mem_summary": {
+ "total": "341.06m",
+ "used": "57.16m",
+ "free": "283.90m",
+ "buffers": "0.00k",
+ "max": "1.67g",
+ }
+ "thread_summary": {
+ "cpus": 8,
+ "threads": 44,
+ "counts": {
+ "HTTP": {
+ "RUNNABLE": 3,
+ "TIMED_WAITING": 2
+ },
+ "SSH-Interactive-Worker": {
+ "WAITING": 1
+ },
+ "Other": {
+ "WAITING": 10,
+ "RUNNABLE": 2,
+ "TIMED_WAITING": 25
+ },
+ "SshCommandStart": {
+ "WAITING": 1
+ }
+ }
+ },
+ "jvm_summary": {
+ "vm_vendor": "Oracle Corporation",
+ "vm_name": "Java HotSpot(TM) 64-Bit Server VM",
+ "vm_version": "23.25-b01",
+ "os_name": "Mac OS X",
+ "os_version": "10.8.5",
+ "os_arch": "x86_64",
+ "user": "gerrit",
+ "host": "GERRIT",
+ "current_working_directory": "/Users/gerrit/site",
+ "site": "/Users/gerrit/site"
+ }
+ }
+----
+
[[list-capabilities]]
=== List Capabilities
--
@@ -691,6 +775,117 @@
Only set for disk caches.
|==================================
+[[jvm-summary-info]]
+=== JvmSummaryInfo
+The `JvmSummaryInfo` entity contains information about the JVM.
+
+[options="header",width="50%",cols="1,^1,5"]
+|========================================
+|Field Name ||Description
+|`vm_vendor` ||The vendor of the virtual machine.
+|`vm_name` ||The name of the virtual machine.
+|`vm_version` ||The version of the virtual machine.
+|`os_name` ||The name of the operating system.
+|`os_version` ||The version of the operating system.
+|`os_arch` ||The architecture of the operating system.
+|`user` ||The user that is running Gerrit.
+|`host` |optional|
+The host on which Gerrit is running.
+|`current_working_directory`||The current working directory.
+|`site` ||The path to the review site.
+|========================================
+
+[[mem-summary-info]]
+=== MemSummaryInfo
+The `MemSummaryInfo` entity contains information about the current
+memory usage.
+
+[options="header",width="50%",cols="1,^1,5"]
+|============================
+|Field Name ||Description
+|`total` ||
+The total size of the memory. The value is returned with a unit
+abbreviation (`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
+|`used` ||
+The size of used memory. The value is returned with a unit abbreviation
+(`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
+|`free` ||
+The size of free memory. The value is returned with a unit abbreviation
+(`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
+|`buffers` ||
+The size of memory used for JGit buffers. The value is returned with a
+unit abbreviation (`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
+|`max` ||
+The maximal memory size. The value is returned with a unit abbreviation
+(`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
+|`open_files` |optional|
+The number of open files.
+|============================
+
+[[summary-info]]
+=== SummaryInfo
+The `SummaryInfo` entity contains information about the current state
+of the server.
+
+[options="header",width="50%",cols="1,^1,5"]
+|============================
+|Field Name ||Description
+|`task_summary` ||
+Summary about current tasks as a link:#task-summary-info[
+TaskSummaryInfo] entity.
+|`mem_summary` ||
+Summary about current memory usage as a link:#mem-summary-info[
+MemSummaryInfo] entity.
+|`thread_summary` ||
+Summary about current threads as a link:#thread-summary-info[
+ThreadSummaryInfo] entity.
+|`jvm_summary` |optional|
+Summary about the JVM link:#jvm-summary-info[JvmSummaryInfo] entity.
+Only set if the `jvm` option was set.
+|============================
+
+[[task-summary-info]]
+=== TaskSummaryInfo
+The `TaskSummaryInfo` entity contains information about the current
+tasks.
+
+[options="header",width="50%",cols="1,^1,5"]
+|============================
+|Field Name ||Description
+|`total` |optional|
+Total number of current tasks.
+|`running` |optional|
+Number of currently running tasks.
+|`ready` |optional|
+Number of currently ready tasks.
+|`sleeping` |optional|
+Number of currently sleeping tasks.
+|============================
+
+[[thread-summary-info]]
+=== ThreadSummaryInfo
+The `ThreadSummaryInfo` entity contains information about the current
+threads.
+
+[options="header",width="50%",cols="1,6"]
+|===========================
+|Field Name |Description
+|`cpus` |
+The number of available processors.
+|`threads` |
+The total number of current threads.
+|`counts` |
+Detailed thread counts as a map that maps a thread kind to a map that
+maps a thread state to the thread count. The thread kinds group the
+counts by threads that have the same name prefix (`HTTP`,
+`IntraLineDiff`, `ReceiveCommits`, `SSH git-receive-pack`,
+`SSH git-upload-pack`, `SSH-Interactive-Worker`, `SSH-Stream-Worker`,
+`SshCommandStart`). The counts for other threads are available under
+the thread kind `Other`. Counts for the following thread states can be
+included: `NEW`, `RUNNABLE`, `BLOCKED`, `WAITING`, `TIMED_WAITING` and
+`TERMINATED`.
+|===========================
+
[[top-menu-entry-info]]
=== TopMenuEntryInfo
The `TopMenuEntryInfo` entity contains information about a top menu
