From 53d0976ef22d64e6ad8b6c53cc4808b37b87f7be Mon Sep 17 00:00:00 2001
From: hengyunabc <hengyunabc@gmail.com>
Date: Thu, 28 Nov 2019 16:02:27 +0800
Subject: [PATCH] update trace command docs

---
 .../core/command/monitor200/TraceCommand.java |  3 +++
 site/src/site/sphinx/en/trace.md              | 24 +++++++++++++++++++
 site/src/site/sphinx/trace.md                 | 24 +++++++++++++++++++
 3 files changed, 51 insertions(+)

diff --git a/core/src/main/java/com/taobao/arthas/core/command/monitor200/TraceCommand.java b/core/src/main/java/com/taobao/arthas/core/command/monitor200/TraceCommand.java
index 70849e1b8..15c018b73 100644
--- a/core/src/main/java/com/taobao/arthas/core/command/monitor200/TraceCommand.java
+++ b/core/src/main/java/com/taobao/arthas/core/command/monitor200/TraceCommand.java
@@ -24,6 +24,7 @@ import java.util.List;
  *
  * @author vlinux on 15/5/27.
  */
+// @formatter:off
 @Name("trace")
 @Summary("Trace the execution time of specified method invocation.")
 @Description(value = Constants.EXPRESS_DESCRIPTION + Constants.EXAMPLE +
@@ -33,7 +34,9 @@ import java.util.List;
         "  trace *StringUtils isBlank '#cost>100'\n" +
         "  trace -E org\\\\.apache\\\\.commons\\\\.lang\\\\.StringUtils isBlank\n" +
         "  trace -E com.test.ClassA|org.test.ClassB method1|method2|method3\n" +
+        "  trace demo.MathGame run -n 5\n" +
         Constants.WIKI + Constants.WIKI_HOME + "trace")
+//@formatter:on
 public class TraceCommand extends EnhancerCommand {
 
     private String classPattern;
diff --git a/site/src/site/sphinx/en/trace.md b/site/src/site/sphinx/en/trace.md
index b3f089a62..fdf925341 100644
--- a/site/src/site/sphinx/en/trace.md
+++ b/site/src/site/sphinx/en/trace.md
@@ -52,6 +52,30 @@ Affect(class-cnt:1 , method-cnt:1) cost in 42 ms.
         `---[0.170316ms] demo.MathGame:print()
 ```
 
+
+#### trace times limit
+
+If the method invoked many times, use `-n` options to specify trace times. For example, the command will exit when received a trace result.
+
+```bash
+$ trace demo.MathGame run -n 1
+Press Q or Ctrl+C to abort.
+Affect(class-cnt:1 , method-cnt:1) cost in 35 ms.
+`---ts=2019-11-28 15:54:28;thread_name=main;id=1;is_daemon=false;priority=5;TCCL=sun.misc.Launcher$AppClassLoader@3d4eac69
+    `---[0.866311ms] demo.MathGame:run()
+        +---[0.044001ms] java.util.Random:nextInt() #23
+        +---[0.069037ms] demo.MathGame:primeFactors() #24 [throws Exception]
+        +---[0.003227ms] java.lang.StringBuilder:<init>() #28
+        +---[0.006155ms] java.lang.Integer:valueOf() #28
+        +---[0.071335ms] java.lang.String:format() #28
+        +---[min=0.002142ms,max=0.002237ms,total=0.004379ms,count=2] java.lang.StringBuilder:append() #28
+        +---[0.011072ms] java.lang.Exception:getMessage() #28
+        +---[0.006048ms] java.lang.StringBuilder:toString() #28
+        `---[0.084138ms] java.io.PrintStream:println() #28
+
+Command execution times exceed limit: 1, so command will exit. You can set it with -n option.
+```
+
 #### Ignore jdk method
 
 ```bash
diff --git a/site/src/site/sphinx/trace.md b/site/src/site/sphinx/trace.md
index 84b8a560c..fae66bbcd 100644
--- a/site/src/site/sphinx/trace.md
+++ b/site/src/site/sphinx/trace.md
@@ -54,6 +54,30 @@ Affect(class-cnt:1 , method-cnt:1) cost in 42 ms.
         `---[0.170316ms] demo.MathGame:print()
 ```
 
+#### trace次数限制
+
+如果方法调用的次数很多，那么可以用`-n`参数指定捕捉结果的次数。比如下面的例子里，捕捉到一次调用就退出命令。
+
+```bash
+$ trace demo.MathGame run -n 1
+Press Q or Ctrl+C to abort.
+Affect(class-cnt:1 , method-cnt:1) cost in 35 ms.
+`---ts=2019-11-28 15:54:28;thread_name=main;id=1;is_daemon=false;priority=5;TCCL=sun.misc.Launcher$AppClassLoader@3d4eac69
+    `---[0.866311ms] demo.MathGame:run()
+        +---[0.044001ms] java.util.Random:nextInt() #23
+        +---[0.069037ms] demo.MathGame:primeFactors() #24 [throws Exception]
+        +---[0.003227ms] java.lang.StringBuilder:<init>() #28
+        +---[0.006155ms] java.lang.Integer:valueOf() #28
+        +---[0.071335ms] java.lang.String:format() #28
+        +---[min=0.002142ms,max=0.002237ms,total=0.004379ms,count=2] java.lang.StringBuilder:append() #28
+        +---[0.011072ms] java.lang.Exception:getMessage() #28
+        +---[0.006048ms] java.lang.StringBuilder:toString() #28
+        `---[0.084138ms] java.io.PrintStream:println() #28
+
+Command execution times exceed limit: 1, so command will exit. You can set it with -n option.
+```
+
+
 #### 过滤掉jdk的函数
 
 ```bash