kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-06 10:25:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Documentation for tail and the stream endpoint
This commit is contained in:
Alex Dadgar
2016-07-22 16:21:25 -07:00
committed by GitHub
parent b6da4d6f99 7f5238ec00
commit 432277a608
3 changed files with 141 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
command/fs.go
View File

@@ -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)
}

72
website/source/docs/commands/fs.html.md.erb
View File

@@ -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
## Using Job-ID instead of Alloc-ID
$ nomad fs -tail -f -n 3 redis/local/redis.stdout
foobar
baz
bam
<blocking>
```
Passing `-job` into one of the `fs` commands will allow the `fs` command to randomly select an allocation ID from the specified job.
## 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.
```
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.

79
website/source/docs/http/client-fs.html.md
View File

@@ -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>