HouseMD, 比BTrace更实用的Java运行诊断工具

HouseMD 是一款非常敏捷的 Java进程运行时的诊断调式命令行工具, 它具备安全易用高效的特点, 让它非常适合在要求严格的线上(生产)环境中使用.

特性

• 交互式命令行
  • 支持 Tab自动补全或候选列表提示
  • 支持命令历史
• 查看加载类
  • 支持跟踪文件来源路径
  • 支持跟踪类加载器层次
• 跟踪方法
  • 支持类短名字( SimpleName)和方法名(可选)限定跟踪目标
  • 支持根据抽象类或接口来限定其实现类的跟踪目标
  • 支持实时显示跟踪目标的摘要统计
  • 支持输出跟踪目标调用日志文件输出
  • 支持输出跟踪目标调用栈文件输出
• 查看环境变量和属性( Comming soon)

为什么要有 HouseMD

点击这里查看

与 BTrace 相比

• 仅一个 jar包, 部署简单, 使用简单
• 无需编写脚本, 借助指令完成常见诊断操作, 且切换快速高效
• 借助命令行提示, 能够快速准确定位要跟踪的目标
• 支持查看加载类的信息, 这在容器的应用诊断场景非常有用
• 通过跟踪限时和限次数的机制, 来控制给跟踪过程带来的消耗
• 自动检测并解决容器应用中类加载的问题
• 自身源码精简短小, 易于阅读掌握, 易于定制扩展

安装

快速安装

在 Linux或 Unix的系统下, 在要安装 HouseMD的路径下(建议将该路径加入系统PATH变量), 运行:

> curl -Lk https://raw.github.com/zhongl/HouseMD/master/bin/install | bash

HouseMD目前对 Windows还不支持( 相关Issue), 期待有需要的同志来贡献代码!

下载安装

• 点击这里 下载最新的版本
• 运行命令:

> java -Xbootclasspath/a:$JAVA_HOME/lib/tools.jar -jar housemd-assembly-x.x.x.jar

注意: 在 Mac OSX下, 选项 -Xbootclasspath是不需要的.

入门

启动

假定你在  快速安装并将安装路径加入PATH 之后, 在命令行输入:

      > housemd -h

你会看到 HouseMD的帮助信息, 如下：

      Usage: housemd [OPTIONS] pid
    a runtime diagnosis tool of JVM.
Options:
    -h, --help
        show help infomation of this command.
    -p, --port=[INT]
        set console local socket server port number.
        default: 54321
Parameters:
    pid
        id of process to be diagnosing.

真正要用起来, 则需要拿到你要诊断的 java进程的 ID（通过 jps或 ps）, 假设 pid是 1234, 然后执行:

      > housemd 1234

帮助

在显示若干行 INFO信息后, 此时进入 HouseMD的 Shell提示符, 键入 help指令, 可以查看其支持的内置指令:

      housemd> help

quit      terminate the process.
help      display this infomation.
trace     display or output infomation of method invocaton.
loaded    display loaded classes information.

在 help后加上指令的名字, 如 loaded, 便会显示具体指令的帮助信息:

      housemd> help loaded
Usage: loaded [OPTIONS] name
    display loaded classes information.
Options:
    -h, --classloader-hierarchies
        display classloader hierarchies of loaded class.
Parameters:
    name
        class name without package name.

退出

退出支持三种方式:

1. 键入 quit指令
2. 键入 Ctrl + D
3. 键入 Ctrl + C

常见问题解答

点击这里查看

指令范例

loaded

      housemd> loaded String
java.lang.String -> /usr/lib/jvm/java-6-sun-1.6.0.26/jre/lib/rt.jar

查看类 java.lang.String的加载路径

      housemd> loaded -h ScalaObject
scala.ScalaObject -> /home/housemd/housemd.jar
    - com.github.zhongl.housemd.Duck$1@1e859c0
        - sun.misc.Launcher$AppClassLoader@1cde100
            - sun.misc.Launcher$ExtClassLoader@16f0472

查看类 scala.ScalaObject的加载路径和类加载器层次.

注意: BootClassLoader由于不是 Java语言实现, 所以不会显示.

trace

      housemd> trace -t 2 TraceTarget$A.m
INFO : probe class TraceTarget$A
TraceTarget$A.m(int, String)    TraceTarget$CL@42719c            0            -ms    null
TraceTarget$A.m(String)         TraceTarget$CL@42719c            2            3ms    TraceTarget$A@401369

TraceTarget$A.m(int, String)    TraceTarget$CL@42719c            0            -ms    null
TraceTarget$A.m(String)         TraceTarget$CL@42719c            4            1ms    TraceTarget$A@401369

INFO : Ended by timeout
INFO : reset class TraceTarget$A

跟踪接下来2秒内 TraceTarget$A.m方法的调用

每列的含义依次是: 方法全名(含参数列表), 当前类的加载器对象, 总计调用次数, 平均调用耗时, 调用的自身对象

      housemd> trace -l 4 TraceTarget$D+.mD1
INFO : probe class TraceTarget$D
TraceTarget$D.mD1(int)    TraceTarget$CL@42719c            2           <1ms    TraceTarget$B@80cac9

INFO : Ended by overlimit
INFO : reset class TraceTarget$D

跟踪接下来4次抽象类 TraceTarget$D的 mD1方法的调用

这里可以看到, 这个方法调用的触发对象是其实现类 TraceTarget$B的实例

      housemd> trace -i 4 TraceTarget$D+
INFO : probe class TraceTarget$D
INFO : probe class TraceTarget$B
TraceTarget$B.mC(String)       TraceTarget$CL@42719c            8           <1ms    TraceTarget$B@80cac9
TraceTarget$B.mD2(int, int)    TraceTarget$CL@42719c            8           <1ms    TraceTarget$B@80cac9
TraceTarget$D.mD1(int)         TraceTarget$CL@42719c            8           <1ms    TraceTarget$B@80cac9

TraceTarget$B.mC(String)       TraceTarget$CL@42719c           16           <1ms    TraceTarget$B@80cac9
TraceTarget$B.mD2(int, int)    TraceTarget$CL@42719c           16           <1ms    TraceTarget$B@80cac9
TraceTarget$D.mD1(int)         TraceTarget$CL@42719c           16           <1ms    TraceTarget$B@80cac9

INFO : Ended by timeout
INFO : reset class TraceTarget$D
INFO : reset class TraceTarget$B

跟踪抽象类 TraceTarget$D所有方法的调用, 设定每隔4秒进行一次实时摘要显示, 直至默认结束条件达成

      housemd> trace -d TraceTarget.addOne TraceTarget$A
......

跟踪 TraceTarget.addOne方法和  TraceTarget$A的所有方法的调用, 并输出详细日志到文件

文件的路径, 请通过 help trace 查看 -d选项的说明获知

输出的 detail文件内容:

      2012-06-14 14:38:29 8ms [main] null TraceTarget.addOne [0] 1
2012-06-14 14:38:29 2ms [main] TraceTarget$A@995a79 TraceTarget$A.m [123] void
2012-06-14 14:38:30 0ms [main] null TraceTarget.addOne [0] 1
2012-06-14 14:38:30 0ms [main] TraceTarget$A@995a79 TraceTarget$A.m [123] void

日志每行以一个空格分隔, 每列的含义依次是: 日期, 时间戳, 调用耗时, 调用线程名, 调用方法的自身对象, 调用方法全名, 调用方法参数值列表, 返回值(或异常)

      housemd> trace -s TraceTarget.addOne
......

跟踪 TraceTarget.addOne方法, 并输出其调用栈到文件

文件的路径, 请通过 help trace 查看 -s选项的说明获知

输出的stack文件内容:

      TraceTarget.addOne(Integer) call by thread [main]
    TraceTarget.main(TraceTarget.java:42)

更多信息请见 常见问题解答, 或指令帮助

历史版本和未来规划

点击这里查看

疑问, 建议, 缺陷

欢迎任何疑问, 建议还有缺陷, 请至 这里提交给我.

后记

HouseMD是基于字节码技术的诊断工具, 因此除了 Java意外, 任何最终以字节码形式运行于 JVM之上的语言,  HouseMD都支持对它们进行诊断, 如 Clojure(感谢 @Killme2008提供了它的 使用入门)),  scala,  Groovy,  JRuby,  Jython,  kotlin等.