Merge pull request #1453 from hashicorp/d-fs-tail

Documentation for tail and the stream endpoint
hashicorp · Jul 22, 2016 · 432277a · 432277a
2 parents b6da4d6 + 7f5238e
commit 432277a
Show file tree

Hide file tree

Showing 3 changed files with 141 additions and 19 deletions.
diff --git a/command/fs.go b/command/fs.go
@@ -55,6 +55,10 @@ FS Specific Options:
   -stat
     Show file stat information instead of displaying the file, or listing the directory.
 
+  -f
+	Causes the output to not stop when the end of the file is reached, but
+	rather to wait for additional output. 
+
   -tail 
 	Show the files contents with offsets relative to the end of the file. If no
 	offset is given, -n is defaulted to 10.
@@ -65,11 +69,6 @@ FS Specific Options:
 
   -c
 	Sets the tail location in number of bytes relative to the end of the file.
-
-  -f
-	Causes the output to not stop when the end of the file is reached, but
-	rather to wait for additional output. 
-
 `
 	return strings.TrimSpace(helpText)
 }

diff --git a/website/source/docs/commands/fs.html.md.erb b/website/source/docs/commands/fs.html.md.erb
@@ -9,24 +9,58 @@ description: >
 # Command: fs
 
 The `fs` command allows a user to navigate an allocation directory on a Nomad
-client. The following functionalities are available - `cat`, `ls` and `stat`
+client. The following functionalities are available - `cat`, `tail`, `ls` and
+`stat`.
 
-`cat`: If the target path is a file, Nomad will cat the target path.
-`ls`: If the target path is a directory, Nomad displays the name of a file and directories and their associated information.
-`stat`: If the `-stat` flag is used, Nomad will Display information about a file.
+* `cat`: If the target path is a file, Nomad will `cat` the file.
+* `tail`: If the target path is a file and `-tail` flag is specified, Nomad will
+        `tail` the file.
+* `ls`: If the target path is a directory, Nomad displays the name of a file and
+      directories and their associated information.
+* `stat`: If the `-stat` flag is used, Nomad will display information about a
+        file.
 
 ## Usage
 
 ```
-nomad fs <alloc-id> <path>
-nomad fs -stat <alloc-id> <path>
+nomad fs [options] <alloc-id> <path>
 ```
 
-A valid allocation id is necessary unless `-job` is specified and the path is relative to the root of the allocation directory.
-The path is optional and it defaults to `/` of the allocation directory
+This command accepts a path and single allocation ID unless the `-job` flag is
+specified, in which case an allocation is chosen for the given job.  The path is
+relative to the root of the allocation directory.  The path is optional and it
+defaults to `/` of the allocation directory
+#
+## General Options
+
+<%= general_options_usage %>
+
+## Fs Options
+
+* `-H`: Machine friendly output.
+
+* `-verbose`: Display verbose output.
+
+* `-job`: Use a random allocation from the specified job, prefering a running
+allocation.
+
+* `-stat`: Show stat information instead of displaying the file, or listing the
+directory.
+
+* `-f`: Causes the output to not stop when the end of the file is reached, but
+rather to wait for additional output. 
+
+* `-tail`: Show the files contents with offsets relative to the end of the file.
+If no offset is given, -n is defaulted to 10.
+
+* `-n`: Sets the tail location in best-efforted number of lines relative to the
+end of the file.
+
+* `-c`: Sets the tail location in number of bytes relative to the end of the file.
 
 ## Examples
 
+```
 $ nomad fs eb17e557
 Mode        Size  Modified Time        Name
 drwxrwxr-x  4096  28 Jan 16 05:39 UTC  alloc/
@@ -46,17 +80,27 @@ Mode        Size  Modified Time        Name
 
 
 $ nomad fs redis/local/redis.stdout
-6710:C 27 Jan 22:04:03.794 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
-6710:M 27 Jan 22:04:03.795 * Increased maximum number of open files to 10032 (it was originally set to 256).
+foobar
+baz
+
+$ nomad fs -tail -f -n 3 redis/local/redis.stdout
+foobar
+baz
+bam
+<blocking>
+```
 
-## Using Job-ID instead of Alloc-ID
+## Using Job ID instead of Allocation ID
 
-Passing `-job` into one of the `fs` commands will allow the `fs` command to randomly select an allocation ID from the specified job.
+Passing `-job` into one of the `fs` commands will allow the `fs` command to
+randomly select an allocation ID from the specified job.
 
 ```
 nomad fs -job <job-id> <path>
 ```
 
-Nomad will prefer to select a running allocation ID for the job, but if no running allocations for the job are found, Nomad will use a dead allocation.
+Nomad will prefer to select a running allocation ID for the job, but if no
+running allocations for the job are found, Nomad will use a dead allocation.
 
-This can be useful for debugging a job that has multiple allocations, and it's not really required to use a specific allocation ID.
+This can be useful for debugging a job that has multiple allocations, and it's
+not really required to use a specific allocation ID.
diff --git a/website/source/docs/http/client-fs.html.md b/website/source/docs/http/client-fs.html.md
@@ -54,6 +54,85 @@ allocation was placed.
 
 </dl>
 
+<dl>
+  <dt>Description</dt>
+  <dd>
+     Stream contents of a file in an allocation directory.
+  </dd>
+
+  <dt>Method</dt>
+  <dd>GET</dd>
+
+  <dt>URL</dt>
+  <dd>`/v1/client/fs/stream/<Allocation-ID>`</dd>
+
+  <dt>Parameters</dt>
+  <dd>
+    <ul>
+      <li>
+        <span class="param">path</span>
+        <span class="param-flags">required</span>
+         The path relative to the root of the allocation directory. It 
+         defaults to `/`
+      </li>
+      <li>
+        <span class="param">offset</span>
+         The offset to start streaming from. Defaults to 0.
+      </li>
+      <li>
+        <span class="param">origin</span>
+        Origin can be either "start" or "end" and applies the offset relative to
+        either the start or end of the file respectively. Defaults to "start".
+      </li>
+    </ul>
+  </dd>
+
+  <dt>Returns</dt>
+  <dd>
+
+    ```
+...
+    {
+        "File":"alloc/logs/redis.stdout.0",
+        "Offset":3604480
+        "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..."
+    }
+    {
+        "File":"alloc/logs/redis.stdout.0",
+        "FileEvent": "file deleted"
+    }
+    ```
+
+  </dd>
+
+
+  <dt>Field Reference</dt>
+  <dd>
+    The return value is a stream of frames. These frames contain the following
+    fields:
+
+    <ul>
+      <li>
+        <span class="param">Data</span>
+        A base64 encoding of the bytes being streamed.
+      </li>
+      <li>
+        <span class="param">FileEvent</span>
+        An event that could cause a change in the streams position. The possible
+        values are "file deleted" and "file truncated".
+      </li>
+      <li>
+        <span class="param">Offset</span>
+        Offset is the offset into the stream.
+      </li>
+      <li>
+        <span class="param">File</span>
+        The name of the file being streamed.
+      </li>
+    </ul>
+  </dd>
+</dl>
+
 <dl>
   <dt>Description</dt>
   <dd>