arthas/site/docs/en/doc/async.md

# Arthas Async Jobs

[`Async Jobs` online tutorial](https://arthas.aliyun.com/doc/arthas-tutorials?language=en&id=case-async-jobs)

Asynchronous jobs in arthas. The idea is borrowed from [linux jobs](http://man7.org/linux/man-pages/man1/jobs.1p.html).

## 1. Use & to run the command in the background

For example, execute the trace command in the background:

```bash
trace Test t &
```

By doing this, the current command is put to the background to run, you can continue to execute other commands in the console.

## 2. List background jobs

If you want to list all background jobs, you can execute the `jobs` command and the results are as follows:

```bash
$ jobs
[10]*
       Stopped           watch com.taobao.container.Test test "params[0].{? #this.name == null }" -x 2
       execution count : 19
       start time      : Fri Sep 22 09:59:55 CST 2017
       timeout date    : Sat Sep 23 09:59:55 CST 2017
       session         : 3648e874-5e69-473f-9eed-7f89660b079b (current)
```

You can see that there is currently a background job executing:

- job id is 10, `*` indicates that this job is created by the current session.
- status is `Stopped`
- execution count is the number of executions, which have been executed 19 times since the start.
- timeout date: timeout timestamp, when the time exceeds this timestamp, the job will be automatically timeout and exit.

## 3. Suspend and cancel job

When the job is executing in the foreground, for example, directly executing the command `trace Test t`, or executing the background job command `trace Test t &`, then putting the job back to the foreground via `fg` command, the console cannot continue to execute other command, but can receive and process the following keyboard events:

- ‘ctrl + z’: Suspends the job, the job status will change to `Stopped`, and the job can be restarted by `bg <job-id>` or `fg <job-id>`
- ‘ctrl + c’: Stops the job
- ‘ctrl + d’: According to linux semantics this should lead to exit the terminal, right now Arthas has not implemented this yet, therefore simply ignore this keystroke.

## 4. fg/bg, switch the job from the foreground to the background, and vise verse

- When a job is executed in the background or in suspended status (use `ctrl + z` to suspend job), `fg <job-id>` can transfer the job to the foreground to continue to run.
- When a job is in suspended status (use `ctrl + z` to suspend job), `bg <job-id>` can put the job to the background to continue to run.
- A job created by other session can only be put to the foreground to run by using `fg` in the current session.

## 5. Redirect the output

The job output can be redirect to the specified file by `>` or `>>`, and can be used together with `&`. By doing this, you can achieve running commands asynchronously, for example:

```bash
$ trace Test t >> test.out &
```

At this time, the trace command will be executed in the background, and the result will be output to the `test.out` file under the `working directory` of the application. You can continue to execute other commands. And you can view the command execution result in the file. You can execute the `pwd` command to view the `working directory` of the current application.

```bash
$ cat test.out
```

If no redirect file is specified, the result will be output to the `~/logs/arthas-cache/` directory, for example:

```bash
$ trace Test t >> &
job id : 2
cache location : /Users/admin/logs/arthas-cache/28198/2
```

At this time, the command will be executed asynchronously in the background, and the result will be asynchronously saved in the file (`~/logs/arthas-cache/${PID}/${JobId}`);

- At this time, the execution of the task is not affected by the session disconnection; the default timeout period of the task is 1 day, and the default timeout period can be modified through the global `options` command;
- The result of this command will be output asynchronously to the file; at this time, regardless of whether `save-result` is true or not, the result will not be written asynchronously to `~/logs/arthas-cache/result.log`.

## 6. Stop job

If you want to stop background job, just `kill <job-id>`.

## 7. Others

- Support up to 8 commands at the same time to redirect the output to the log files.
- Do not open too many background jobs at the same time to avoid negative performance effect to the target JVM.
- If you do not want to stop the Arthas service and continue to perform background tasks, you can exit the Arthas console by executing `quit` command (`stop` command will stop the Arthas service)