Merge pull request #4096 from hashicorp/d-ui-update-docs

Docs: Update UI API and UI Guide

ui/app/templates/components/job-page/system.hbs

@@ -25,8 +25,6 @@
 
   {{job-page/parts/placement-failures job=job}}
 
-  {{job-page/parts/running-deployment job=job}}
-
   {{job-page/parts/task-groups
     job=job
     sortProperty=sortProperty

website/source/api/ui.html.md

@@ -44,6 +44,29 @@ This page shows an overview of a specific job. Details include name, status, typ
 priority, allocation statuses, and task groups. Additionally, if there is a running
 deployment for the job, it will be shown on the overview.
 
+This page shows an overview of a specific job. The exact information shown varies
+based on the type of job.
+
+- **Service Job** - Includes job metadata (name, status, priority, namespace), allocation
+  statuses, placement failures, active deployment, task groups, and evaluations.
+
+- **Batch Job** - Includes job metadata, allocation statuses, placement failures, task
+  groups, and evaluations.
+
+- **System Job** - Includes job metadata, allocation statuses, placement failures, task
+  groups, and evaluations.
+
+- **Periodic Job** - Includes job metadata, cron information force launch action, children statuses,
+  and children list.
+
+- **Parameterized Job** - Includes job metadata, children statuses, and children list.
+
+- **Periodic Child** - Includes job metadata, link to parent job, allocation statuses, placement
+  failures, task groups, and evaluations.
+
+- **Parameterized Child** - Includes job metadata, link to parent job, allocation statuses,
+  placement failures, task groups, evaluations, and dispatch payload.
+
 | Path               | Produces    |
 | ------------------ | ----------- |
 | `/ui/jobs/:job_id` | `text/html` |
@@ -143,6 +166,27 @@ description of the event.
   or ascending. This is specified as a querystring parameter.
 
 
+## Task Detail
+
+This page shows details and events for a specific task. Details include when the task started
+and stopped, all static and dynamic addresses, and all recent events.
+
+| Path                                   | Produces    |
+| -------------------------------------- | ----------- |
+| `/ui/allocations/:alloc_id/:task_name` | `text/html` |
+
+
+## Task Logs
+
+This page streams `stdout` and `stderr` logs for a task. By default, `stdout` is tailed, but
+there are available actions to see the head of the log, pause and play streaming, and switching
+to `stderr`.
+
+| Path                                        | Produces    |
+| ------------------------------------------- | ----------- |
+| `/ui/allocations/:alloc_id/:task_name/logs` | `text/html` |
+
+
 ## Nodes List
 
 This page lists all nodes in the Nomad cluster in a sortable, searchable, paginated

website/source/guides/ui.html.md

@@ -10,7 +10,7 @@ description: |-
 # Web UI
 
 The Nomad Web UI offers an easy to use web experience for inspecting a Nomad cluster.
-Jobs, Deployments, Task Groups, Allocations, Clients, and Servers can all be
+Jobs, Deployments, Evaluations, Task Groups, Allocations, Logs, Clients, and Servers can all be
 monitored from the Web UI. The Web UI also supports the use of ACL tokens for
 clusters that are using the [ACL system](/guides/acl.html).
 
@@ -26,7 +26,8 @@ port, `4646`.
 ## Reviewing Jobs
 
 The home page of the Web UI is the jobs list view. This page has a searchable, sortable,
-paginated table of all jobs in the cluster, regardless of job status.
+paginated table of all jobs in the cluster, regardless of job status. This page will automatically
+update as jobs are started, stopped, and allocations transition through states.
 
 [![Jobs List][img-jobs-list]][img-jobs-list]
 
@@ -47,6 +48,9 @@ number of task groups, and an aggregation of all allocations by allocation statu
 Clicking on a job will navigate to the Job Detail page. This page shows a list of task groups
 for the job as well as the status of each allocation for each task group by allocation status.
 
+This page will automatically update as deployments start and finish, new versions fail to be placed,
+allocations transition through states, and evaluations update.
+
 [![Job Detail][img-job-detail]][img-job-detail]
 
 ### Reading a Job Definition
@@ -61,6 +65,8 @@ job definition is shown as an interactive JSON object.
 Job Versions can be found on the Versions tab on the Job Detail page. This page has a timeline view of
 every tracked version for the job.
 
+This page will automatically update as new versions are submitted to the cluster.
+
 [![Job Versions][img-job-versions]][img-job-versions]
 
 Each version can be toggled to also show the diff between job versions.
@@ -72,6 +78,8 @@ Each version can be toggled to also show the diff between job versions.
 Job Deployments are listed on the Deployments tab on the Job Detail page. Every tracked deployment is listed in
 a timeline view.
 
+This page will automatically update as new versions are submitted to the cluster and deployments proceed.
+
 [![Job Deployments][img-job-deployments]][img-job-deployments]
 
 Each deployment can be toggle to show information about the deployment, including canaries placed and desired,
@@ -81,15 +89,40 @@ allocations placed and desired, healthy and unhealthy allocations, task group me
 
 ### Monitoring a Current Job Deployment
 
-When a deployment is currently running, it is called out on the Job Detail Overview tab.
+When a deployment is currently running, it is called out on the Job Detail Overview tab. It will update
+automatically as canaries and allocations are placed and deemed healthy or unhealthy.
 
 [![Active Job Deployment][img-active-job-deployment]][img-active-job-deployment]
 
+### Inspecting Child Jobs
+
+Child jobs are only listed on the parent periodic or parameterized job detail pages. This leaves the global
+jobs list view uncluttered.
+
+[![Periodic Job Detail Showing Children Jobs][img-periodic-job-detail]][img-periodic-job-detail]
+
+### Forcing a Periodic Launch
+
+From the job detail page for a periodic job, a child instance can be launched on demand rather than waiting
+the scheduled amount of time as defined by the cron in the job definition.
+
+[![Periodic Force Launch Button][img-periodic-force-launch-button]][img-periodic-force-launch-button]
+
+### Inspecting a Dispatch Payload
+
+When a parameterized job is dispatched, the payload is captured and accessible from the bottom of the
+parameterized child job detail page. The Web UI will attempt to parse the payload as JSON for improved
+inspecting capabilities.
+
+[![Parameterized Dispatch Payload][img-parameterized-dispatch-payload]][img-parameterized-dispatch-payload]
+
 ## Inspecting a Task Group
 
 Clicking on a task group from the Job Detail page will navigate to the Task Group Detail page. This page shows
 the aggregated resource metrics for a task group as well as a list of all associated allocations.
 
+This page will automatically update as the allocations in the task group change states.
+
 [![Task Group Detail][img-task-group-detail]][img-task-group-detail]
 
 ## Inspecting an Allocation
@@ -97,17 +130,34 @@ the aggregated resource metrics for a task group as well as a list of all associ
 From the Task Group Detail page, each allocation in the allocations table will report basic information about
 the allocation, including utilized CPU and memory.
 
-[![Allocation Stats][img-allocation-stats]][img-allocation-stats]
+Each allocation will poll for updates to current stats.
 
-~> **Note.** To collect current CPU and memory statistics, the Web UI makes requests directly to the client
-~> the allocation is running on. These requests will fail unless the browser session is running in the same
-~> subnet as the Nomad client.
+[![Allocation Stats][img-allocation-stats]][img-allocation-stats]
 
 Clicking an allocation will navigate to the Allocation Detail page. From here, the event history for each task
 in the allocation can be seen.
 
+This page will automatically update as new task events are emitted.
+
 [![Allocation Detail][img-allocation-detail]][img-allocation-detail]
 
+## Reviewing Logs
+
+Clicking on a task from the allocation detail will navigate to the Task Detail page. The Task Detail page includes
+a list of recent events as well as a tab for logs.
+
+On the Logs tab, anything the task writes to `stdout` or `stderr` is accessible. The log stream component allows
+for pausing and playing log streaming, jumping to the head or tail of the log, and toggling between `stdout` and
+`stderr`.
+
+~> **Note.** The Web UI will first attempt to stream logs directly from the client agent to avoid unnecessary load
+~> on server agents. If the client is not accessible, the Web UI will fallback to using the server for convenience.
+
+[![Task Logs][img-task-logs]][img-task-logs]
+
+~> **Note.** Only `stdout` and `stderr` are available in the UI. Any logs written to a file are available from the
+~> CLI using the [`nomad alloc fs`]('/docs/commands/alloc/fs.html'), but filesystem access is not yet in the Web UI.
+
 ## Reviewing Clients
 
 Clicking the Clients link in the left-hand menu of the Web UI will navigate to the Clients List page. This page
@@ -119,6 +169,8 @@ sharing links easier.
 In addition to name, each client in the table includes details such as current status, address, datacenter,
 and number of allocations.
 
+This page will automatically update as nodes change states and work is allocated.
+
 [![Clients List][img-clients-list]][img-clients-list]
 
 ## Inspecting a Client
@@ -127,6 +179,9 @@ Clicking on a client will navigate to the Client Detail page. This page shows th
 well as the list of all allocations placed on the client. Additionally, all attributes of the machine are
 itemized.
 
+This page will automatically update as allocations come and go on the client and the usage stats for an
+allocation change.
+
 [![Client Detail][img-client-detail]][img-client-detail]
 
 ## Inspecting Servers
@@ -166,3 +221,7 @@ Web UI makes will provide the Secret ID as the ACL Token via the `X-Nomad-Token`
 [img-client-detail]: /assets/images/guide-ui-client-detail.png
 [img-server-detail]: /assets/images/guide-ui-server-detail.png
 [img-acl-tokens]: /assets/images/guide-ui-acl-tokens.png
+[img-task-logs]: /assets/images/guide-ui-task-logs.png
+[img-parameterized-dispatch-payload]: /assets/images/guide-ui-parameterized-dispatch-payload.png
+[img-periodic-force-launch-button]: /assets/images/guide-ui-periodic-force-launch-button.png
+[img-periodic-job-detail]: /assets/images/guide-ui-periodic-job-detail.png