From 88372e6b72b617b41c7d70b41e8e97d29e62ac22 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Mon, 28 Aug 2017 16:05:58 -0700 Subject: [PATCH] Document new status command This PR documents the new status and job status command. --- command/job_status.go | 6 +- website/source/docs/commands/job.html.md.erb | 2 + .../docs/commands/job/status.html.md.erb | 248 ++++++++++++++++++ .../source/docs/commands/status.html.md.erb | 246 +++++------------ website/source/layouts/docs.erb | 3 + 5 files changed, 328 insertions(+), 177 deletions(-) create mode 100644 website/source/docs/commands/job/status.html.md.erb diff --git a/command/job_status.go b/command/job_status.go index 82d0de13163..91a018b1577 100644 --- a/command/job_status.go +++ b/command/job_status.go @@ -30,8 +30,8 @@ func (c *JobStatusCommand) Help() string { helpText := ` Usage: nomad status [options] - Display status information about jobs. If no job ID is given, - a list of all known jobs will be dumped. + Display status information about a job. If no job ID is given, a list of all + known jobs will be displayed. General Options: @@ -57,7 +57,7 @@ Status Options: } func (c *JobStatusCommand) Synopsis() string { - return "Display status information about jobs" + return "Display status information about a job" } func (c *JobStatusCommand) AutocompleteFlags() complete.Flags { diff --git a/website/source/docs/commands/job.html.md.erb b/website/source/docs/commands/job.html.md.erb index de1b36eb378..dc8c2f458e2 100644 --- a/website/source/docs/commands/job.html.md.erb +++ b/website/source/docs/commands/job.html.md.erb @@ -24,9 +24,11 @@ subcommands are available: * [`job history`][history] - Display all tracked versions of a job * [`job promote`][promote] - Promote a job's canaries * [`job revert`][revert] - Revert to a prior version of the job +* [`job status`][status] - Display status information about a job [deployments]: /docs/commands/job/deployments.html "List deployments for a job" [dispatch]: /docs/commands/job/dispatch.html "Dispatch an instance of a parameterized job" [history]: /docs/commands/job/history.html "Display all tracked versions of a job" [promote]: /docs/commands/job/promote.html "Promote a job's canaries" [revert]: /docs/commands/job/revert.html "Revert to a prior version of the job" +[status]: /docs/commands/job/status.html "Display status information about a job" diff --git a/website/source/docs/commands/job/status.html.md.erb b/website/source/docs/commands/job/status.html.md.erb new file mode 100644 index 00000000000..ff67b3bd6de --- /dev/null +++ b/website/source/docs/commands/job/status.html.md.erb @@ -0,0 +1,248 @@ +--- +layout: "docs" +page_title: "Commands: job status" +sidebar_current: "docs-commands-job-status" +description: > + Display information and status of jobs. +--- + +# Command: job status + +The `job status` command displays status information for a job. + +## Usage + +``` +nomad job status [options] [job] +``` + +This command accepts an optional job ID or prefix as the sole argument. If there +is an exact match based on the provided job ID or prefix, then information about +the specific job is queried and displayed. Otherwise, a list of matching jobs and +information will be displayed. + +If the ID is omitted, the command lists out all of the existing jobs and a few of +the most useful status fields for each. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Status Options + +* `-all-allocs`: Display all allocations matching the job ID, even those from an + older instance of the job. + +* `-evals`: Display the evaluations associated with the job. + +* `-short`: Display short output. Used only when a single node is being queried. + Drops verbose node allocation data from the output. + +* `-verbose`: Show full information. + +## Examples + +List of all jobs: + +``` +$ nomad job status +ID Type Priority Status Submit Date +job1 service 80 running 07/25/17 15:47:11 UTC +job2 batch 40 complete 07/24/17 19:22:11 UTC +job3 service 50 dead (stopped) 07/22/17 16:34:48 UTC +``` + +Short view of a specific job: + +``` +$ nomad job status -short job1 +ID = job1 +Name = Test Job +Submit Date = 07/25/17 15:47:11 UTC +Type = service +Priority = 3 +Datacenters = dc1,dc2,dc3 +Status = pending +Periodic = false +Parameterized = false +``` + +Full status information of a job: + +``` +$ nomad job status example +ID = example +Name = example +Submit Date = 07/25/17 15:53:04 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 1 0 0 0 + +Latest Deployment +ID = 6294be0c +Status = successful +Description = Deployment completed successfully + +Deployed +Task Group Desired Placed Healthy Unhealthy +cache 1 1 1 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +478ce836 5ed166e8 cache 0 run running 07/25/17 15:53:04 UTC +``` + +Full status information of a perodic job: + +``` +$ nomad job status example +ID = example +Name = example +Submit Date = 07/25/17 15:59:52 UTC +Type = batch +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = true +Parameterized = false +Next Periodic Launch = 07/25/17 16:00:30 UTC (5s from now) + +Children Job Summary +Pending Running Dead +0 3 0 + +Previously Launched Jobs +ID Status +example/periodic-1500998400 running +example/periodic-1500998410 running +example/periodic-1500998420 running +``` + +Full status information of a parameterized job: + +``` +$ nomad job status example +ID = example +Name = example +Submit Date = 07/25/17 15:59:52 UTC +Type = batch +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = true + +Parameterized Job +Payload = required +Required Metadata = foo +Optional Metadata = bar + +Parameterized Job Summary +Pending Running Dead +0 2 0 + +Dispatched Jobs +ID Status +example/dispatch-1485411496-58f24d2d running +example/dispatch-1485411499-fa2ee40e running +``` + +Full status information of a job with placement failures: + +``` +$ nomad job status example +ID = example +Name = example +Submit Date = 07/25/17 15:55:27 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 1 0 4 0 0 0 + +Placement Failure +Task Group "cache": + * Resources exhausted on 1 nodes + * Dimension "cpu exhausted" exhausted on 1 nodes + +Latest Deployment +ID = bb4b2fb1 +Status = running +Description = Deployment is running + +Deployed +Task Group Desired Placed Healthy Unhealthy +cache 5 4 4 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +048c1e9e 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +250f9dec 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +2eb772a1 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +a17b7d3d 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +``` + +Full status information showing evaluations with a placement failure. The in +progress evaluation denotes that Nomad is blocked waiting for resources to +become availables so that it can place the remaining allocations. + +``` +$ nomad job status -evals example +ID = example +Name = example +Submit Date = 07/25/17 15:55:27 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 1 0 4 0 0 0 + +Evaluations +ID Priority Triggered By Status Placement Failures +e44a39e8 50 deployment-watcher canceled false +97018573 50 deployment-watcher complete true +d5a7300c 50 deployment-watcher canceled false +f05a4495 50 deployment-watcher complete true +e3f3bdb4 50 deployment-watcher canceled false +b5f08700 50 deployment-watcher complete true +73bb867a 50 job-register blocked N/A - In Progress +85052989 50 job-register complete true + +Placement Failure +Task Group "cache": + * Resources exhausted on 1 nodes + * Dimension "cpu exhausted" exhausted on 1 nodes + +Latest Deployment +ID = bb4b2fb1 +Status = running +Description = Deployment is running + +Deployed +Task Group Desired Placed Healthy Unhealthy +cache 5 4 4 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +048c1e9e 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +250f9dec 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +2eb772a1 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +a17b7d3d 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +``` diff --git a/website/source/docs/commands/status.html.md.erb b/website/source/docs/commands/status.html.md.erb index 3a7f8c3178d..a107ac8cf3d 100644 --- a/website/source/docs/commands/status.html.md.erb +++ b/website/source/docs/commands/status.html.md.erb @@ -3,74 +3,39 @@ layout: "docs" page_title: "Commands: status" sidebar_current: "docs-commands-status" description: > - Display information and status of jobs. + Display the status output for any Nomad resource. --- # Command: status -The `status` command displays status information for jobs. +The `status` command displays the status output for any Nomad resouce. ## Usage ``` -nomad status [options] [job] +nomad status [options] ``` -This command accepts an optional job ID or prefix as the sole argument. If there -is an exact match based on the provided job ID or prefix, then information about -the specific job is queried and displayed. Otherwise, a list of matching jobs and -information will be displayed. +The status command accepts any Nomad identifier or identifier prefix as its sole +argument. The command detects the type of the identifier and routes to the +appropriate status command to display more detailed output. -If the ID is omitted, the command lists out all of the existing jobs and a few of -the most useful status fields for each. +If the ID is omitted, the command lists out all of the existing jobs. This is +for backwards compatibility and should not be relied on. ## General Options <%= partial "docs/commands/_general_options" %> -## Status Options - -* `-evals`: Display the evaluations associated with the job. - -* `-short`: Display short output. Used only when a single node is being queried. - Drops verbose node allocation data from the output. - -* `-verbose`: Show full information. - ## Examples -List of all jobs: - -``` -$ nomad status -ID Type Priority Status Submit Date -job1 service 80 running 07/25/17 15:47:11 UTC -job2 batch 40 complete 07/24/17 19:22:11 UTC -job3 service 50 dead (stopped) 07/22/17 16:34:48 UTC -``` - -Short view of a specific job: - -``` -$ nomad status -short job1 -ID = job1 -Name = Test Job -Submit Date = 07/25/17 15:47:11 UTC -Type = service -Priority = 3 -Datacenters = dc1,dc2,dc3 -Status = pending -Periodic = false -Parameterized = false -``` - -Full status information of a job: +Display the status of a job: ``` $ nomad status example ID = example Name = example -Submit Date = 07/25/17 15:53:04 UTC +Submit Date = 08/28/17 23:01:39 UTC Type = service Priority = 50 Datacenters = dc1 @@ -83,163 +48,96 @@ Task Group Queued Starting Running Failed Complete Lost cache 0 0 1 0 0 0 Latest Deployment -ID = 6294be0c -Status = successful -Description = Deployment completed successfully +ID = f5506391 +Status = running +Description = Deployment is running Deployed Task Group Desired Placed Healthy Unhealthy -cache 1 1 1 0 +cache 1 1 0 0 Allocations ID Node ID Task Group Version Desired Status Created At -478ce836 5ed166e8 cache 0 run running 07/25/17 15:53:04 UTC +e1d14a39 f9dabe93 cache 0 run running 08/28/17 23:01:39 UTC ``` -Full status information of a perodic job: +Display the status of an allocation: ``` -$ nomad status example -ID = example -Name = example -Submit Date = 07/25/17 15:59:52 UTC -Type = batch -Priority = 50 -Datacenters = dc1 -Status = running -Periodic = true -Parameterized = false -Next Periodic Launch = 07/25/17 16:00:30 UTC (5s from now) - -Children Job Summary -Pending Running Dead -0 3 0 - -Previously Launched Jobs -ID Status -example/periodic-1500998400 running -example/periodic-1500998410 running -example/periodic-1500998420 running -``` +$ nomad status e1d14a39 +ID = e1d14a39 +Eval ID = cc882755 +Name = example.cache[0] +Node ID = f9dabe93 +Job ID = example +Job Version = 0 +Client Status = running +Client Description = +Desired Status = run +Desired Description = +Created At = 08/28/17 23:01:39 UTC +Deployment ID = f5506391 +Deployment Health = healthy -Full status information of a parameterized job: +Task "redis" is "running" +Task Resources +CPU Memory Disk IOPS Addresses +4/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:21752 -``` -$ nomad status example -ID = example -Name = example -Submit Date = 07/25/17 15:59:52 UTC -Type = batch -Priority = 50 -Datacenters = dc1 -Status = running -Periodic = false -Parameterized = true - -Parameterized Job -Payload = required -Required Metadata = foo -Optional Metadata = bar +Task Events: +Started At = 08/28/17 23:01:39 UTC +Finished At = N/A +Total Restarts = 0 +Last Restart = N/A -Parameterized Job Summary -Pending Running Dead -0 2 0 - -Dispatched Jobs -ID Status -example/dispatch-1485411496-58f24d2d running -example/dispatch-1485411499-fa2ee40e running +Recent Events: +Time Type Description +08/28/17 23:01:39 UTC Started Task started by client +08/28/17 23:01:39 UTC Task Setup Building Task Directory +08/28/17 23:01:39 UTC Received Task received by client ``` -Full status information of a job with placement failures: +Display the status of a deployment: ``` -$ nomad status example -ID = example -Name = example -Submit Date = 07/25/17 15:55:27 UTC -Type = service -Priority = 50 -Datacenters = dc1 -Status = running -Periodic = false -Parameterized = false - -Summary -Task Group Queued Starting Running Failed Complete Lost -cache 1 0 4 0 0 0 - -Placement Failure -Task Group "cache": - * Resources exhausted on 1 nodes - * Dimension "cpu exhausted" exhausted on 1 nodes - -Latest Deployment -ID = bb4b2fb1 -Status = running -Description = Deployment is running +$ nomad status f5506391 +ID = f5506391 +Job ID = example +Job Version = 0 +Status = successful +Description = Deployment completed successfully Deployed Task Group Desired Placed Healthy Unhealthy -cache 5 4 4 0 - -Allocations -ID Node ID Task Group Version Desired Status Created At -048c1e9e 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC -250f9dec 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC -2eb772a1 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC -a17b7d3d 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +cache 1 1 1 0 ``` -Full status information showing evaluations with a placement failure. The in -progress evaluation denotes that Nomad is blocked waiting for resources to -become availables so that it can place the remaining allocations. +Display the status of a node: ``` -$ nomad status -evals example -ID = example -Name = example -Submit Date = 07/25/17 15:55:27 UTC -Type = service -Priority = 50 -Datacenters = dc1 -Status = running -Periodic = false -Parameterized = false +$ nomad status f9dabe93 +ID = f9dabe93 +Name = nomad-server01 +Class = +DC = dc1 +Drain = false +Status = ready +Drivers = docker,exec,java,qemu,raw_exec,rkt +Uptime = 4h17m24s -Summary -Task Group Queued Starting Running Failed Complete Lost -cache 1 0 4 0 0 0 - -Evaluations -ID Priority Triggered By Status Placement Failures -e44a39e8 50 deployment-watcher canceled false -97018573 50 deployment-watcher complete true -d5a7300c 50 deployment-watcher canceled false -f05a4495 50 deployment-watcher complete true -e3f3bdb4 50 deployment-watcher canceled false -b5f08700 50 deployment-watcher complete true -73bb867a 50 job-register blocked N/A - In Progress -85052989 50 job-register complete true - -Placement Failure -Task Group "cache": - * Resources exhausted on 1 nodes - * Dimension "cpu exhausted" exhausted on 1 nodes +Allocated Resources +CPU Memory Disk IOPS +500/8709 MHz 256 MiB/2.0 GiB 300 MiB/24 GiB 0/0 -Latest Deployment -ID = bb4b2fb1 -Status = running -Description = Deployment is running +Allocation Resource Utilization +CPU Memory +3/8709 MHz 6.3 MiB/2.0 GiB -Deployed -Task Group Desired Placed Healthy Unhealthy -cache 5 4 4 0 +Host Resource Utilization +CPU Memory Disk +116/8709 MHz 335 MiB/2.0 GiB 12 GiB/38 GiB Allocations ID Node ID Task Group Version Desired Status Created At -048c1e9e 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC -250f9dec 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC -2eb772a1 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC -a17b7d3d 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +e1d14a39 f9dabe93 cache 0 run running 08/28/17 23:01:39 UTC ``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 9792b5cfb89..ad14e19ec6a 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -232,6 +232,9 @@ > job revert + > + job status + >