From 92f27fa946ef4133e010df28410bf0c530d97ea4 Mon Sep 17 00:00:00 2001
From: Diptanu Choudhury <diptanuc@gmail.com>
Date: Tue, 14 Jun 2016 02:58:33 +0200
Subject: [PATCH] Added the docs for the http api endpoint

---
 .../docs/http/client-allocation-stats.html.md | 154 ++++++++++++++++++
 .../source/docs/http/client-fs-cat.html.md    |   2 +-
 website/source/docs/http/client-fs-ls.html.md |   2 +-
 .../source/docs/http/client-fs-stat.html.md   |   2 +-
 website/source/docs/http/client-stats.html.md |  88 ++++++++++
 5 files changed, 245 insertions(+), 3 deletions(-)
 create mode 100644 website/source/docs/http/client-allocation-stats.html.md
 create mode 100644 website/source/docs/http/client-stats.html.md

diff --git a/website/source/docs/http/client-allocation-stats.html.md b/website/source/docs/http/client-allocation-stats.html.md
new file mode 100644
index 000000000..999897a09
--- /dev/null
+++ b/website/source/docs/http/client-allocation-stats.html.md
@@ -0,0 +1,154 @@
+---
+layout: "http"
+page_title: "HTTP API: /v1/client/allocation/allocation-id/stats"
+sidebar_current: "docs-http-client-allocation-stats"
+description: |-
+  The '/v1/client/allocation/<allocation-id>/stats` endpoint is used to query the actual resources consumed
+  by an allocation.
+---
+
+# /v1/client/allocation/allocation-id/stats
+
+The `/allocation/<allocation-id>/stats` endpoint is used to query the actual resources consumed by an allocation.
+The API endpoint is hosted by the Nomad client and requests have to be made to
+the nomad client whose resource usage metrics are of interest.
+
+
+## GET
+
+<dl>
+  <dt>Description</dt>
+  <dd>
+     Query resource usage of an allocation running on a client.
+  </dd>
+
+  <dt>Method</dt>
+  <dd>GET</dd>
+
+  <dt>URL</dt>
+  <dd>`/v1/client/allocation/<allocation-id>/stats`</dd>
+
+  <dt>Returns</dt>
+  <dd>
+  ```
+  {
+    "ResourceUsage": {
+      "CpuStats": {
+        "Measured": [
+          "System Mode",
+          "User Mode",
+          "Percent"
+        ],
+        "Percent": 105.77854560628487,
+        "SystemMode": 6.860067935411291,
+        "ThrottledPeriods": 0,
+        "ThrottledTime": 0,
+        "TotalTicks": 714.0051828424228,
+        "UserMode": 98.9184820888787
+      },
+      "MemoryStats": {
+        "Cache": 0,
+        "KernelMaxUsage": 0,
+        "KernelUsage": 0,
+        "MaxUsage": 0,
+        "Measured": [
+          "RSS",
+          "Swap"
+        ],
+        "RSS": 14098432,
+        "Swap": 0
+      }
+    },
+    "Tasks": {
+      "redis": {
+        "Pids": {
+          "27072": {
+            "CpuStats": {
+              "Measured": [
+                "System Mode",
+                "User Mode",
+                "Percent"
+              ],
+              "Percent": 6.8607999603563385,
+              "SystemMode": 5.880684245133524,
+              "ThrottledPeriods": 0,
+              "ThrottledTime": 0,
+              "TotalTicks": 0,
+              "UserMode": 0.9801144039714172
+            },
+            "MemoryStats": {
+              "Cache": 0,
+              "KernelMaxUsage": 0,
+              "KernelUsage": 0,
+              "MaxUsage": 0,
+              "Measured": [
+                "RSS",
+                "Swap"
+              ],
+              "RSS": 13418496,
+              "Swap": 0
+            }
+          },
+          "27073": {
+            "CpuStats": {
+              "Measured": [
+                "System Mode",
+                "User Mode",
+                "Percent"
+              ],
+              "Percent": 98.91774564592852,
+              "SystemMode": 0.9793836902777665,
+              "ThrottledPeriods": 0,
+              "ThrottledTime": 0,
+              "TotalTicks": 0,
+              "UserMode": 97.93836768490729
+            },
+            "MemoryStats": {
+              "Cache": 0,
+              "KernelMaxUsage": 0,
+              "KernelUsage": 0,
+              "MaxUsage": 0,
+              "Measured": [
+                "RSS",
+                "Swap"
+              ],
+              "RSS": 679936,
+              "Swap": 0
+            }
+          }
+        },
+        "ResourceUsage": {
+          "CpuStats": {
+            "Measured": [
+              "System Mode",
+              "User Mode",
+              "Percent"
+            ],
+            "Percent": 105.77854560628487,
+            "SystemMode": 6.860067935411291,
+            "ThrottledPeriods": 0,
+            "ThrottledTime": 0,
+            "TotalTicks": 714.0051828424228,
+            "UserMode": 98.9184820888787
+          },
+          "MemoryStats": {
+            "Cache": 0,
+            "KernelMaxUsage": 0,
+            "KernelUsage": 0,
+            "MaxUsage": 0,
+            "Measured": [
+              "RSS",
+              "Swap"
+            ],
+            "RSS": 14098432,
+            "Swap": 0
+          }
+        },
+        "Timestamp": 1465865820750959600
+      }
+    },
+    "Timestamp": 1465865820750959600
+  }
+  ```
+  </dd>
+</dl>
diff --git a/website/source/docs/http/client-fs-cat.html.md b/website/source/docs/http/client-fs-cat.html.md
index b7abedf38..448ee8ffd 100644
--- a/website/source/docs/http/client-fs-cat.html.md
+++ b/website/source/docs/http/client-fs-cat.html.md
@@ -3,7 +3,7 @@ layout: "http"
 page_title: "HTTP API: /v1/client/fs/cat"
 sidebar_current: "docs-http-client-fs-cat"
 description: |-
-  The '/1/client/fs/cat` endpoint is used to read the contents of a file in an
+  The '/v1/client/fs/cat` endpoint is used to read the contents of a file in an
   allocation directory.
 ---
 
diff --git a/website/source/docs/http/client-fs-ls.html.md b/website/source/docs/http/client-fs-ls.html.md
index fc6598519..912386cec 100644
--- a/website/source/docs/http/client-fs-ls.html.md
+++ b/website/source/docs/http/client-fs-ls.html.md
@@ -3,7 +3,7 @@ layout: "http"
 page_title: "HTTP API: /v1/client/fs/ls"
 sidebar_current: "docs-http-client-fs-ls"
 description: |-
-  The '/1/client/fs/ls` endpoint is used to list files in an allocation
+  The '/v1/client/fs/ls` endpoint is used to list files in an allocation
   directory.
 ---
 
diff --git a/website/source/docs/http/client-fs-stat.html.md b/website/source/docs/http/client-fs-stat.html.md
index 8fe428667..3de010e83 100644
--- a/website/source/docs/http/client-fs-stat.html.md
+++ b/website/source/docs/http/client-fs-stat.html.md
@@ -3,7 +3,7 @@ layout: "http"
 page_title: "HTTP API: /v1/client/fs/stat"
 sidebar_current: "docs-http-client-fs-stat"
 description: |-
-  The '/1/client/fs/stat` endpoint is used to stat a file in an allocation
+  The '/v1/client/fs/stat` endpoint is used to stat a file in an allocation
   directory.
 ---
 
diff --git a/website/source/docs/http/client-stats.html.md b/website/source/docs/http/client-stats.html.md
new file mode 100644
index 000000000..792b682bf
--- /dev/null
+++ b/website/source/docs/http/client-stats.html.md
@@ -0,0 +1,88 @@
+---
+layout: "http"
+page_title: "HTTP API: /v1/client/stats"
+sidebar_current: "docs-http-client-stats"
+description: |-
+  The '/v1/client/stats` endpoint is used to query the actual resources consumed
+  on the node.
+---
+
+# /v1/client/stats
+
+The `/stats` endpoint is used to query the actual resources consumed on a node.
+The API endpoint is hosted by the Nomad client and requests have to be made to
+the nomad client whose resource usage metrics are of interest.
+
+
+## GET
+
+<dl>
+  <dt>Description</dt>
+  <dd>
+     Query the actual resource usage of a Nomad client
+  </dd>
+
+  <dt>Method</dt>
+  <dd>GET</dd>
+
+  <dt>URL</dt>
+  <dd>`/v1/client/stats`</dd>
+
+  <dt>Returns</dt>
+  <dd>
+  ```
+   {
+     "CPU": [
+       {
+         "CPU": "cpu0",
+         "Idle": 89.2156862745098,
+         "System": 4.901960784313726,
+         "Total": 10.784313725490197,
+         "User": 5.88235294117647
+       },
+       {
+         "CPU": "cpu1",
+         "Idle": 100,
+         "System": 0,
+         "Total": 0,
+         "User": 0
+       },
+       {
+         "CPU": "cpu2",
+         "Idle": 94.05940594059405,
+         "System": 2.9702970297029703,
+         "Total": 5.9405940594059405,
+         "User": 2.9702970297029703
+       },
+       {
+         "CPU": "cpu3",
+         "Idle": 99.00990099009901,
+         "System": 0,
+         "Total": 0.9900990099009901,
+         "User": 0.9900990099009901
+       }
+     ],
+     "CPUTicksConsumed": 119.5762958648806,
+     "DiskStats": [
+       {
+         "Available": 16997969920,
+         "Device": "/dev/disk1",
+         "InodesUsedPercent": 85.84777164286838,
+         "Mountpoint": "/",
+         "Size": 120108089344,
+         "Used": 102847975424,
+         "UsedPercent": 85.62951586835626
+       }
+     ],
+     "Memory": {
+       "Available": 3724746752,
+       "Free": 2446233600,
+       "Total": 8589934592,
+       "Used": 4865187840
+     },
+     "Timestamp": 1465839167993064200,
+     "Uptime": 101149
+   }
+  ```
+  </dd>
+</dl>