diff --git a/en/README.html b/en/README.html index 6c6d800e2..254cc44c4 100644 --- a/en/README.html +++ b/en/README.html @@ -92,10 +92,10 @@
  • Advanced usage
  • Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • diff --git a/en/_sources/batch-support.md.txt b/en/_sources/batch-support.md.txt index 6672f2006..68430721f 100644 --- a/en/_sources/batch-support.md.txt +++ b/en/_sources/batch-support.md.txt @@ -1,15 +1,15 @@ Batch Processing ================ -With the help of `Batch Processing`, you can run several commands in one line and get the results. +With the help of Batch Processing, you can run multiple commands in batch and get the final result at the end. ### Usage -#### Step-1: Create the script +#### Step 1: Create the script -Creating a `test.as` script suffixed with `as` here for consistency (actually any suffix is acceptable). +Create a `test.as` script suffixed with `as`. Here `as` is suggested for the suffix of the filename, but in fact any suffix is acceptable. -``` +```bash ➜ arthas git:(develop) cat /var/tmp/test.as help dashboard -b -n 1 @@ -18,21 +18,21 @@ thread sc -d org.apache.commons.lang.StringUtils ``` -Attention: -* each command takes each independent line; -* `dashboard` command should include `-b` to turn on batch mode and `-n` to ensure the script ends; -* commands as `watch/tt/trace/monitor/stack` should include `-n` option to ensure the script ends; -* [asynchronous](async.md) can also be used as `watch c.t.X test returnObj > &`; +Note: +* Each command takes one line. +* Batch mode (via `-b`) and execution times (via `-n`) must be explicitly specified for `dashboard`, otherwise batch script cannot terminate. +* Commands such as `watch`/`tt`/`trace`/`monitor`/`stack` should include `-n` option to ensure the script can be able to quit. +* Also consider to use `async` (for example: `watch c.t.X test returnObj > &`) to put commands run at background and get the output from the log file, see more from [asynchronous job](async.md) -#### Step-2: Run the script +#### Step 2: Run the script -Using `-b` to turn on script mode, and `-f` to run it and you can also *redirect* the output as: +Use `-b` to turn on batch mode, and use `-f` to specify the script file. By default the result will be output to the standard output, but you can redirect the output to the file like this: ```bash ./as.sh -b -f /var/tmp/test.as 56328 > test.out ``` -#### Step-3: Check the outputs +#### Step 3: Check the outputs ```bash cat test.out diff --git a/en/_sources/classloader.md.txt b/en/_sources/classloader.md.txt index 8fccd39e5..4d2976704 100644 --- a/en/_sources/classloader.md.txt +++ b/en/_sources/classloader.md.txt @@ -1,23 +1,23 @@ classloader =========== -Check the inheritance tree, urls and classes loading profiles of the class loaders. +View hierarchy, urls and classes-loading info for the class-loaders. -It can be a great help for `ResourceNotFoundException` when you can use command `classloader` to specify a class loader to `getResources` and print all the urls of the valid resources. +`classloader` can search and print out the URLs for a specified resource from one particular classloader. It is quite handy when analyze `ResourceNotFoundException`. ### Options |Name|Specification| |---:|:---| -|[l]|list all class loader instances based on thread count| -|[t]|print the inheritance structure of the class loaders| +|[l]|list all class loader instances| +|[t]|print classloader's hierarchy| |[a]|list all the classes loaded by all the class loaders (use it with great caution since the output can be huge)| -|[c:]|get the hashcode of the class loader| +|[c:]|print classloader's hashcode| |[c: r:]|using class loader to search resource| ### Usage -* Categorised by class loader +* View statistics categorized by class type ```bash $ classloader @@ -36,7 +36,7 @@ $ classloader Affect(row-cnt:11) cost in 66 ms. ``` -* Categorized by class loader instance +* View statistics categorized by loaded classes number ```bash $ classloader -l @@ -86,7 +86,7 @@ $ classloader -l sun.reflect.misc.MethodUtil@1201f221 1 1201f221 sun.misc.Launcher$AppClassLoader@14dad5dc ``` -* Check inheritance tree of the class loaders +* View class-loaders hierarchy ```shell $ classloader -t @@ -100,7 +100,7 @@ $ classloader -t | | +-sun.reflect.DelegatingClassLoader@73f44f24 ``` -* Check URL of the class loader +* Show the URLs from which to load classes and resources for one particular URLClassLoader ```shell $ classloader -c 5ffe9775 @@ -113,7 +113,7 @@ file:/Users/hello/soft/taobao-tomcat-7.0.64/deploy/taobao-hsf.sar/lib/pandora.th file:/Users/hello/soft/taobao-tomcat-7.0.64/deploy/taobao-hsf.sar/lib/picocontainer-2.14.3.jar ``` -* Using class loader to search for resource +* Use one class loader to search one particular resource ```shell $ classloader -c 226b143b -r META-INF/MANIFEST.MF @@ -121,7 +121,7 @@ $ classloader -c 226b143b -r META-INF/MANIFEST.MF jar:file:/Users/hello/.m2/repository/javax/annotation/jsr250-api/1.0/jsr250-api-1.0.jar!/META-INF/MANIFEST.MF ``` -* Using class loader to look for `*.class` file +* Use one class loader to search one particular class ```shell $ classloader -c 1b6d3586 -r java/lang/String.class diff --git a/en/_sources/commands.md.txt b/en/_sources/commands.md.txt index 8ef88a647..48c4bb959 100644 --- a/en/_sources/commands.md.txt +++ b/en/_sources/commands.md.txt @@ -1,16 +1,12 @@ All Commands ============= - - * [dashboard](dashboard.md) * [thread](thread.md) * [jvm](jvm.md) * [sysprop](sysprop.md) * [getstatic](getstatic.md) - - * [sc](sc.md) * [sm](sm.md) * [dump](dump.md) @@ -28,16 +24,16 @@ All Commands * [options](options.md) -### Basic Commands +### Basic Arthas Commands -* help - check the assistant info for the command -* cls - clear out the current screen area -* session - check the current session profile -* [reset](reset.md) - clear the injected code from the classes (B.T.W when Arthas server closed, all the injected will also be cleared) -* version - the version of the working Arthas +* help - examine help information +* cls - clear out the screen +* session - examine the current session +* [reset](reset.md) - reset enhanced classes. All enhanced classes will be reset to their original states. When Arthas server closes, all these enhanced classes will be reset too +* version - print out Arthas's version * quit - exit the current Arthas client without affecting other clients -* shutdown - terminate the Arthas server and all clients -* [keymap](keymap.md) - shortcuts for Arthas and also you can define your own +* shutdown - terminate the Arthas server, all the Arthas clients connecting to this server will be disconnected +* [keymap](keymap.md) - list all Arthas keyboard shortcuts and shortcut customizations. diff --git a/en/_sources/dashboard.md.txt b/en/_sources/dashboard.md.txt index f41b5acbe..21c3fa601 100644 --- a/en/_sources/dashboard.md.txt +++ b/en/_sources/dashboard.md.txt @@ -1,11 +1,11 @@ dashboard ========= -This is the realtime dashboard for the system; press `Ctrl+C` to exit. +> This is the real time statistics dashboard for the current system, press `Ctrl+C` to exit. -When running in *Ali-tomcat*, the dashboard will present the realtime statistics of the tomcat including [QPS](https://en.wikipedia.org/wiki/Queries_per_second), RT, error counts, thread profile and the like. +When running in Apache Tomcat Alibaba edition, the dashboard will also present the real time statistics of the tomcat, including [QPS](https://en.wikipedia.org/wiki/Queries_per_second), RT, error counts, and thread pool, etc. -### A Demo +### Usage ``` $ dashboard @@ -44,18 +44,18 @@ processors 4 threadpool uptime 16020s busy 0 ``` -### Specification +### Notes on column headers -* ID: thread ID in JVM (this is different from the nativeID in thread dump) +* ID: JVM thread ID, pls. note this ID is different from the nativeID in jstack * NAME: thread name -* GROUP: group the thread is in -* STATE: the current state of the thread -* PRIORITY: within 1 ~ 10 (the higher the number, the higher the priority) -* CPU%: CPU usage ratio within 100ms -* TIME: total running time in minute:second format -* INTERRUPTED: the thread interrupted state -* DAEMON: is daemon thread or not - -### Screenshots +* GROUP: thread group name +* PRIORITY: thread priority, ranged from 1 to 10. The greater number, the higher priority +* STATE: thread state +* CPU%: the ratio of CPU usage for the thread, sampled every 100ms +* TIME: total running time in `minute:second` format +* INTERRUPTED: the thread interruption state +* DAEMON: daemon thread or not + +### Screenshot ![alt text](../_static/dashboard.png "dashboard") diff --git a/en/_sources/dump.md.txt b/en/_sources/dump.md.txt index c0e157f23..e3b24b6c8 100644 --- a/en/_sources/dump.md.txt +++ b/en/_sources/dump.md.txt @@ -1,15 +1,15 @@ dump === -Dump the bytecode the loaded classes to a specified directory. +> Dump the bytecode for the particular classes to the specified directory. ### Options |Name|Specification| |---:|:---| -|*class-pattern*|pattern for the class name| -|[c:]|hashcode of the [class loader](classloader.md) that loaded the class| -|[E]|turn on regex matching while the default is wildcard matching| +|*class-pattern*|class name pattern| +|`[c:]`|hashcode of the [class loader](classloader.md) that loaded the target class| +|`[E]`|turn on regex match, the default behavior is wild card match| ### Usage diff --git a/en/_sources/getstatic.md.txt b/en/_sources/getstatic.md.txt index a6927f511..f784f9169 100644 --- a/en/_sources/getstatic.md.txt +++ b/en/_sources/getstatic.md.txt @@ -1,13 +1,13 @@ getstatic ========= -Check the static fields of classes conveniently as `getstatic class_name field_name` +Check the static fields of classes conveniently, the usage is `getstatic class_name field_name`. -Tip: if the *field* is a composite object, you can even use [`OGNL`](https://en.wikipedia.org/wiki/OGNL) to traverse, filter and access the internal properties of it. +Tip: if the static field is a complex class, you can even use [`OGNL`](https://en.wikipedia.org/wiki/OGNL) to traverse, filter and access the inner properties of this class. -E.g. suppose `n` is a `Map` and the key is a `Enum` then if you want to get the key with a specific `Enum` value - `STOP` or `a`, you can achieve it as: +E.g. suppose `n` is a `Map` and its key is a `Enum`, then you can achieve this if you want to pick the key with a specific `Enum` value: -``` +```bash $ getstatic com.alibaba.arthas.Test n 'entrySet().iterator.{? #this.key.name()=="STOP"}' field: n @ArrayList[ diff --git a/en/_sources/groovy.md.txt b/en/_sources/groovy.md.txt new file mode 100644 index 000000000..991adff8c --- /dev/null +++ b/en/_sources/groovy.md.txt @@ -0,0 +1,170 @@ +groovy +=== + +> Arthas support groovy scripting to allow user to use script like BTrace. It is possible to use if/for/switch/while in groovy scripting, but has more limitations compared to BTrace. + +### Limitations + +1. Prohibit from alternating the original logic. Like `watch` command, The major purpose of scripting is monitoring and observing. +1. Only allow to monitor at the stages of before/success/exception/finish on one method. + +### Parameters + +|Parameter|Explanation| +|---:|:---| +|*class-pattern*|class name pattern| +|*method-pattern*|method name pattern| +|*script-filepath*|the absolute path of the groovy script| +|[S]|match all sub classes| +|[E]|enable regex match, the default is wildcard match| + +Note: the third parameter `script-filepath` must be the absolute path of the groovy script, for example `/tmp/test.groovy`. It is not recommended to use relative path, e.g. `./test.groovy`. + +### Explanation on the important callbacks + +```java +/** + * Listeners for script to enhance the class + */ +interface ScriptListener { + + /** + * When the script is created + * + * @param output Output + */ + void create(Output output); + + /** + * When the script is destroyed + * + * @param output Output + */ + void destroy(Output output); + + /** + * Before the method executes + * + * @param output Output + * @param advice Advice + */ + void before(Output output, Advice advice); + + /** + * After the method returns + * + * @param output Output + * @param advice Advice + */ + void afterReturning(Output output, Advice advice); + + /** + * After the method throws exceptions + * + * @param output Output + * @param advice Advice + */ + void afterThrowing(Output output, Advice advice); + +} +``` + +### `Advice` parameter + +`Advice` contains all information necessary for notification. Refer to [expression core parameters](advice-class.md) for more details. + +### `Output` parameter + +There are three methods in `Output`, used for outputting the corresponding text. + +```java +/** + * Output + */ +interface Output { + + /** + * Output text without line break + * + * @param string Text to output + * @return this + */ + Output print(String string); + + /** + * Output text with line break + * + * @param string Text to output + * @return this + */ + Output println(String string); + + /** + * Finish outputting from the script + * + * @return this + */ + Output finish(); + +} +``` + +### A groovy sample script to output logs + +```groovy +import com.taobao.arthas.core.command.ScriptSupportCommand +import com.taobao.arthas.core.util.Advice + +import static java.lang.String.format + +/** + * Output method logs + */ +public class Logger implements ScriptSupportCommand.ScriptListener { + + @Override + void create(ScriptSupportCommand.Output output) { + output.println("script create."); + } + + @Override + void destroy(ScriptSupportCommand.Output output) { + output.println("script destroy."); + } + + @Override + void before(ScriptSupportCommand.Output output, Advice advice) { + output.println(format("before:class=%s;method=%s;paramslen=%d;%s;", + advice.getClazz().getSimpleName(), + advice.getMethod().getName(), + advice.getParams().length, advice.getParams())) + } + + @Override + void afterReturning(ScriptSupportCommand.Output output, Advice advice) { + output.println(format("returning:class=%s;method=%s;", + advice.getClazz().getSimpleName(), + advice.getMethod().getName())) + } + + @Override + void afterThrowing(ScriptSupportCommand.Output output, Advice advice) { + output.println(format("throwing:class=%s;method=%s;", + advice.getClazz().getSimpleName(), + advice.getMethod().getName())) + } +} +``` + +Run the script like this: + +```bash +$ groovy com.alibaba.sample.petstore.dal.dao.ProductDao getProductById /Users/zhuyong/middleware/arthas/scripts/Logger.groovy -S +script create. +Press Ctrl+C to abort. +Affect(class-cnt:1 , method-cnt:1) cost in 102 ms. +before:class=IbatisProductDao;method=getProductById;paramslen=1;[Ljava.lang.Object;@45df64fc; +returning:class=IbatisProductDao;method=getProductById; +before:class=IbatisProductDao;method=getProductById;paramslen=1;[Ljava.lang.Object;@5b0e2d00; +returning:class=IbatisProductDao;method=getProductById; +``` diff --git a/en/_sources/index.md.txt b/en/_sources/index.md.txt index 97265a95c..62f48d714 100644 --- a/en/_sources/index.md.txt +++ b/en/_sources/index.md.txt @@ -1,49 +1,46 @@ Arthas Documentation === -**[中文文档/Chinese Docs](https://alibaba.github.io/arthas/)** +**[中文文档](https://alibaba.github.io/arthas/)** ![arthas](arthas.png) -`Arthas` is a Java Diagnostic tool open sourced by Alibaba. - -Arthas help developers in trouble-shooting production issues for Java applications without modifying code or restarting servers. +Arthas is a Java diagnostic tool open-sourced by Alibaba middleware team. It is widely adopted and popular among the developers inside Alibaba. Arthas helps developers in trouble-shooting issues in production environment for Java based applications without modifying code or restarting servers. ### Background -Often times, the production system network is inaccessible from local development environment. If issues are encountered in production systems, it is impossible to use IDE to debug the application remotely. More importantly, debugging in production environment is unacceptable, as it will suspend all the threads, which leads to blocking of business services. +Oftentimes the production system network is inaccessible from local development environment. If issues are encountered in production systems, it is impossible to use IDE to debug the application remotely. What's even worse, debugging in production environment is unacceptable, as it will suspend all the threads, leading to services downtime. -Developers could always try to reproduce the same issue on the test/staging environment. However, this is tricky as some issues cannot be be reproduced easily on a different environment, or even disappear once restarted. +Developers could always try to reproduce the same issue on the test/staging environment. However, this is tricky as some issues cannot be reproduced easily in a different environment, or even disappear once restarted. -And if you're thinking of adding some logs to your code to help trouble-shoot the issue, you will have to go through the following lifecycle; test, staging, and then to production. Time is money! This approach is inefficient! Besides, the issue may not be reproducible once the JVM is restarted, as described above. +And if you're thinking of adding some logs to your code to help trouble-shoot the issue, you will have to go through the following lifecycle: test, staging, and then to production. Time is money! This approach is inefficient! Worse still, the issue may not be fixed since it might be irreproducible once the JVM is restarted, as described above. -Arthas was built to solve these issues. A developer can trouble-shoot your production issues on-the-fly. No JVM restart, no additional code changes. Arthas works as an observer, which will never suspend your existing threads. +Arthas is built to solve these issues. A developer can troubleshoot production issues on the fly. No JVM restart, no additional code changes. Arthas works as an observer, that is, it will never suspend your running threads. ### Key features * Check whether a class is loaded? Or where the class is loaded from? (Useful for trouble-shooting jar file conflicts) * Decompile a class to ensure the code is running as expected. -* View classloader statistics, e.g. the number of classloaders, the number of classes loaded per classloader, the classloader hierarchy, possible classloader leaks, etc. -* View the method invocation details, e.g. method parameter, return object, thrown exception, and etc. -* Check the stack trace of specified method invocation. This is useful when a developers wants to know the caller of the said method. +* Check classloader statistics, e.g. the number of classloaders, the number of classes loaded per classloader, the classloader hierarchy, possible classloader leaks, etc. +* Check the method invocation details, e.g. method parameter, returned values, exceptions and etc. +* Check the stack trace of specified method invocation. This is useful when a developer wants to know the caller of the method. * Trace the method invocation to find slow sub-invocations. -* Monitor method invocation statistics, e.g. qps, rt, success rate and etc. -* Monitor system metrics, thread states and cpu usage, gc statistics, and etc. +* Monitor method invocation statistics, e.g. QPS (Query Per Second), RT (Return Time), success rate and etc. +* Monitor system metrics, thread states and CPU usage, GC statistics and etc. * Supports command line interactive mode, with auto-complete feature enabled. -* Supports telnet and websocket, which enables both local and remote diagnostics with command line and browsers. - +* Supports telnet and WebSocket, which enables both local and remote diagnostics with command line and browsers. Contents -------- -English version has just been finished. If you would like to make it better, please check [here](https://github.com/alibaba/arthas/issues/51) and submit your PM. +English version has just been finished. If you would like to make it better, please check [here](https://github.com/alibaba/arthas/issues/51) and submit your pull request. * [Installation](install-detail.md) * [Quick start](quick-start.md) * [Advanced usage](advanced-use.md) * [Commands](commands.md) * [User cases](https://github.com/alibaba/arthas/issues?q=label%3Auser-case) -* [Release Notes](release-notes.md) * [Questions and answers](https://github.com/alibaba/arthas/issues?q=label%3Aquestion-answered) * [Fork me at GitHub](https://github.com/alibaba/arthas) * [CONTRIBUTING](https://github.com/alibaba/arthas/blob/master/CONTRIBUTING.md) +* [Release Notes](release-notes.md) diff --git a/en/_sources/install-detail.md.txt b/en/_sources/install-detail.md.txt index 00a5d0cf9..27aba125e 100644 --- a/en/_sources/install-detail.md.txt +++ b/en/_sources/install-detail.md.txt @@ -1,51 +1,45 @@ -Arthas Install +Install Arthas ============== ## Linux/Unix/Mac -You can install Arthas in one single line as: +You can install Arthas with one single line command on Linux, Unix, and Mac. Pls. copy the following command and paste it into the command line, then press *Enter* to run: ```bash curl -L https://alibaba.github.io/arthas/install.sh | sh ``` -The command line above will download the booting script `as.sh` to the current directory and you can then start Arthas by `./as.sh`, for more help info you can use `./as.sh -h` to check the details. +The command above will download the bootstrap script `as.sh` to the current directory. You can move it the any other place you want, or put its location in `$PATH`. -By the way, you can also add the absolute path of the script `as.sh` to `$PATH` to make it available globally. +You can enter its interactive interface by executing `as.sh`, or execute `as.sh -h` for more help information. ## Windows Latest Version: [![Arthas](https://img.shields.io/maven-central/v/com.taobao.arthas/arthas-packaging.svg?style=flat-square "Arthas")](http://search.maven.org/classic/#search%7Cga%7C1%7Cg%3A%22com.taobao.arthas%22%20AND%20a%3A%22arthas-packaging%22) -Download the latest `bin.zip`, unzip the package and you can find the `as.bat`. For now this script will only take one argument `pid` which means you can only diagnose the local Java process. (Welcome any bat script expert to make it better :heart:) +Download the latest `bin.zip`, unzip the package, and find `as.bat` from 'bin' directory. For now this script will only take one argument `pid`, which means you can only diagnose the local Java process. (Welcome any bat script expert to make it better :heart:) ```bash as.bat ``` -A small tip: +To have a better experience, you can start the Arthas Server locally by executing `as.bat `, then run `./as.sh @:` in another Linux/Unix/Mac machine. -If you are asking for better UX, you can start the Arthas Server locally by `as.bat ` and then use `./as.sh @:`in another Linux/Unix/Mac machine. - - -Another tip: - -If in Windows, the color is not working as expect. You can try [conemu](https://sourceforge.net/projects/conemu) to get it to work. +> If the color is not working as expect on windows, you can use [conemu](https://sourceforge.net/projects/conemu) to get it to work. ## Manual Installation [Manual Installation](manual-install.md) -## Advanced Manual Boot +If you fail to boot Arthas with the provided batch file, you could try to assemble the bootstrap command in the following way. -If you cannot boot Arthas, try to pass in all the critical options manually as the following steps: -1. locate the java for JVM: +1. Locate java in the target JVM: - Linux/Unix/Mac: `ps aux | grep java` - Windows: open the Process Monitor to search java -2. Concatenate the command +2. Assemble bootstrap command: Let's suppose we are using `/opt/jdk1.8/bin/java`, then the command should be: @@ -58,21 +52,20 @@ If you cannot boot Arthas, try to pass in all the critical options manually as t -agent /tmp/arthas-packaging/arthas/arthas-agent.jar ``` - * `-Xbootclasspath` add tools.jar - * `-jar /tmp/arthas-packaging/arthas-core.jar` specify main entry - * `-pid 15146` specify the target java process pid - * `-target-ip 127.0.0.1` specify the IP - * `-telnet-port 3658 -http-port 8563` specify telnet and http ports - * `-core /tmp/arthas-packaging/arthas-core.jar -agent /tmp/arthas-packaging/arthas/arthas-agent.jar` specify core/agent jar package - - - But if you are using JDK 1.9 or above，then you do not need to add `tools.jar` in option `-Xbootclasspath`. - - F.Y.I the booting log will be printed to `~/logs/arthas/arthas.log`. - -3. Connect via telnet + Note: + + * `-Xbootclasspath` adds tools.jar + * `-jar /tmp/arthas-packaging/arthas-core.jar` specifies main entry + * `-pid 15146` specifies the target java process PID + * `-target-ip 127.0.0.1` specifies the IP + * `-telnet-port 3658 -http-port 8563` specifies telnet and HTTP ports for remote access + * `-core /tmp/arthas-packaging/arthas-core.jar -agent /tmp/arthas-packaging/arthas/arthas-agent.jar` specifies core/agent jar package + + If you are running on JDK 1.9 or above，then it's unncessary to add `tools.jar` in option `-Xbootclasspath`. + + You can find the logs from `~/logs/arthas/arthas.log`. - When attached successfully, you can connect it with +3. Use telnet to connect once attaching to the target JVM (in step 2) succeeds ```bash telnet localhost 3658 @@ -86,12 +79,10 @@ Download the latest `doc.zip`. ## Uninstall -### Linux/Unix/Mac +* On Linux/Unix/Mac, delete the files with the following command: -```bash -rm -rf ~/.arthas/ ~/.arthas_history -``` - -### Windows + ```bash + rm -rf ~/.arthas/ ~/.arthas_history + ``` -Directly delete the `zip` and unzipped files. +* On Windows, simply delete the zip file and unzipped files. diff --git a/en/_sources/jad.md.txt b/en/_sources/jad.md.txt index ef6a55ad5..a7c27cfcf 100644 --- a/en/_sources/jad.md.txt +++ b/en/_sources/jad.md.txt @@ -1,27 +1,24 @@ jad === -De-compile specified loaded classes. +> De-compile the specified classes. -`jad` helps to *de-compile* the byte code in JVM to the source code to assist you to better understand the logic behind. +`jad` helps to de-compile the byte code running in JVM to the source code to assist you to understand the logic behind better. -F.Y.I -* the de-compiled code will be grammatically highlighted for readability in Arthas console; -* there might be some trivial grammar errors but it won't affect the logic understanding. +* The de-compiled code is syntax highlighted for better readability in Arthas console. +* It is possible that there's grammar error in the de-compiled code, but it should not affect your interpretation. ### Options |Name|Specification| |---:|:---| |*class-pattern*|pattern for the class name| -|[c:]|hashcode of the class loader that loaded the class| -|[E]|turn on regex matching while the default is wildcard matching| +|`[c:]`|hashcode of the class loader that loads the class| +|`[E]`|turn on regex match while the default is wildcard match| ### Usage -When several class loaders loaded the same class: -1. `jad` to get the hashcode of the class loader; -2. `jad -c ` to get the de-compiled class loaded by the specified class loader. +> If the target class is loaded by multiple classloaders, `jad` outputs the `hashcode` of the corresponding classloaders, then you can re-run `jad` and specify `-c ` to de-compile the target class from the specified classloader. ```java $ jad org.apache.log4j.Logger @@ -156,7 +153,3 @@ private Map directMetrics(String ip, String[] metrics) { Affect(row-cnt:1) cost in 1508 ms. ``` - -F.Y.I - -Inner class is not yet supported, you can just check the *outer* class to further check the inner class. diff --git a/en/_sources/jvm.md.txt b/en/_sources/jvm.md.txt index b787281b7..8ab378a73 100644 --- a/en/_sources/jvm.md.txt +++ b/en/_sources/jvm.md.txt @@ -1,7 +1,7 @@ jvm === -Check the JVM profile +> Check the current JVM's info ### Usage @@ -95,16 +95,16 @@ $ jvm Affect cost in 2 ms. ``` -### thread-related +### Thread related * COUNT: the count of active threads * DAEMON-COUNT: the count of active daemon threads * PEAK-COUNT: the maximum count of the live threads since JVM starts * STARTED-COUNT: the total count of the created threads since JVM starts -* DEADLOCK-COUNT: the count of deadlock threads +* DEADLOCK-COUNT: the count of deadlocked threads -### fileDescriptor-related +### File descriptor related * MAX-FILE-DESCRIPTOR-COUNT：the count of max file descriptor JVM process can open -* OPEN-FILE-DESCRIPTOR-COUNT：the current count of file descriptor JVM process open \ No newline at end of file +* OPEN-FILE-DESCRIPTOR-COUNT：the current count of file descriptor JVM process open diff --git a/en/_sources/keymap.md.txt b/en/_sources/keymap.md.txt index 1f2321298..e98456f1c 100644 --- a/en/_sources/keymap.md.txt +++ b/en/_sources/keymap.md.txt @@ -1,11 +1,10 @@ Arthas Console Keymap === -`keymap` command print current keymap. +Use `keymap` command to print the current keymap: The default keymap is: - | Shortcut | Shortcut Description | Command Name | Command Description | | ------------- | ---------------- | -------------------- | ---------------- | | `"\C-a"` | ctrl + a | beginning-of-line | go to the beginning of the line | @@ -28,16 +27,14 @@ The default keymap is: | `"\C-x\e[3~"` | | backward-kill-line | | | `"\e\C-?"` | | backward-kill-word | | - -* You can enter `Tab` to get automatic prompts at any time. -* After typing the command, type `-` or `--`, then press `tab` to display the specific options of this command. - +* Press `tab` to enable auto-completion prompt at any time. +* Enter command and `-` or `--`, then press `tab` to display the concrete options for the current command. #### Custom shortcuts -Create a new `$USER_HOME/.arthas/conf/inputrc` file in the current user home directory and add a custom configuration. +Specify customization in `$USER_HOME/.arthas/conf/inputrc` file in the current user home directory. -Suppose I am a heavy user of vim. I want to set `ctrl+h` to the cursor forward character. Set it as follows, first copy the default configuration. +Vim user may want to map `ctrl+h` to moving the cursor forward one character. To achieve this, copy the default configuration first, ``` "\C-a": beginning-of-line @@ -61,14 +58,14 @@ Suppose I am a heavy user of vim. I want to set `ctrl+h` to the cursor forward c "\e\C-?": backward-kill-word ``` -Then replace `"\C-h": backward-delete-char` with `"\C-h": backward-char`, then reconnect. +then replace `"\C-h": backward-delete-char` with `"\C-h": backward-char`, then reconnect to Arthas console to take effect. -#### Shortcuts about async +#### Shortcuts for jobs -* ctrl + c: Terminate current command -* ctrl + z: Suspend the current command, you can restore this command with bg/fg, or kill it. -* ctrl + a: Go to the beginning the line -* ctrl + e: Go to the end of the line +* `ctrl + c`: Terminate current command +* `ctrl + z`: Suspend the current command, you can restore this command with `bg`/`fg`, or `kill` it. +* `ctrl + a`: Go to the beginning the line +* `ctrl + e`: Go to the end of the line diff --git a/en/_sources/manual-install.md.txt b/en/_sources/manual-install.md.txt index d5d50e617..8048aa886 100644 --- a/en/_sources/manual-install.md.txt +++ b/en/_sources/manual-install.md.txt @@ -1,31 +1,33 @@ -Manual Installation +Manually Install Arthas =================== -### Download +1. Download the latest version -**Latest `bin.zip`**: [![Arthas](https://img.shields.io/maven-central/v/com.taobao.arthas/arthas-packaging.svg?style=flat-square "Arthas")](http://search.maven.org/classic/#search%7Cga%7C1%7Cg%3A%22com.taobao.arthas%22%20AND%20a%3A%22arthas-packaging%22) + **Latest version**: [![Arthas](https://img.shields.io/maven-central/v/com.taobao.arthas/arthas-packaging.svg?style=flat-square "Arthas")](http://search.maven.org/classic/#search%7Cga%7C1%7Cg%3A%22com.taobao.arthas%22%20AND%20a%3A%22arthas-packaging%22) + If the download speed is slow, try to use [Ali cloud mirror repository](https://maven.aliyun.com/), for example, to download version `3.x.x` (you can replace `3.x.x` in the example URL if you want to download other version), the download URL is: https://maven.aliyun.com/repository/public/com/taobao/arthas/arthas-packaging/3.x.x/arthas-packaging-3.x.x-bin.zip -If the download is slow, try to download from the [repository in AliYun](https://maven.aliyun.com/); the downloading URL template is (remember to fill up the version `3.x.x` template to your needs) +2. Unzip zip file -`https://maven.aliyun.com/repository/public/com/taobao/arthas/arthas-packaging/3.x.x/arthas-packaging-3.x.x-bin.zip` -### Unzip + ```bash + unzip arthas-packaging-bin.zip + ``` -```bash -unzip arthas-packaging-bin.zip -``` +3. Install Arthas -### Install + It is recommended to completely remove all old versions of Arthas before installation. -```bash -sudo su admin -rm -rf /home/admin/.arthas/lib/* # remove all the leftover of the old outdated Arthas -cd arthas -./install-local.sh # switch the user based on the owner of the target Java process. -``` + ```bash + sudo su admin + rm -rf /home/admin/.arthas/lib/* # remove all the leftover of the old outdated Arthas + cd arthas + ./install-local.sh # switch the user based on the owner of the target Java process. + ``` -### Start +4. Start Arthas -```bash -./as.sh # make sure the old Arthas has been shutdown (using command shutdown); -``` + Make sure `shutdown` the old Arthas server before start. + + ```bash + ./as.sh + ``` diff --git a/en/_sources/monitor.md.txt b/en/_sources/monitor.md.txt index d77b4b64f..7c17ed2b1 100644 --- a/en/_sources/monitor.md.txt +++ b/en/_sources/monitor.md.txt @@ -1,22 +1,23 @@ monitor ======= -Monitor methods calling stack traces. +> Monitor method invocation. -F.Y.I +Monitor invocation for the method matched with `class-pattern` and `method-pattern`. -1. `monitor` is a persistent command, it never returns until you press `Ctrl+C` to manually stop it; -2. the server runs the jobs in the background; -3. injected monitoring code will become invalid automatically once the monitoring jobs being terminated; -4. in theory, Arthas will not change any original behaviors but if it does, please do not hesitate to start an [issue](https://github.com/alibaba/arthas/issues). +`monitor` is not a command returning immediately. -### Properties monitored +A command returning immediately is a command immediately returns with the result after the command is input, while a non-immediate returning command will keep outputting the information from the target JVM process until user presses `Ctrl+C`. -|Property|Specification| +On Arthas's server side, the command is running as a background job, but the weaved code will not take further effect once the job is terminated, therefore, it will not impact the performance after the job quits. Furthermore, Arthas is designed to have no side effect to the business logic. + +### Items to monitor + +|Item|Specification| |---:|:---| |timestamp|timestamp| |class|Java class| -|method|constructor and regular methods| +|method|method (constructor and regular methods)| |total|calling times| |success|success count| |fail|failure count| @@ -25,12 +26,14 @@ F.Y.I ### Parameters +Parameter `[c:]` stands for cycles of statistics. Its value is an integer value in seconds. + |Name|Specification| |---:|:---| |*class-pattern*|pattern for the class name| |*method-pattern*|pattern for the method name| -|[E]|turn on regex matching while the default is wildcard matching| -|[c:]|cycle of output with default value: `60 s`| +|`[E]`|turn on regex matching while the default is wildcard matching| +|`[c:]`|cycle of statistics, the default value: `120`s| ### Usage diff --git a/en/_sources/options.md.txt b/en/_sources/options.md.txt index 51bd2efb2..c008e554f 100644 --- a/en/_sources/options.md.txt +++ b/en/_sources/options.md.txt @@ -1,22 +1,22 @@ options === -### Global options +> Global options |Name| Default Value | Description | | ------------------------- | ----- | ---------------------------------------- | -| unsafe | false | Enable system-level class enhancement; JVM might crash, if you turn it on (use with great caution :exclamation:) | -| dump | false | Enable support for dumping enhanced class to external files; if turned on, class file will be dumped to`/${application dir}/arthas-class-dump/`，please check console output for specific location | -| batch-re-transform | true | re-transform matched classes in batch | -| json-format | false | Enable output in JSON format | -| disable-sub-class | false | Disabling child class matching: by default child class will be matched while matching target class; if you wish exact matching, you should turn it off | -| debug-for-asm | false | Print ASM-related debug message | -| save-result | false | Enable saving logs for task results: when true, all command results will be saved to `/home/admin/logs/arthas/arthas.log` | -| job-timeout | 1d | Default timeout for background jobs: jobs will be stopped once timed out (i.e. 1d, 2h, 3m, 25s)| +| unsafe | false | whether to enhance to system-level class. Use it with caution since JVM may hang| +| dump | false | whether to dump enhanced class to the external files. If it's on, enhanced class will be dumped into `/${application dir}/arthas-class-dump/`, the specific output path will be output in the console | +| batch-re-transform | true | whether to re-transform matched classes in batch| +| json-format | false | whether to output in JSON format| +| disable-sub-class | false | whether to enable matching child classes. The default value is `true`. If exact match is desire, turn off this flag| +| debug-for-asm | false | whether to enable ASM debugging log| +| save-result | false | whether to save execution result. All execution results will be saved to `/home/admin/logs/arthas/arthas.log` when it's turned on| +| job-timeout | 1d | default timeout for background jobs. Background job will be terminated once it's timed out (i.e. 1d, 2h, 3m, 25s)| ### Usage -Saving logs for command outputs, you can: +For example, to enable saving command execution result, input the command below: ``` $ options save-result true diff --git a/en/_sources/quick-start.md.txt b/en/_sources/quick-start.md.txt index d9a69ff7d..585a0a890 100644 --- a/en/_sources/quick-start.md.txt +++ b/en/_sources/quick-start.md.txt @@ -1,7 +1,7 @@ Quick Start =========== -## 1. Start A Demo +## 1. Start Demo Application Save the following code to a `Demo.java` and run the commands in shell as @@ -39,68 +39,67 @@ public class Demo { } ``` -## 2. Start Arthas - -### Linux/Unix/Mac +Save the contents above into `Demo.java`, then compile it under the command line: ```bash -./as.sh +javac Demo.java +java Demo ``` +You can also save and start the code in IDE. -1. the user to run the *command* should have the same privilege as the owner of the target process, as a simple example you can try the following command if the target process is managed by user `admin`: +## 2. Start Arthas - ```bash - sudo su admin && ./as.sh - # Or - sudo -u admin -EH ./as.sh - ``` +### Linux/Unix/Mac -2. For more details of the booting script, please refer to [Start Arthas](start-arthas.md). -3. If you cannot *attach* the target process, please check the logs under `~/logs/arthas` for troubleshooting. +Execute the following command in the command line: -4. Selecting the target process as: +```bash +./as.sh +``` - ``` - $ ./as.sh - Arthas script version: 3.0.2 - Found existing java process, please choose one and hit RETURN. - * [1]: 95428 - [2]: 22647 org.jetbrains.jps.cmdline.Launcher - [3]: 21736 - [4]: 13560 Demo - ``` +> The user to run this script *MUST* have the same privilege as the owner of the target process, as a simple example you can try the following command if the target process is managed by user `admin`: `sudo su admin && ./as.sh` or `sudo -u admin -EH ./as.sh`. For more details on the bootstrap script, please refer to [Start Arthas](start-arthas.md). If you cannot be able to attach to the target process, please check the logs under `~/logs/arthas` for troubleshooting. - We select `4` to check our Demo process and we then have +Select the target Java process to attach: - ``` - Connecting to arthas server... current timestamp is 1536656867 - Trying 127.0.0.1... - Connected to 127.0.0.1. - Escape character is '^]'. - ,---. ,------. ,--------.,--. ,--. ,---. ,---. - / O \ | .--. ''--. .--'| '--' | / O \ ' .-' - | .-. || '--'.' | | | .--. || .-. |`. `-. - | | | || |\ \ | | | | | || | | |.-' | - `--' `--'`--' '--' `--' `--' `--'`--' `--'`-----' +```bash +$ ./as.sh +Arthas script version: 3.0.2 +Found existing java process, please choose one and hit RETURN. +* [1]: 95428 + [2]: 22647 org.jetbrains.jps.cmdline.Launcher + [3]: 21736 + [4]: 13560 Demo +``` +The 'Demo' process is the fourth as shown above, press '4' then 'Enter'. Arthas will attach to the target process, and start to output: - wiki: https://alibaba.github.io/arthas - version: 3.0.1-RC-SNAPSHOT - pid: 13560 - timestamp: 1536656867894 - - $ - ``` +```bash +Connecting to arthas server... current timestamp is 1536656867 +Trying 127.0.0.1... +Connected to 127.0.0.1. +Escape character is '^]'. + ,---. ,------. ,--------.,--. ,--. ,---. ,---. + / O \ | .--. ''--. .--'| '--' | / O \ ' .-' +| .-. || '--'.' | | | .--. || .-. |`. `-. +| | | || |\ \ | | | | | || | | |.-' | +`--' `--'`--' '--' `--' `--' `--'`--' `--'`-----' + + +wiki: https://alibaba.github.io/arthas +version: 3.0.1-RC-SNAPSHOT +pid: 13560 +timestamp: 1536656867894 +``` ### Windows -Open the *DOS* console, under the unzipped arthas folder execute `as.bat ` +Open 'Command' window, execute `as.bat ` from where the Arthas package file is unzipped. ## 3. Check the Dashboard -Type in [dashboard](dashboard.md) and hit the *ENTER*, you will see it as (`Ctrl+C` to stop) +Type '[dashboard](dashboard.md)' and hit 'ENTER', a brief report on the current process will be shown as below, pls. `Ctrl+C` to stop: ``` $ dashboard @@ -138,7 +137,7 @@ java.home /Library/Java/JavaVir ## 4. watch -Input [watch](watch.md) to check the returned value of `Counter.value()`: +Use '[watch](watch.md)' to check the returned value of `Counter.value()`: ``` $ watch Demo$Counter value returnObj @@ -151,9 +150,10 @@ ts=2018-09-10 17:53:14;result=@Integer[624] ts=2018-09-10 17:53:15;result=@Integer[625] ``` -[more advanced usages](advanced-use.md) +Pls. refer to [advanced usages](advanced-use.md) for more information. ## 5. Exit Arthas -- `quit` or `exit` will just disconnect the current console connection while Arthas still running in the target process -- `shutdown` will terminate the Arthas completely +Use `quit` or `exit` to disconnect from the current process. The Arthas instance attached to the target process continues to live inside the process, and its port is standby for further connection. + +Use `shutdown` to have Arthas completely quit from the target process. diff --git a/en/_sources/redefine.md.txt b/en/_sources/redefine.md.txt index fdb2c6a85..146b8cb1a 100644 --- a/en/_sources/redefine.md.txt +++ b/en/_sources/redefine.md.txt @@ -1,21 +1,18 @@ redefine ======== -Load the external `*.class` files to **re-define** the JVM-loaded classes. +> Load the external `*.class` files to re-define the loaded peer class in JVM. Reference: [Instrumentation#redefineClasses](https://docs.oracle.com/javase/8/docs/api/java/lang/instrument/Instrumentation.html#redefineClasses-java.lang.instrument.ClassDefinition...-) -F.Y.I - -1. Re-defined classes cannot be restores any more; -2. Re-definition can fail (like adding a new field/method); for more information, please refer to JDK documentation +> Notes: Re-defined classes cannot be restored. There are chances that redefining may fail due to some reasons, for example: there's new field introduced in the new version of the class, pls. refer to JDK's documentation for the limitations. ### Options |Name|Specification| |---:|:---| -|[c:]|hashcode of the class loader| -|[p:]|absolute path of the external `*.class` (multiple paths supported)| +|`[c:]`|hashcode of the class loader| +|`[p:]`|absolute path of the external `*.class`, multiple paths are separated with 'space'| ### Usage diff --git a/en/_sources/reset.md.txt b/en/_sources/reset.md.txt index d32d8dc5d..cd24fbf92 100644 --- a/en/_sources/reset.md.txt +++ b/en/_sources/reset.md.txt @@ -1,7 +1,7 @@ reset === -> Reset all classes that have been enhanced by Arthas, and all enhanced classes will be reset when Arthas server `shutdown`. +> Reset all classes that have been enhanced by Arthas. These enhanced classes will also be reset when Arthas server is `shutdown`. ### Usage @@ -51,4 +51,4 @@ Affect(class-cnt:1 , method-cnt:1) cost in 15 ms. $ reset Affect(class-cnt:1 , method-cnt:0) cost in 9 ms. -``` \ No newline at end of file +``` diff --git a/en/_sources/save-log.md.txt b/en/_sources/save-log.md.txt index 0d580c513..4c2f25541 100644 --- a/en/_sources/save-log.md.txt +++ b/en/_sources/save-log.md.txt @@ -1,27 +1,25 @@ Log command outputs =================== -Log command outputs for later analysis, turned off by default. +> Log command outputs for later analysis -To turn it on, using [options](options.md) as: +* By default, this behavior is turned off. To enable it, execute the command below: -```bash -$ options save-result true - NAME BEFORE-VALUE AFTER-VALUE ----------------------------------------- - save-result false true -Affect(row-cnt:1) cost in 3 ms. -``` - -F.Y.I + ```bash + $ options save-result true + NAME BEFORE-VALUE AFTER-VALUE + ---------------------------------------- + save-result false true + Affect(row-cnt:1) cost in 3 ms. + ``` -1. logging file lies in: `{user.home}/logs/arthas-cache/result.log`; -2. remember to clean up the file to save disk space. + If the message above is output on the console, then this behavior is enabled successfully. + +* Log file path -### Asynchronous log + The command execution result will be save in `{user.home}/logs/arthas-cache/result.log`. Pls. clean it up regularly to save disk space. - :notes: :notes: -With the latest Arthas, you can log the outputs asynchronously in the background: +### Use asynchronous job to log ```bash $ trace Test t >> & @@ -29,9 +27,8 @@ job id : 2 cache location : /Users/zhuyong/logs/arthas-cache/28198/2 ``` -F.Y.I +By doing this, the command will run at background asynchronously, and output the execution result into `~/logs/arthas-cache/{PID}/{JobId}`: -1. `quit/exit` or `Ctrl+C` will not affect the asynchronous jobs :sparkles:; -2. default timeout for the background job is 1 day (you can set it via [options](options.md)); -3. outputs will be save to the `cache location` now (no matter what `save-result` is - not `~/logs/arthas-cache/result.log` any more). +* The background job will continue to run even if the current session is disconnected. The default job timeout value is 1 day, use global '[options](options.md)' command to alternate it. +* The execution result will be output into the file asynchronously. Pls. note the behavior of this command is not controlled by `save-result` option from global [options](options.md). No matter `save-result` is set to `true` or not, this command will write into `~/logs/arthas-cache/{PID}/{JobId}` anyway, instead of into `~/logs/arthas-cache/result.log`. diff --git a/en/_sources/sc.md.txt b/en/_sources/sc.md.txt index 6aaabebdc..9eb8ee553 100644 --- a/en/_sources/sc.md.txt +++ b/en/_sources/sc.md.txt @@ -1,31 +1,27 @@ sc == -Check the profiles of the loaded classes. +> Search classes loaded by JVM. -Abbreviated from *Search-Class*; with the help of this command, you can search out all the loaded classes in JVM. Supported options are: `[d]`、`[E]`、`[f]` and `[x:]`. +`sc` stands for search class. This command can search all possible classes loaded by JVM and show their information. The supported options are: `[d]`、`[E]`、`[f]` and `[x:]`. -Options -------- - -### Specification +### Supported Options |Name|Specification| |---:|:---| |*class-pattern*|pattern for the class name| |*method-pattern*|pattern for the method name| -|[d]|print the details of the current class including the source file, class declaration, the class loaders and the like.
    F.Y.I if a class is loaded by several class loaders, then the class will be printed several times| -|[E]|turn on regx matching while the default is wildcards matching| -|[f]|print the fields info of the current class, which ***must*** be used with `-d`| -|[x:]|the depth to print the static fields, whose default is `0` - directly invoke the `toString()`| +|`[d]`|print the details of the current class, including its code source, class specification, its class loader and so on.
    If a class is loaded by more than one class loader, then the class details will be printed several times| +|`[E]`|turn on regex match, the default behavior is wildcards match| +|`[f]`|print the fields info of the current class, MUST be used with `-d` together| +|`[x:]`|specify the depth of recursive traverse the static fields, the default value is '0' - equivalent to use `toString` to output| -Tip: -1. *class-patten* supports full qualified class name (e.g. com.taobao.test.AAA and com/taobao/test/AAA) -2. `sc` turned on the `sub-class` matching in default mode; if you do want to hide `sub-class`, you can just turn it off with [options](options.md) as `options disable-sub-class true`. +> *class-patten* supports full qualified class name, e.g. com.taobao.test.AAA and com/taobao/test/AAA. It also supports the format of 'com/taobao/test/AAA', so that it is convenient to directly copy class name from the exception stack trace without replacing '/' to '.'.

    +> `sc` turns on matching sub-class match by default, that is, `sc` will also search the sub classes of the target class too. If exact-match is desired, pls. use `options disable-sub-class true`. ### Usage -Check the static fields of a class using `sc -df class-name` +For example, use `sc -df class-name` to view class's static fields: ```shell $ sc -df org.apache.commons.lang.StringUtils diff --git a/en/_sources/sm.md.txt b/en/_sources/sm.md.txt index a11502b1d..1f9328068 100644 --- a/en/_sources/sm.md.txt +++ b/en/_sources/sm.md.txt @@ -1,12 +1,10 @@ sm == -Check the method profile of the loaded classes; +> Search method from the loaded classes. -Abbreviated from *Search-Method*, with which you can check all methods profiles of the loaded classes. +`sm` stands for search method. This command can search and show method information from all loaded classes. `sm` can only view the methods declared on the target class, that is, methods from its parent classes are invisible. -F.Y.I -`sm` only shows the methods declared in the current class; methods declared in ancestors will not be presented. ### Options @@ -14,12 +12,14 @@ F.Y.I |---:|:---| |*class-pattern*|pattern for class name| |*method-pattern*|pattern for method name| -|[d]|print the details of the method| -|[E]|turn on regex matching while the default mode is wildcard matching| +|`[d]`|print the details of the method| +|`[E]`|turn on regex matching while the default mode is wildcard matching| ### Usage -``` +Show methods from `org.apache.catalina.connector.Connector`: + +```bash $ sm org.apache.catalina.connector.Connector org.apache.catalina.connector.Connector-> org.apache.catalina.connector.Connector->setProperty @@ -61,6 +61,8 @@ org.apache.catalina.connector.Connector->getMaxCookieCount ``` +Show methods' details from `org.apache.catalina.connector.Connector`: + ```bash $ sm org.apache.catalina.connector.Connector -d declaring-class org.apache.catalina.connector.Connector diff --git a/en/_sources/stack.md.txt b/en/_sources/stack.md.txt index ce43a730d..fb9d7aabf 100644 --- a/en/_sources/stack.md.txt +++ b/en/_sources/stack.md.txt @@ -1,9 +1,9 @@ stack ===== -Print out the full call stack trace *till* the current method. +> Print out the full call stack of the current method. -Most of the time, we know the method being invoked but not always we know **HOW being invoked**; `stack` can be a great help to locate the *source* for you. +Most often we know one method gets called, but we have no idea on which code path gets executed or when the method gets called since there are so many code paths to the target method. The command `stack` comes to rescue in this difficult situation. ### Parameters @@ -12,29 +12,24 @@ Most of the time, we know the method being invoked but not always we know **HOW |*class-pattern*|pattern for the class name| |*method-pattern*|pattern for the method name| |*condition-expression*|condition expression| -|[E]|turn on regex matching while the default is wildcard matching| -|[n:]|calling times| +|`[E]`|turn on regex match, the default behavior is wildcard match| +|`[n:]`|execution times| -F.Y.I -1. any valid OGNL expression as `"{params,returnObj}"` supported; -2. filter by time cost as `trace *StringUtils isBlank '#cost>100'`; calling stack with only time cost higher than `100ms` will be printed. +There's one thing worthy noting here is observation expression. The observation expression supports OGNL grammar, for example, you can come up a expression like this `"{params,returnObj}"`. All OGNL expressions are supported as long as they are legal to the grammar. -Attention: -1. `#cost` can be used in `watch/stack/trace`; -2. using `#cost` in Arthas 3.0 instead of `$cost`. - - -Advanced: -* [Critical fields in expression](advice-class.md) -* [Special usage](https://github.com/alibaba/arthas/issues/71) -* [OGNL official guide](https://commons.apache.org/proper/commons-ognl/language-guide.html) +Thanks for `advice`'s data structure, it is possible to observe from varieties of different angles. Inside `advice` parameter, all necessary information for notification can be found. +Pls. refer to [core parameters in expression](advice-class.md) for more details. +* Pls. also refer to [https://github.com/alibaba/arthas/issues/71](https://github.com/alibaba/arthas/issues/71) for more advanced usage +* OGNL official site: [https://commons.apache.org/proper/commons-ognl/language-guide.html](https://commons.apache.org/proper/commons-ognl/language-guide.html) ### Usage -The quoting rules: if there are quotes within the expression, use another type of quotes to quote the whole expression (single `''` or double `""` quotes). +> Notes: if there's quotes character (say, `'`) in the expression, then the whole expression must be wrapped by quotes but with the other type (in this case, `"`) too. On contrary, it's no need to quote the expression itself if there's no quotes character found in it, but it is strongly recommended. -``` +Print out calling stack when the first method parameter is "K9-BD-01" for 'getProductById()' method: + +```bash $ stack com.alibaba.sample.petstore.dal.dao.ProductDao getProductById 'params[0]=="K9-BD-01"' Press Ctrl+C to abort. Affect(class-cnt:1 , method-cnt:1) cost in 51 ms. @@ -71,9 +66,9 @@ thread_name="http-bio-8080-exec-2" thread_id=0x48;is_daemon=true;priority=5; ... ``` -Filtering by time cost: +Print out the calling stack when method 'execute()' takes more than 30ms to finish: -``` +```bash $ stack com.alibaba.sample.petstore.web.store.module.screen.ItemList execute #cost>30 Press Ctrl+C to abort. Affect(class-cnt:1 , method-cnt:1) cost in 123 ms. diff --git a/en/_sources/start-arthas.md.txt b/en/_sources/start-arthas.md.txt index 3cfc333bd..7efe627f1 100644 --- a/en/_sources/start-arthas.md.txt +++ b/en/_sources/start-arthas.md.txt @@ -30,19 +30,15 @@ Startup script is as follows: ./as.sh [@IP:PORT] ``` - - ### Parameter Description -* PID: Target Java process ID(Make sure that the user executing the command has sufficient permissions to operate the target Java process.) - -* IP: The address that Arthas Server listens on, the default value is `127.0.0.1`. Arthas allows multiple users to access simultaneously without interfering with each other. - -* PORT: Arthas Server port，the default value is 3658 +* *PID*: Target Java process ID (Make sure that the user executing the command has sufficient permissions to operate the target Java process.) +* *IP*: The address that Arthas Server listens on, the default value is `127.0.0.1`. Arthas allows multiple users to access simultaneously without interfering with each other. +* *PORT*: Arthas Server port，the default value is 3658 ### Sample -* If you do not specify IP and PORT, the default is 127.0.0.1 and 3658 +* If IP and PORT are not specified, then the default values are 127.0.0.1 and 3658 > ./as.sh 12345 @@ -52,7 +48,7 @@ Startup script is as follows: ### Remote Diagnosis -After starting Arthas Server, users can use `telnet` connect to the remote Arthas Server, for example： +After starting Arthas Server on the target Java process, users can use `telnet` connect to the remote Arthas Server, for example： ```bash telnet 192.168.1.119 3658 @@ -60,7 +56,7 @@ telnet 192.168.1.119 3658 ### sudo Support -If you need to switch users, such as `admin`, you need to add the -H parameter. +Usually online environment will only grant users privilege as low as possible, instead, all advanced operations are through sudo-list. Since `as.sh` script takes into account the current effective user, it is possible to run the script in the other rule, by specifying `-H` option like this: ```bash sudo -u admin -H ./as.sh 12345 @@ -69,8 +65,8 @@ sudo -u admin -H ./as.sh 12345 ### Windows Support -`as.bat` script only supports one parameter: pid +Right now `as.bat` script supports one parameter only, which is: pid ```bash as.bat -``` \ No newline at end of file +``` diff --git a/en/_sources/sysprop.md.txt b/en/_sources/sysprop.md.txt index 6aa630733..9fc4ed49b 100644 --- a/en/_sources/sysprop.md.txt +++ b/en/_sources/sysprop.md.txt @@ -1,7 +1,7 @@ sysprop ======= -Check the JVM system properties. +> Examine the system properties from the target JVM ### Usage @@ -102,16 +102,16 @@ $ sysprop sun.cpu.isalist ``` -#### Check a single property +#### Check One Single Property -Tip: `tab` auto-completion supported +> Use `tab` for auto-completion -``` +```bash $ sysprop java.version java.version=1.8.0_51 ``` -#### Modify a single property +#### Modify Single Property ``` $ sysprop user.country diff --git a/en/_sources/thread.md.txt b/en/_sources/thread.md.txt index 51aff9563..213073c77 100644 --- a/en/_sources/thread.md.txt +++ b/en/_sources/thread.md.txt @@ -1,31 +1,25 @@ thread ====== -Check the basic profile and stack trace of the threads. +> Check the basic info and stack trace of the target thread. ### Parameters |Name|Specification| |---:|:---| |*id*|thread id in JVM| -|[n:]|the top n busiest with stack traces| -|[b]|locate the threads blocking others| +|`[n:]`|the top n busiest threads with stack traces printed| +|`[b]`|locate the thread blocking the others| |[i ``]|specify the interval to collect data to compute CPU ratios (ms)| -How to get the CPU ratios? - -> Within an *specified* interval, the time cost by the thread compared to the total CPU time. -> Take a sample (using `java.lang.management.ThreadMXBean#getThreadCpuTime`) to get the CPU time cost for all the threads and after a *specified* interval (default *100 ms*, which can be specified by `-i`), take another sample and we have the CPU time cost and the ratios naturally. - -> Attention: this kind of operation will take time, to decrease the extra cost, you'd better expand the interval to like `5000 ms` for less performance overhead. - -F.Y.I - -If you'd like to check the CPU ratios from the very start of the Java process, [show-busy-java-threads](https://github.com/oldratlee/useful-scripts/blob/master/docs/java.md#-show-busy-java-threads) can be a help. +> How the CPU ratios are calculated?

    +> CPU ratio for a given thread is the CPU time it takes divided by the total CPU time within a specified interval period. It is calculated in the following way: sample CPU times for all the thread by calling `java.lang.management.ThreadMXBean#getThreadCpuTime` first, then sleep for a period (the default value is 100ms, which can be specified by `-i`), then sample CPU times again. By this, we can get the time cost for this period for each thread, then come up with the ratio.

    +> Note: this operation consumes CPU time too (`getThreadCpuTime` is time-consuming), therefore it is possible to observe Arthas's thread appears in the list. To avoid this, try to increase sample interval, for example: 5000 ms.

    +> If you'd like to check the CPU ratios from the very beginning of the Java process, [show-busy-java-threads](https://github.com/oldratlee/useful-scripts/blob/master/docs/java.md#-show-busy-java-threads) can come to help. ### Usage -#### List the top n busiest with detailed stack trace +#### List the top n busiest threads with detailed stack trace ```shell $ thread -n 3 @@ -58,7 +52,7 @@ $ thread -n 3 at java.lang.ref.Reference$ReferenceHandler.run(Reference.java:133) ``` -#### List all info when no options provided +#### List all threads' info when no options provided ```shell $ thread @@ -82,7 +76,7 @@ ID NAME GROUP PRIORITY STA 21 Thread-8 main 5 RUNNABLE 0 0:0 false true ``` -#### thread present the specified thread profile +#### thread id, show the running stack for the target thread ```shell $ thread 1 @@ -96,9 +90,9 @@ $ thread 1 at java.util.concurrent.CountDownLatch.await(CountDownLatch.java:231) ``` -#### thread -b locate the blocking threads +#### thread -b, locate the thread bocking the others -Using `-b`, we can effectively locate the threads holding locks blocking other threads resulting in a frozen system. +In some occasions, we experience the whole application is stuck because there's one particular thread hold one lock that other threads are relying on. To diagnose such an issue, Arthas provides `thread -b` to find the problematic thread in one single command. ```bash $ thread -b @@ -139,10 +133,10 @@ $ thread -b - java.util.concurrent.ThreadPoolExecutor$Worker@31a6493e ``` -Attention: only `synchronized` blocked threads can be located for now, while `java.util.concurrent.Lock` not supported yet. +> Note: By now Arthas only supports to locate the thread blocked by `synchronzied`, while `java.util.concurrent.Lock` is not supported yet. -#### thread -i specify the collecting interval +#### thread -i, specify the sampling interval ```bash $ thread -n 3 -i 1000 diff --git a/en/_sources/trace.md.txt b/en/_sources/trace.md.txt index f49c43e7f..83ff594c0 100644 --- a/en/_sources/trace.md.txt +++ b/en/_sources/trace.md.txt @@ -1,7 +1,9 @@ trace ===== -Track methods calling stack trace and print the time cost in each call. +> Trace method calling path, and output the time cost for each node in the path. + +`trace` can track the calling path specified by `class-pattern` / `method-pattern`, and calculate the time cost on the whole path. ### Parameters @@ -10,27 +12,31 @@ Track methods calling stack trace and print the time cost in each call. |*class-pattern*|pattern for the class name| |*method-pattern*|pattern for the method name| |*condition-express*|condition expression| -|[E]|turn on regx matching while the default is wildcards matching| -|[n:]|calling times| +|`[E]`|enable regex match, the default behavior is wildcards match| +|`[n:]`|execution times| |#cost|time cost| -F.Y.I -1. any valid OGNL expression as `"{params,returnObj}"` supported; -2. filter by time cost as `trace *StringUtils isBlank '#cost>100'`; calling stack with only time cost higher than `100ms` will be printed. +There's one thing worthy noting here is observation expression. The observation expression supports OGNL grammar, for example, you can come up a expression like this `"{params,returnObj}"`. All OGNL expressions are supported as long as they are legal to the grammar. + +Thanks for `advice`'s data structure, it is possible to observe from varieties of different angles. Inside `advice` parameter, all necessary information for notification can be found. + +Pls. refer to [core parameters in expression](advice-class.md) for more details. +* Pls. also refer to [https://github.com/alibaba/arthas/issues/71](https://github.com/alibaba/arthas/issues/71) for more advanced usage +* OGNL official site: [https://commons.apache.org/proper/commons-ognl/language-guide.html](https://commons.apache.org/proper/commons-ognl/language-guide.html) + +Many times what we are interested is the exact trace result when the method call takes time over one particular period. It is possible to achieve this in Arthas, for example: `trace *StringUtils isBlank '$cost>100'` means trace result will only be output when the executing time exceeds 100ms. + +> Notes: +> 1. `watch`/`stack`/`trace`, these three commands all support `$cost`. +> 2. On version `3.0`, pls. use `#cost` instead of `$cost`. -Attention: -1. `#cost` can be used in `watch/stack/trace`; -2. using `#cost` in Arthas 3.0 instead of `$cost`. -3. `trace` can help to locate the performance lurking issue but only `level-one` method invoking considered. +### Notice -Advanced: -* [Critical fields in expression](advice-class.md) -* [Special usage](https://github.com/alibaba/arthas/issues/71) -* [OGNL official guide](https://commons.apache.org/proper/commons-ognl/language-guide.html) +`trace` is handy to help discovering and locating the performance flaws in your system, but pls. note Arthas can only trace the first level method call each time. ### Usage -A demo: +Sample code: ```java public static void main(String[] args) { @@ -67,7 +73,7 @@ A demo: } ``` -Tracing down method `add`: +Trace down method `add`: ```shell $ trace com.alibaba.sample.petstore.web.store.module.screen.ItemList add params.length==2 @@ -81,7 +87,7 @@ Affect(class-cnt:1 , method-cnt:1) cost in 144 ms. `---[0ms]java.util.List:size() ``` -Filtering by time cost: +Filter by time cost: ```shell $ trace com.alibaba.sample.petstore.web.store.module.screen.ItemList execute #cost>4 @@ -97,11 +103,10 @@ trace com.alibaba.sample.petstore.web.store.module.screen.ItemList execute #cost `---[min=0.005428ms,max=0.094064ms,total=0.105228ms,count=3] com.alibaba.citrus.turbine.Context:put() ``` -Only the calling trace of the time cost higher than `4ms` presented now. +> Only the call path which's time cost is higher than `4ms` will be shown. This feature is handy to focus on what's needed to focus when troubleshoot. -F.Y.I -1. like JProfile and other similar commercial software, you can `trace` down the specified method calling stack with time cost in Arthas; -2. there will be some overhead using `trace` but not much; -3. the time cost is an instructive clue for troubleshooting, which means it's not that accurate ignoring the cost it itself causes; the deeper or more the call is, the worse accuracy the time cost will be; -4. `[0,0,0ms,11]xxx:yyy() [throws Exception]`，the same method calling aggregated into one line here while `throws Exception` indicates there is an exception. +* Here Arthas provides the similar functionality JProfile and other commercial software provide. Compared to these professional softwares, Arthas doesn't deduce the time cost `trace` itself takes, therefore it is not as accurate as these softwares offer. More classes and methods on the calling path, more inaccurate `trace` output is, but it is still helpful for diagnostics where the bottleneck is. +* "[2.847106ms] com.alibaba.sample.petstore.biz.StoreManager:getAllProductItems()" means "getAllProductItem()" method from "com.alibaba.sample.petstore.biz.StoreManager" takes `2.847106` ms. +* "[min=0.005428ms,max=0.094064ms,total=0.105228ms,count=3] com.alibaba.citrus.turbine.Context:put()" means aggregating all same method calls into one single line. The minimum time cost is `0.005428` ms, the maximum time cost is `0.094064` ms, and the total time cost for all method calls (`3` times in total) to "com.alibaba.citrus.turbine.Context:put()" is `0.105228ms`. If "throws Exception" appears in this line, it means some exceptions have been thrown from this method calls. +* The total time cost may not equal to the sum of the time costs each sub method call takes, this is because Arthas instrumented code takes time too. diff --git a/en/advanced-use.html b/en/advanced-use.html index 9374455b3..f827e98d8 100644 --- a/en/advanced-use.html +++ b/en/advanced-use.html @@ -114,10 +114,10 @@
  • Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • diff --git a/en/advice-class.html b/en/advice-class.html index cad95da03..3ba8773c2 100644 --- a/en/advice-class.html +++ b/en/advice-class.html @@ -119,14 +119,14 @@
  • stack
  • tt
  • options
    • -
  • Basic Commands
    • +
  • Basic Arthas Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • diff --git a/en/async.html b/en/async.html index fae295bb9..63670a00d 100644 --- a/en/async.html +++ b/en/async.html @@ -120,10 +120,10 @@
  • Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • diff --git a/en/batch-support.html b/en/batch-support.html index 48bbdad33..afa121fad 100644 --- a/en/batch-support.html +++ b/en/batch-support.html @@ -114,10 +114,10 @@
  • Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -188,37 +188,37 @@

    Batch Processing

    -

    With the help of Batch Processing, you can run several commands in one line and get the results.

    +

    With the help of Batch Processing, you can run multiple commands in batch and get the final result at the end.

    Usage

    -

    Step-1: Create the script

    -

    Creating a test.as script suffixed with as here for consistency (actually any suffix is acceptable).

    -
    ➜  arthas git:(develop) cat /var/tmp/test.as
-help
-dashboard -b -n 1
+
    Step 1: Create the script
    
+
    Create a test.as script suffixed with as. Here as is suggested for the suffix of the filename, but in fact any suffix is acceptable.
    
+
    ➜  arthas git:(develop) cat /var/tmp/test.as
+help
+dashboard -b -n 1
 session
 thread
 sc -d org.apache.commons.lang.StringUtils
 
    
 
    
-
    Attention:
    
+
    Note:
    
 
      
-
    • each command takes each independent line;
      • 
-
    • dashboard command should include -b to turn on batch mode and -n to ensure the script ends;
      • 
-
    • commands as watch/tt/trace/monitor/stack should include -n option to ensure the script ends;
      • 
-
    • asynchronous can also be used as watch c.t.X test returnObj > &;
      • 
+
    • Each command takes one line.
      • 
+
    • Batch mode (via -b) and execution times (via -n) must be explicitly specified for dashboard, otherwise batch script cannot terminate.
      • 
+
    • Commands such as watch/tt/trace/monitor/stack should include -n option to ensure the script can be able to quit.
      • 
+
    • Also consider to use async (for example: watch c.t.X test returnObj > &) to put commands run at background and get the output from the log file, see more from asynchronous job
      •
    -

    Step-2: Run the script

    -

    Using -b to turn on script mode, and -f to run it and you can also redirect the output as:

    +

    Step 2: Run the script

    +

    Use -b to turn on batch mode, and use -f to specify the script file. By default the result will be output to the standard output, but you can redirect the output to the file like this:

    ./as.sh -b -f /var/tmp/test.as 56328 > test.out
    -

    Step-3: Check the outputs

    +

    Step 3: Check the outputs

    cat test.out
    diff --git a/en/classloader.html b/en/classloader.html index d85bb9e8b..7e94a0c41 100644 --- a/en/classloader.html +++ b/en/classloader.html @@ -114,14 +114,14 @@
  • stack
  • tt
  • options
    • -
  • Basic Commands
    • +
  • Basic Arthas Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -192,8 +192,8 @@

    classloader

    -

    Check the inheritance tree, urls and classes loading profiles of the class loaders.

    -

    It can be a great help for ResourceNotFoundException when you can use command classloader to specify a class loader to getResources and print all the urls of the valid resources.

    +

    View hierarchy, urls and classes-loading info for the class-loaders.

    +

    classloader can search and print out the URLs for a specified resource from one particular classloader. It is quite handy when analyze ResourceNotFoundException.

    Options

    @@ -206,11 +206,11 @@ - + - + @@ -218,7 +218,7 @@ - + @@ -229,7 +229,7 @@

    Usage

      -
    • Categorised by class loader
      • +
    • View statistics categorized by class type
    $ classloader
  name                                                   numberOfInstances  loadedCountTotal
@@ -248,7 +248,7 @@ Affect(row-cnt:11) cost in
      -
    • Categorized by class loader instance
      • +
    • View statistics categorized by loaded classes number
    $ classloader -l
  name                                                            loadedCount  hash      parent
@@ -298,7 +298,7 @@ Affect(row-cnt:11) cost in
      -
    • Check inheritance tree of the class loaders
      • +
    • View class-loaders hierarchy
    $ classloader -t
 +-BootstrapClassLoader
@@ -312,7 +312,7 @@ Affect(row-cnt:11) cost in
      -
    • Check URL of the class loader
      • +
    • Show the URLs from which to load classes and resources for one particular URLClassLoader
    $ classloader -c 5ffe9775
 file:/Users/hello/soft/taobao-tomcat-7.0.64/deploy/taobao-hsf.sar/lib/commons-lang-2.6.jar
@@ -325,7 +325,7 @@ file:/Users/hello/soft/taobao-tomcat-7.0.64/deploy/taobao-hsf.sar/lib/picocontai
      -
    • Using class loader to search for resource
      • +
    • Use one class loader to search one particular resource
    $ classloader -c 226b143b -r META-INF/MANIFEST.MF
  jar:file:/Users/hello/.m2/repository/javax/enterprise/cdi-api/1.0/cdi-api-1.0.jar!/META-INF/MANIFEST.MF
@@ -333,7 +333,7 @@ file:/Users/hello/soft/taobao-tomcat-7.0.64/deploy/taobao-hsf.sar/lib/picocontai
      -
    • Using class loader to look for *.class file
      • +
    • Use one class loader to search one particular class
    $ classloader -c 1b6d3586 -r java/lang/String.class
  jar:file:/Library/Java/JavaVirtualMachines/jdk1.8.0_60.jdk/Contents/Home/jre/lib/rt.jar!/java/lang/String.class
diff --git a/en/commands.html b/en/commands.html
index 801135c5d..bd5809464 100644
--- a/en/commands.html
+++ b/en/commands.html
@@ -110,14 +110,14 @@
 
  • stack
    • 
 
  • tt
    • 
 
  • options
    • 
-
  • Basic Commands
    • 
+
  • Basic Arthas Commands
    • 
 
 
 
  • User cases
    • 
-
  • Release Notes
    • 
 
  • Questions and answers
    • 
 
  • Fork me at GitHub
    • 
 
  • CONTRIBUTING
    • 
+
  • Release Notes
    • 
 
 
             
@@ -207,17 +207,17 @@
 
  • options
    •
    -
    -

    Basic Commands

    +
    +

    Basic Arthas Commands

      -
    • help - check the assistant info for the command
      • -
    • cls - clear out the current screen area
      • -
    • session - check the current session profile
      • -
    • reset - clear the injected code from the classes (B.T.W when Arthas server closed, all the injected will also be cleared)
      • -
    • version - the version of the working Arthas
      • +
    • help - examine help information
      • +
    • cls - clear out the screen
      • +
    • session - examine the current session
      • +
    • reset - reset enhanced classes. All enhanced classes will be reset to their original states. When Arthas server closes, all these enhanced classes will be reset too
      • +
    • version - print out Arthas’s version
    • quit - exit the current Arthas client without affecting other clients
      • -
    • shutdown - terminate the Arthas server and all clients
      • -
    • keymap - shortcuts for Arthas and also you can define your own
      • +
    • shutdown - terminate the Arthas server, all the Arthas clients connecting to this server will be disconnected
      • +
    • keymap - list all Arthas keyboard shortcuts and shortcut customizations.
    diff --git a/en/dashboard.html b/en/dashboard.html index 62147d041..791d5259b 100644 --- a/en/dashboard.html +++ b/en/dashboard.html @@ -94,9 +94,9 @@
  • Advanced usage
  • Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -193,10 +193,11 @@

    dashboard

    -

    This is the realtime dashboard for the system; press Ctrl+C to exit.

    -

    When running in Ali-tomcat, the dashboard will present the realtime statistics of the tomcat including QPS, RT, error counts, thread profile and the like.

    -
    -

    A Demo

    +
    +
    This is the real time statistics dashboard for the current system, press Ctrl+C to exit.
    +

    When running in Apache Tomcat Alibaba edition, the dashboard will also present the real time statistics of the tomcat, including QPS, RT, error counts, and thread pool, etc.

    +
    +

    Usage

    $ dashboard
 ID         NAME                              GROUP                  PRIORITY   STATE       %CPU       TIME       INTERRUPTED DAEMON
 889        RMI TCP Connection(15)-30.10.166. RMI Runtime            9          RUNNABLE    48         0:5        false       true
@@ -234,22 +235,22 @@ uptime                            16020s                            busy
    -
    -

    Specification

    +
    +

    Notes on column headers

      -
    • ID: thread ID in JVM (this is different from the nativeID in thread dump)
      • +
    • ID: JVM thread ID, pls. note this ID is different from the nativeID in jstack
    • NAME: thread name
      • -
    • GROUP: group the thread is in
      • -
    • STATE: the current state of the thread
      • -
    • PRIORITY: within 1 ~ 10 (the higher the number, the higher the priority)
      • -
    • CPU%: CPU usage ratio within 100ms
      • -
    • TIME: total running time in minute:second format
      • -
    • INTERRUPTED: the thread interrupted state
      • -
    • DAEMON: is daemon thread or not
      • +
    • GROUP: thread group name
      • +
    • PRIORITY: thread priority, ranged from 1 to 10. The greater number, the higher priority
      • +
    • STATE: thread state
      • +
    • CPU%: the ratio of CPU usage for the thread, sampled every 100ms
      • +
    • TIME: total running time in minute:second format
      • +
    • INTERRUPTED: the thread interruption state
      • +
    • DAEMON: daemon thread or not
    -
    -

    Screenshots

    +
    +

    Screenshot

    alt text

    diff --git a/en/dump.html b/en/dump.html index 48fe65cab..fca538779 100644 --- a/en/dump.html +++ b/en/dump.html @@ -114,14 +114,14 @@
  • stack
  • tt
  • options
    • -
  • Basic Commands
    • +
  • Basic Arthas Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -192,7 +192,8 @@

    dump

    -

    Dump the bytecode the loaded classes to a specified directory.

    +
    +
    Dump the bytecode for the particular classes to the specified directory.

    Options

    [l]list all class loader instances based on thread countlist all class loader instances
    [t]print the inheritance structure of the class loadersprint classloader's hierarchy
    [a]
    [c:]get the hashcode of the class loaderprint classloader's hashcode
    [c: r:]
    @@ -205,15 +206,15 @@ - + - - + + - - + +
    class-patternpattern for the class nameclass name pattern
    [c:]hashcode of the class loader that loaded the class[c:]hashcode of the class loader that loaded the target class
    [E]turn on regex matching while the default is wildcard matching[E]turn on regex match, the default behavior is wild card match
    diff --git a/en/genindex.html b/en/genindex.html index e3c2681b0..05bc851ba 100644 --- a/en/genindex.html +++ b/en/genindex.html @@ -93,10 +93,10 @@
  • Advanced usage
  • Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • diff --git a/en/getstatic.html b/en/getstatic.html index 4d49cf784..96ded3c68 100644 --- a/en/getstatic.html +++ b/en/getstatic.html @@ -110,14 +110,14 @@
  • stack
  • tt
  • options
    • -
  • Basic Commands
    • +
  • Basic Arthas Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -188,21 +188,21 @@

    getstatic

    -

    Check the static fields of classes conveniently as getstatic class_name field_name

    -

    Tip: if the field is a composite object, you can even use OGNL to traverse, filter and access the internal properties of it.

    -

    E.g. suppose n is a Map and the key is a Enum then if you want to get the key with a specific Enum value - STOP or a, you can achieve it as:

    -
    $ getstatic com.alibaba.arthas.Test n 'entrySet().iterator.{? #this.key.name()=="STOP"}'
+
    Check the static fields of classes conveniently, the usage is getstatic class_name field_name.
    
+
    Tip: if the static field is a complex class, you can even use OGNL to traverse, filter and access the inner properties of this class.
    
+
    E.g. suppose n is a Map and its key is a Enum, then you can achieve this if you want to pick the key with a specific Enum value:
    
+
    $ getstatic com.alibaba.arthas.Test n 'entrySet().iterator.{? #this.key.name()=="STOP"}'
 field: n
-@ArrayList[
-    @Node[STOP=bbb],
-]
-Affect(row-cnt:1) cost in 68 ms.
+@ArrayList[
+    @Node[STOP=bbb],
+]
+Affect(row-cnt:1) cost in 68 ms.
 
-$ getstatic com.alibaba.arthas.Test m 'entrySet().iterator.{? #this.key=="a"}'
+$ getstatic com.alibaba.arthas.Test m 'entrySet().iterator.{? #this.key=="a"}'
 field: m
-@ArrayList[
-    @Node[a=aaa],
-]
+@ArrayList[
+    @Node[a=aaa],
+]
    diff --git a/en/groovy.html b/en/groovy.html new file mode 100644 index 000000000..77908325b --- /dev/null +++ b/en/groovy.html @@ -0,0 +1,433 @@ + + + + + + + + + + + groovy — Arthas 3.0.5-SNAPSHOT documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + +
    + + + + + +
    + +
    + + + + + + + + + + + + + + + + + +
    + + + + +
    +
    +
    +
    + +
    +

    groovy

    +
    +
    Arthas support groovy scripting to allow user to use script like BTrace. It is possible to use if/for/switch/while in groovy scripting, but has more limitations compared to BTrace.
    +
    +

    Limitations

    +
      +
    1. Prohibit from alternating the original logic. Like watch command, The major purpose of scripting is monitoring and observing.
      2. +
    2. Only allow to monitor at the stages of before/success/exception/finish on one method.
      3. +
    +
    +
    +

    Parameters

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ParameterExplanation
    class-patternclass name pattern
    method-patternmethod name pattern
    script-filepaththe absolute path of the groovy script
    [S]match all sub classes
    [E]enable regex match, the default is wildcard match

    Note: the third parameter script-filepath must be the absolute path of the groovy script, for example /tmp/test.groovy. It is not recommended to use relative path, e.g. ./test.groovy.

    +
    +
    +

    Explanation on the important callbacks

    +
    /**
+ * Listeners for script to enhance the class
+ */
+interface ScriptListener {
+
+    /**
+     * When the script is created
+     *
+     * @param output Output
+     */
+    void create(Output output);
+
+    /**
+     * When the script is destroyed
+     *
+     * @param output Output
+     */
+    void destroy(Output output);
+
+    /**
+     * Before the method executes
+     *
+     * @param output Output
+     * @param advice Advice
+     */
+    void before(Output output, Advice advice);
+
+    /**
+     * After the method returns
+     *
+     * @param output Output
+     * @param advice Advice
+     */
+    void afterReturning(Output output, Advice advice);
+
+    /**
+     * After the method throws exceptions
+     *
+     * @param output Output
+     * @param advice Advice
+     */
+    void afterThrowing(Output output, Advice advice);
+
+}
+
    +
    +
    +
    +

    Advice parameter

    +

    Advice contains all information necessary for notification. Refer to expression core parameters for more details.

    +
    +
    +

    Output parameter

    +

    There are three methods in Output, used for outputting the corresponding text.

    +
    /**
+ * Output
+ */
+interface Output {
+
+    /**
+     * Output text without line break
+     *
+     * @param string Text to output
+     * @return this
+     */
+    Output print(String string);
+
+    /**
+     * Output text with line break
+     *
+     * @param string Text to output
+     * @return this
+     */
+    Output println(String string);
+
+    /**
+     * Finish outputting from the script
+     *
+     * @return this
+     */
+    Output finish();
+
+}
+
    +
    +
    +
    +

    A groovy sample script to output logs

    +
    import com.taobao.arthas.core.command.ScriptSupportCommand
+import com.taobao.arthas.core.util.Advice
+
+import static java.lang.String.format
+
+/**
+ * Output method logs
+ */
+public class Logger implements ScriptSupportCommand.ScriptListener {
+
+    @Override
+    void create(ScriptSupportCommand.Output output) {
+        output.println("script create.");
+    }
+
+    @Override
+    void destroy(ScriptSupportCommand.Output output) {
+        output.println("script destroy.");
+    }
+
+    @Override
+    void before(ScriptSupportCommand.Output output, Advice advice) {
+        output.println(format("before:class=%s;method=%s;paramslen=%d;%s;",
+                advice.getClazz().getSimpleName(),
+                advice.getMethod().getName(),
+                advice.getParams().length, advice.getParams()))
+    }
+
+    @Override
+    void afterReturning(ScriptSupportCommand.Output output, Advice advice) {
+        output.println(format("returning:class=%s;method=%s;",
+                advice.getClazz().getSimpleName(),
+                advice.getMethod().getName()))
+    }
+
+    @Override
+    void afterThrowing(ScriptSupportCommand.Output output, Advice advice) {
+        output.println(format("throwing:class=%s;method=%s;",
+                advice.getClazz().getSimpleName(),
+                advice.getMethod().getName()))
+    }
+}
+
    +
    +

    Run the script like this:

    +
    $ groovy com.alibaba.sample.petstore.dal.dao.ProductDao getProductById /Users/zhuyong/middleware/arthas/scripts/Logger.groovy -S
+script create.
+Press Ctrl+C to abort.
+Affect(class-cnt:1 , method-cnt:1) cost in 102 ms.
+before:class=IbatisProductDao;method=getProductById;paramslen=1;[Ljava.lang.Object;@45df64fc;
+returning:class=IbatisProductDao;method=getProductById;
+before:class=IbatisProductDao;method=getProductById;paramslen=1;[Ljava.lang.Object;@5b0e2d00;
+returning:class=IbatisProductDao;method=getProductById;
+
    +
    +
    +
    + + +
    + +
    +
    + + +
    + +
    +

    + © Copyright 2018, Alibaba Middleware Group, and contributors. + +

    +
    + Built with Sphinx using a theme provided by Read the Docs. + +
    + +
    +
    + +
    + +
    + + + + + + + + + + + + + + + + +
    +
    + Fork me at GitHub +
    +
    + + + + + + + + + \ No newline at end of file diff --git a/en/index.html b/en/index.html index 8b883b07c..38eb15a1a 100644 --- a/en/index.html +++ b/en/index.html @@ -31,7 +31,7 @@ - + @@ -93,10 +93,10 @@
  • Advanced usage
  • Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -165,35 +165,34 @@

    Arthas Documentation

    -

    中文文档/Chinese Docs

    +

    中文文档

    arthas

    -

    Arthas is a Java Diagnostic tool open sourced by Alibaba.

    -

    Arthas help developers in trouble-shooting production issues for Java applications without modifying code or restarting servers.

    +

    Arthas is a Java diagnostic tool open-sourced by Alibaba middleware team. It is widely adopted and popular among the developers inside Alibaba. Arthas helps developers in trouble-shooting issues in production environment for Java based applications without modifying code or restarting servers.

    Background

    -

    Often times, the production system network is inaccessible from local development environment. If issues are encountered in production systems, it is impossible to use IDE to debug the application remotely. More importantly, debugging in production environment is unacceptable, as it will suspend all the threads, which leads to blocking of business services.

    -

    Developers could always try to reproduce the same issue on the test/staging environment. However, this is tricky as some issues cannot be be reproduced easily on a different environment, or even disappear once restarted.

    -

    And if you’re thinking of adding some logs to your code to help trouble-shoot the issue, you will have to go through the following lifecycle; test, staging, and then to production. Time is money! This approach is inefficient! Besides, the issue may not be reproducible once the JVM is restarted, as described above.

    -

    Arthas was built to solve these issues. A developer can trouble-shoot your production issues on-the-fly. No JVM restart, no additional code changes. Arthas works as an observer, which will never suspend your existing threads.

    +

    Oftentimes the production system network is inaccessible from local development environment. If issues are encountered in production systems, it is impossible to use IDE to debug the application remotely. What’s even worse, debugging in production environment is unacceptable, as it will suspend all the threads, leading to services downtime.

    +

    Developers could always try to reproduce the same issue on the test/staging environment. However, this is tricky as some issues cannot be reproduced easily in a different environment, or even disappear once restarted.

    +

    And if you’re thinking of adding some logs to your code to help trouble-shoot the issue, you will have to go through the following lifecycle: test, staging, and then to production. Time is money! This approach is inefficient! Worse still, the issue may not be fixed since it might be irreproducible once the JVM is restarted, as described above.

    +

    Arthas is built to solve these issues. A developer can troubleshoot production issues on the fly. No JVM restart, no additional code changes. Arthas works as an observer, that is, it will never suspend your running threads.

    Key features

    • Check whether a class is loaded? Or where the class is loaded from? (Useful for trouble-shooting jar file conflicts)
    • Decompile a class to ensure the code is running as expected.
      • -
    • View classloader statistics, e.g. the number of classloaders, the number of classes loaded per classloader, the classloader hierarchy, possible classloader leaks, etc.
      • -
    • View the method invocation details, e.g. method parameter, return object, thrown exception, and etc.
      • -
    • Check the stack trace of specified method invocation. This is useful when a developers wants to know the caller of the said method.
      • +
    • Check classloader statistics, e.g. the number of classloaders, the number of classes loaded per classloader, the classloader hierarchy, possible classloader leaks, etc.
      • +
    • Check the method invocation details, e.g. method parameter, returned values, exceptions and etc.
      • +
    • Check the stack trace of specified method invocation. This is useful when a developer wants to know the caller of the method.
    • Trace the method invocation to find slow sub-invocations.
      • -
    • Monitor method invocation statistics, e.g. qps, rt, success rate and etc.
      • -
    • Monitor system metrics, thread states and cpu usage, gc statistics, and etc.
      • +
    • Monitor method invocation statistics, e.g. QPS (Query Per Second), RT (Return Time), success rate and etc.
      • +
    • Monitor system metrics, thread states and CPU usage, GC statistics and etc.
    • Supports command line interactive mode, with auto-complete feature enabled.
      • -
    • Supports telnet and websocket, which enables both local and remote diagnostics with command line and browsers.
      • +
    • Supports telnet and WebSocket, which enables both local and remote diagnostics with command line and browsers.

    Contents

    -

    English version has just been finished. If you would like to make it better, please check here and submit your PM.

    +

    English version has just been finished. If you would like to make it better, please check here and submit your pull request.

    @@ -218,7 +217,7 @@ diff --git a/en/install-detail.html b/en/install-detail.html index c953ea907..93d9434cb 100644 --- a/en/install-detail.html +++ b/en/install-detail.html @@ -8,7 +8,7 @@ - Arthas Install — Arthas 3.0.5-SNAPSHOT documentation + Install Arthas — Arthas 3.0.5-SNAPSHOT documentation @@ -93,23 +93,18 @@
  • Linux/Unix/Mac
  • Windows
  • Manual Installation
    • -
  • Advanced Manual Boot
  • Offline Help Documentation
    • -
  • Uninstall -
    • +
  • Uninstall
  • Quick start
  • Advanced usage
  • Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -155,7 +150,7 @@
  • Docs »
    • -
  • Arthas Install
    • +
  • Install Arthas
  • @@ -176,44 +171,40 @@
    -
    -

    Arthas Install

    +
    +

    Install Arthas

    Linux/Unix/Mac

    -

    You can install Arthas in one single line as:

    +

    You can install Arthas with one single line command on Linux, Unix, and Mac. Pls. copy the following command and paste it into the command line, then press Enter to run:

    curl -L https://alibaba.github.io/arthas/install.sh | sh
    -

    The command line above will download the booting script as.sh to the current directory and you can then start Arthas by ./as.sh, for more help info you can use ./as.sh -h to check the details.

    -

    By the way, you can also add the absolute path of the script as.sh to $PATH to make it available globally.

    +

    The command above will download the bootstrap script as.sh to the current directory. You can move it the any other place you want, or put its location in $PATH.

    +

    You can enter its interactive interface by executing as.sh, or execute as.sh -h for more help information.

    Windows

    Latest Version: Arthas

    -

    Download the latest bin.zip, unzip the package and you can find the as.bat. For now this script will only take one argument pid which means you can only diagnose the local Java process. (Welcome any bat script expert to make it better :heart:)

    +

    Download the latest bin.zip, unzip the package, and find as.bat from ‘bin’ directory. For now this script will only take one argument pid, which means you can only diagnose the local Java process. (Welcome any bat script expert to make it better :heart:)

    as.bat <pid>
    -

    A small tip:

    -

    If you are asking for better UX, you can start the Arthas Server locally by as.bat <pid> and then use ./as.sh <pid>@<ip>:<por>in another Linux/Unix/Mac machine.

    -

    Another tip:

    -

    If in Windows, the color is not working as expect. You can try conemu to get it to work.

    +

    To have a better experience, you can start the Arthas Server locally by executing as.bat <pid>, then run ./as.sh <pid>@<ip>:<por> in another Linux/Unix/Mac machine.

    +
    +
    If the color is not working as expect on windows, you can use conemu to get it to work.

    Manual Installation

    Manual Installation

    -
    -
    -

    Advanced Manual Boot

    -

    If you cannot boot Arthas, try to pass in all the critical options manually as the following steps:

    +

    If you fail to boot Arthas with the provided batch file, you could try to assemble the bootstrap command in the following way.

      -

    1. locate the java for JVM:

      +

    2. Locate java in the target JVM:

      • Linux/Unix/Mac: ps aux | grep java
      • Windows: open the Process Monitor to search java
      3. -

    3. Concatenate the command

      +

    4. Assemble bootstrap command:

      Let’s suppose we are using /opt/jdk1.8/bin/java, then the command should be:

      /opt/jdk1.8/bin/java -Xbootclasspath/a:/opt/jdk1.8/lib/tools.jar \
     -jar /tmp/arthas-packaging/arthas-core.jar \
@@ -223,19 +214,19 @@
     -agent /tmp/arthas-packaging/arthas/arthas-agent.jar
      +

      Note:

        -
      • -Xbootclasspath add tools.jar
        • -
      • -jar /tmp/arthas-packaging/arthas-core.jar specify main entry
        • -
      • -pid 15146 specify the target java process pid
        • -
      • -target-ip 127.0.0.1 specify the IP
        • -
      • -telnet-port 3658 -http-port 8563 specify telnet and http ports
        • -
      • -core /tmp/arthas-packaging/arthas-core.jar -agent /tmp/arthas-packaging/arthas/arthas-agent.jar specify core/agent jar package
        • +
      • -Xbootclasspath adds tools.jar
        • +
      • -jar /tmp/arthas-packaging/arthas-core.jar specifies main entry
        • +
      • -pid 15146 specifies the target java process PID
        • +
      • -target-ip 127.0.0.1 specifies the IP
        • +
      • -telnet-port 3658 -http-port 8563 specifies telnet and HTTP ports for remote access
        • +
      • -core /tmp/arthas-packaging/arthas-core.jar -agent /tmp/arthas-packaging/arthas/arthas-agent.jar specifies core/agent jar package
      -

      But if you are using JDK 1.9 or above，then you do not need to add tools.jar in option -Xbootclasspath.

      -

      F.Y.I the booting log will be printed to ~/logs/arthas/arthas.log.

      +

      If you are running on JDK 1.9 or above，then it’s unncessary to add tools.jar in option -Xbootclasspath.

      +

      You can find the logs from ~/logs/arthas/arthas.log.

      5. -

    5. Connect via telnet

      -

      When attached successfully, you can connect it with

      +

    6. Use telnet to connect once attaching to the target JVM (in step 2) succeeds

      telnet localhost 3658
      @@ -249,16 +240,15 @@

    Uninstall

    -
    -

    Linux/Unix/Mac

    +
      +

    • On Linux/Unix/Mac, delete the files with the following command:

      rm -rf ~/.arthas/ ~/.arthas_history
      -
    -
    -

    Windows

    -

    Directly delete the zip and unzipped files.

    -
    +
    • +

  • On Windows, simply delete the zip file and unzipped files.

    +
    • +
    diff --git a/en/jad.html b/en/jad.html index 449796917..8818bf4ef 100644 --- a/en/jad.html +++ b/en/jad.html @@ -114,14 +114,14 @@
  • stack
  • tt
  • options
    • -
  • Basic Commands
    • +
  • Basic Arthas Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -192,12 +192,12 @@

    jad

    -

    De-compile specified loaded classes.

    -

    jad helps to de-compile the byte code in JVM to the source code to assist you to better understand the logic behind.

    -

    F.Y.I

    +
    +
    De-compile the specified classes.
    +

    jad helps to de-compile the byte code running in JVM to the source code to assist you to understand the logic behind better.

      -
    • the de-compiled code will be grammatically highlighted for readability in Arthas console;
      • -
    • there might be some trivial grammar errors but it won’t affect the logic understanding.
      • +
    • The de-compiled code is syntax highlighted for better readability in Arthas console.
      • +
    • It is possible that there’s grammar error in the de-compiled code, but it should not affect your interpretation.

    Options

    @@ -214,22 +214,19 @@ pattern for the class name -[c:] -hashcode of the class loader that loaded the class +[c:] +hashcode of the class loader that loads the class -[E] -turn on regex matching while the default is wildcard matching +[E] +turn on regex match while the default is wildcard match

    Usage

    -

    When several class loaders loaded the same class:

    -
      -
    1. jad to get the hashcode of the class loader;
      2. -
    2. jad -c <hashcode> to get the de-compiled class loaded by the specified class loader.
      3. -
    +
    +
    If the target class is loaded by multiple classloaders, jad outputs the hashcode of the corresponding classloaders, then you can re-run jad and specify -c <hashcode> to de-compile the target class from the specified classloader.
    $ jad org.apache.log4j.Logger
 
  Found more than one class for: org.apache.log4j.Logger, Please use jad -c hashcode org.apache.log4j.Logger
@@ -361,8 +358,6 @@ private Map<String, Object> directMetrics(String ip
 Affect(row-cnt:1) cost in 1508 ms.
    -

    F.Y.I

    -

    Inner class is not yet supported, you can just check the outer class to further check the inner class.

    diff --git a/en/jvm.html b/en/jvm.html index 33613ec38..cf9d3dbe8 100644 --- a/en/jvm.html +++ b/en/jvm.html @@ -97,8 +97,8 @@
  • thread
  • jvm
  • sysprop
    • @@ -115,14 +115,14 @@
  • stack
  • tt
  • options
    • -
  • Basic Commands
    • +
  • Basic Arthas Commands
  • User cases
    • -
  • Release Notes
  • Questions and answers
  • Fork me at GitHub
  • CONTRIBUTING
    • +
  • Release Notes
    • @@ -193,7 +193,8 @@

    jvm

    -

    Check the JVM profile

    +
    +
    Check the current JVM’s info

    Usage

    $ jvm
@@ -286,17 +287,17 @@ Affect cost in 2 ms.
    -