ref: document dvc queue

content/docs/command-reference/exp/remove.md

@@ -27,8 +27,12 @@ With `--queue`, the list of experiments awaiting execution is cleared instead.
 - `--queue` - remove all experiments that haven't been run yet (defined via
   `dvc exp run --queue`).
 
-- `-A`, `--all` - remove all experiments that have been run. Use `--queue` to
-  remove queued ones.
+  > ⚠️ `dvc exp remove --queue` is now an alias for `dvc queue remove --queued`.
+  > The `--queue` option will likely be deprecated and removed in a future DVC
+  > release. Refer to the `dvc queue` documentation for more details.
+
+- `-A`, `--all` - remove all experiments that have been run. Use
+  `dvc queue remove` to remove queued experiment tasks.
 
 - `--rev <commit>` - remove experiments derived from the specified `<commit>` as
   baseline.

content/docs/command-reference/exp/run.md

@@ -34,13 +34,9 @@ Use the `--set-param` (`-S`) option as a shortcut to change
 <abbr>parameter</abbr> values [on-the-fly] before running the experiment.
 
 It's possible to [queue experiments] for later execution with the `--queue`
-flag. To actually run them, use `dvc exp run --run-all`. Queued experiments are
-run sequentially by default, but can be run in parallel using the `--jobs`
-option.
-
-> ⚠️ Parallel runs are experimental and may be unstable. Make sure you're using
-> a number of jobs that your environment can handle (no more than the CPU
-> cores).
+flag. Queued experiments can be run using `dvc queue start`, refer to th
+`dvc queue` documentation for more information on managing the experiment task
+queue.
 
 It's also possible to run special [checkpoint experiments] that log the
 execution progress (useful for deep learning ML). The `--rev` and `--reset`
@@ -82,8 +78,7 @@ committing them to the Git repo. Unnecessary ones can be [cleared] with
   runs.
 
 - `--queue` - place this experiment at the end of a line for future execution,
-  but don't actually run it yet. Use `dvc exp run --run-all` to process the
-  queue.
+  but don't actually run it yet. Use `dvc queue start` to process the queue.
 
   > For checkpoint experiments, this implies `--reset` unless a `--rev` is
   > provided.
@@ -100,6 +95,13 @@ committing them to the Git repo. Unnecessary ones can be [cleared] with
   > stages may sometimes be executed several times depending on the state of the
   > [run-cache] at that time.
 
+  > ⚠️ `dvc exp run --run-all [--jobs]` is now a shortcut for
+  > `dvc queue start [--jobs]` followed by `dvc queue logs -f`. The `--run-all`
+  > and `--jobs` options will likely be deprecated and removed in a future DVC
+  > release. It is recommended to migrate your workflows to use
+  > `dvc queue start` and `dvc queue logs`. Refer to the `dvc queue`
+  > documentation for more details.
+
 - `-r <commit>`, `--rev <commit>` - resume an experiment from a specific
   checkpoint name or hash (`commit`) in `--queue` or `--temp` runs.
 

content/docs/command-reference/queue/index.md

@@ -0,0 +1,38 @@
+# queue
+
+A set of commands to manage the
+[DVC experiments](/doc/user-guide/experiment-management/experiments-overview)
+task queue: [start](/doc/command-reference/queue/start),
+[stop](/doc/command-reference/queue/stop),
+[status](/doc/command-reference/queue/status),
+[logs](/doc/command-reference/queue/logs),
+[remove](/doc/command-reference/queue/remove),
+[kill](/doc/command-reference/queue/kill)
+
+## Synopsis
+
+```usage
+usage: dvc queue [-h] [-q | -v] {start,stop,status,logs,remove,kill} ...
+
+positional arguments:
+  COMMAND
+    start               Start experiments queue workers.
+    stop                Stop experiments queue workers.
+    status              List the status of the queue tasks and workers.
+    logs                Show output logs for a task in the experiments queue.
+    remove              Remove tasks in experiments queue.
+    kill                Kill tasks in experiments queue.
+```
+
+## Description
+
+`dvc queue` subcommands provide specialized ways to manage queued experiment
+tasks.
+
+## Options
+
+- `-h`, `--help` - prints the usage/help message, and exit.
+
+- `-q`, `--quiet` - do not write anything to standard output.
+
+- `-v`, `--verbose` - displays detailed tracing information.

content/docs/command-reference/queue/kill.md

@@ -0,0 +1,31 @@
+## queue kill
+
+Kill actively running
+[DVC Experiment](/doc/user-guide/experiment-management/experiments-overview).
+tasks.
+
+## Synopsis
+
+```usage
+usage: dvc queue kill [-h] [-q | -v] [<task> ...]
+
+positional arguments:
+  <task>         Tasks in queue to kill.
+```
+
+## Description
+
+Forcefully stops execution of the specified (running) experiment tasks. Killed
+tasks will be considered as failed runs.
+
+This command does not stop the queue worker process. After the specified task
+has been killed, the worker process will consume and execute the next experiment
+task in the queue.
+
+## Options
+
+- `-h`, `--help` - prints the usage/help message, and exit.
+
+- `-q`, `--quiet` - do not write anything to standard output.
+
+- `-v`, `--verbose` - displays detailed tracing information.

content/docs/command-reference/queue/logs.md

@@ -0,0 +1,191 @@
+## queue logs
+
+Show output logs for running and completed tasks in the
+[DVC Experiment](/doc/user-guide/experiment-management/experiments-overview)
+task queue.
+
+## Synopsis
+
+```usage
+usage: dvc queue logs [-h] [-q | -v] [-e <encoding>] [-f] <task>
+
+positional arguments:
+  <task>                Task to show.
+```
+
+## Description
+
+Shows output logs for the specified running or completed experiment task.
+
+By default, this command will show any available log data and then exit. For
+tasks which are still running, the `--follow` option can be used to attach to
+the task and continuously show live log output, until the task has completed.
+
+When using the `--follow` option, it is safe to stop following output using
+`Ctrl+C` (or `SIGINT`). This will only cause the logs command to exit, and the
+experiment task will continue to be run in the background.
+
+## Options
+
+- `-e <encoding>`, `--encoding <encoding>` - text encoding for log output.
+  Defaults to the system locale encoding.
+
+  > ⚠️ Note that this option is used to specify the encoding of the experiment
+  > task output (i.e. the output of pipeline stage commands), which may not
+  > always match the encoding of your system terminal.
+
+- `-f`, `--follow` - attach to task and follow additional live output. Only
+  applicable of the task is still running.
+
+- `-h`, `--help` - prints the usage/help message, and exit.
+
+- `-q`, `--quiet` - do not write anything to standard output.
+
+- `-v`, `--verbose` - displays detailed tracing information.
+
+## Examples
+
+> This is based on our [Get Started](/doc/start/experiments), where you can find
+> the actual source code.
+
+<details>
+
+### Expand to prepare the example ML project
+
+Clone the DVC repo and download the data it <abbr>depends</abbr> on:
+
+```dvc
+$ git clone [email protected]:iterative/example-get-started.git
+$ cd example-get-started
+$ dvc pull
+```
+
+Let's also install the Python requirements:
+
+> We **strongly** recommend creating a
+> [virtual environment](https://python.readthedocs.io/en/stable/library/venv.html)
+> first.
+
+```dvc
+$ pip install -r src/requirements.txt
+```
+
+</details>
+
+Let's say we have previously run some experiments:
+
+```dvc
+$ dvc queue status
+Task     Name    Created    Status
+192a13c          04:15 PM   Failed
+753b005          04:01 PM   Success
+0bbb118          04:01 PM   Success
+1ae8b65          04:01 PM   Success
+
+Worker status: 0 active, 0 idle
+```
+
+We can view the output for both failed and successfully completed experiment
+tasks:
+
+```dvc
+$ dvc queue logs 192a13c
+'data/data.xml.dvc' didn't change, skipping
+Running stage 'prepare':
+> python src/prepare.py data/data.xml
+Traceback (most recent call last):
+  File "/Users/pmrowla/git/example-get-started/.dvc/tmp/exps/tmp217n0tjv/src/prepare.py", line 10, in <module>
+    raise AssertionError
+AssertionError
+ERROR: failed to reproduce 'prepare': failed to run: python src/prepare.py data/data.xml, exited with 1
+```
+
+```dvc
+$ dvc queue logs 0bbb118
+'data/data.xml.dvc' didn't change, skipping
+Stage 'prepare' is cached - skipping run, checking out outputs
+Updating lock file 'dvc.lock'
+
+Stage 'featurize' is cached - skipping run, checking out outputs
+Updating lock file 'dvc.lock'
+
+Stage 'train' is cached - skipping run, checking out outputs
+Updating lock file 'dvc.lock'
+
+Stage 'evaluate' is cached - skipping run, checking out outputs
+Updating lock file 'dvc.lock'
+
+To track the changes with git, run:
+
+    git add dvc.yaml scores.json roc.json params.yaml data/prepared data/data.xml prc.json src/featurization.py data/features src/evaluate.py model.pkl dvc.lock src/train.py src/prepare.py
+
+To enable auto staging, run:
+
+        dvc config core.autostage true
+```
+
+Let's queue a new experiment and view the output while it is running:
+
+```dvc
+$ dvc exp run --queue -S prepare.split=0.40 -S featurize.max_features=4000
+Queued experiment '93cfa70' for future execution.
+$ dvc queue start
+Started '1' new experiments task queue worker.
+$ dvc queue logs 93cfa70                                                                                                                       ⏎
+'data/data.xml.dvc' didn't change, skipping
+Running stage 'prepare':
+> python src/prepare.py data/data.xml
+Updating lock file 'dvc.lock'
+
+Running stage 'featurize':
+> python src/featurization.py data/prepared data/features
+```
+
+We can see that by default, `dvc queue logs` displays any available output and
+then exits. In this case, our `featurize` stage is still running, so no
+additional output is available at this time.
+
+Now let's use the `--follow` option to continue viewing all live output from the
+running experiment task, until it has completed:
+
+```dvc
+$ dvc queue logs -f 93cfa70
+Following logs for experiment '93cfa70'. Use Ctrl+C to stop following logs (experiment execution will continue).
+
+'data/data.xml.dvc' didn't change, skipping
+Running stage 'prepare':
+> python src/prepare.py data/data.xml
+Updating lock file 'dvc.lock'
+
+Running stage 'featurize':
+> python src/featurization.py data/prepared data/features
+The input data frame data/prepared/train.tsv size is (14945, 3)
+The output matrix data/features/train.pkl size is (14945, 4002) and data type is float64
+The input data frame data/prepared/test.tsv size is (10055, 3)
+The output matrix data/features/test.pkl size is (10055, 4002) and data type is float64
+Updating lock file 'dvc.lock'
+
+Running stage 'train':
+> python src/train.py data/features model.pkl
+Input matrix size (14945, 4002)
+X matrix size (14945, 4000)
+Y matrix size (14945,)
+Updating lock file 'dvc.lock'
+
+Running stage 'evaluate':
+> python src/evaluate.py model.pkl data/features scores.json prc.json roc.json
+Updating lock file 'dvc.lock'
+
+To track the changes with git, run:
+
+    git add prc.json model.pkl roc.json params.yaml src/train.py src/prepare.py data/features src/evaluate.py data/data.xml data/prepared dvc.yaml dvc.lock scores.json src/featurization.py
+
+To enable auto staging, run:
+
+        dvc config core.autostage true
+```
+
+We can see that output for the full experiment pipeline is displayed. We are
+also notified that we can safely use `Ctrl+C` if we want to exit the
+`dvc queue logs` command, without affecting the execution of our running
+experiment task.

content/docs/command-reference/queue/remove.md

@@ -0,0 +1,44 @@
+## queue remove
+
+Remove queued and completed tasks from the
+[DVC Experiment](/doc/user-guide/experiment-management/experiments-overview)
+task queue.
+
+## Synopsis
+
+```usage
+usage: dvc queue remove [-h] [-q | -v]
+                        [--all] [--queued] [--success] [--failed]
+                        [<task> ...]
+
+positional arguments:
+  <task>         Tasks in queue to remove.
+```
+
+## Description
+
+Removes the specified queued or completed experiment tasks from the queue. For
+completed tasks, this will also remove any associated output logs.
+
+> ⚠️ Note that for successfully completed tasks, this command is not the same as
+> `dvc exp remove`. This command not remove any Git or DVC data associated with
+> a successful DVC experiment. It only removes the task queue entry and any
+> associated output logs for that task.
+
+## Options
+
+- `--all` - remove all (queued and completed) experiment tasks from the queue.
+
+- `--queued` - remove all queued experiment tasks from the queue.
+
+- `--success` - remove all successfully completed tasks (and associated output
+  logs) from the queue.
+
+- `--failed` - remove all failed tasks (and associated output logs) from the
+  queue.
+
+- `-h`, `--help` - prints the usage/help message, and exit.
+
+- `-q`, `--quiet` - do not write anything to standard output.
+
+- `-v`, `--verbose` - displays detailed tracing information.