XPocket 用戶文檔

XPocket 是PerfMa爲終結性能問題而生的開源的插件容器，它是性能領域的樂高，將定位或者解決各種性能問題的常見的Linux命令，JDK工具，知名性能工具等適配成各種XPocket插件，並讓它們可以相互聯動一鍵解決特定的性能問題。目前XPocket插件生態已經實現了HSDB、JDB、JConsole、Perf、Arthas等多個優秀的開源性能工具的插件化集成，現階段主要側重性能領域。

當你遇到以下類似問題時，XPocket可以幫助到你：

系統存在性能問題？
問題排查時一頭霧水，無從下手？
使用一個新的工具，下載、文檔、安裝完就下班了？
好不容易用起來，只因輸出不合理就又要去找新工具？
有些自己實現的小工具散落各處？
排查過的問題記不記住全憑腦子？

XPocket支持JDK 8+，支持Linux/Mac/Windows，採用命令行交互模式，提供豐富的 Tab 自動補全功能，支持管道操作。

插件開源生態

XPocket在線教程

基礎教程

XPocket官方網站

xpocket.perfma.com

XPocket插件中心

plugin.xpocket.perfma.com

快速開始

1.下載模擬程序，解壓並運行

wget https://a.perfma.net/xpocket/download/XPocket-demo.tar.gz
tar -xvf  XPocket-demo.tar.gz
cd simulator
sh run.sh

2.下載xpocket，然後解壓並運行

wget https://a.perfma.net/xpocket/download/XPocket.tar.gz
tar -xvf  XPocket.tar.gz
sh xpocket/xpocket.sh

啓動成功後如下所示

3.使用插件

1.查看插件列表

plugins

列表如下圖所示

2.使用命令 use + pluginName 或者 use + pluginName@NameSpace 來使用插件，例

use jdb@JDK

4.切換插件

查看插件列表
使用 use + pluginName 或者 use + pluginName@NameSpace 來使用插件

5.獲取幫助

利用help命令來獲取更多幫助信息

獲取插件相關的幫助信息 : help + pluginName@NameSpace ，例如。

help jdb@JDK

獲取命令相關的幫助信息 : help + pluginName.commandName （如果已經切換到插件的操作空間下，可以直接使用 help + commandName 的方式）,例如。

help jdb.cont

切換到某個插件的操作空間下後，可以通過help命令查看當前插件的命令列表。

6.管道操作

場景：當前插件位於JConsole下，需要attach上我們的demo程序。

常規操作（jps -> 獲取demo程序的pid -> 使用attach命令attach目標進程）。
XPocket的管道操作只需一條命令即可（jps | grep demo | split -i 0 | attach），如下所示。

7.退出插件

XPocket退出插件的方式很簡單，只需要使用命令 cd 即可，cd命令可以退出當前插件，使得當前的操作空間回到系統層，如下圖所示。

8.退出XPocket

退出XPocket使用命令 quit 即可，如下圖所示

運行模式

1. telnet server模式

sh xpocket.sh -run_mode telnet -port 9527

該模式會啓動一個靜默模式的XPocket，以對應端口的Telnet Server接受外部鏈接並使用，適用於遠程執行操作的場景。

2. run once 模式

sh xpocket.sh -run_mode once "echo test"

該模式是啓動XPocket運行完指定命令以後直接退出，適用於外部調用完成單次操作的場景。

3. Java Agent模式

sh xpocket.sh -run_mode agent-launcher -pid 1 -port 9527

該模式與telnet模式類似，但是是將XPocket整體作爲一個Java Agent掛載到目標進程上運行，適用於容器類場景，並且可以獲取更多JVM運行時信息。

插件開發

詳情請見開發者指南

現有插件

HSDB

簡介

探索JVM的運行時數據，強大的JVM運行時狀態分析工具（注：由於jdk8以上開始實施模塊化，導致HSDB與其的運行機制不兼容）。

操作指南

Command-Name                   Command-Description
  hsdb                         hsdb [path of sa-jdi.jar] start hsdb command line
  
Tips:
  only support Windows platform

更多操作以及介紹請參考官方介紹

插件倉庫

插件概況

JDB

簡介

Java調試器（JDB）是Java類在命令行中調試程序的工具，它實現了Java平臺調試器體系結構，它有助於使用Java調試接口（JDI）檢測和修復Java程序中的錯誤。

操作指南

 Command-Name                   Command-Description
   jdb                          jdb <options> <class> <arguments>

 Tips:
 1.使用jdb -help獲取詳細幫助信息。
 2.使用jdb -listconnectors 獲取當前支持的所有連接器。
 3.可以使用例如 jdb -connect com.sun.jdi.SocketAttach:hostname=127.0.0.1,port=8000 鏈接已經開啓debug模式的java進程。
 4.使用jdb -classspath .:$CLASS_PATH 來啓動jdb會話（windows上需要使用;分隔多個路徑），然後通過stop in/at 設置斷點並使用run啓動一個可以被debug的java進程。
 5.啓動jdb會話以後也可以通過help命令獲取詳細幫助。

更多操作以及介紹請參考官方介紹

插件倉庫

插件概況

Perf

簡介

Perf功能強大，它可以檢測CPU性能計數器，跟蹤點，kprobes和uprobes（動態跟蹤），它能夠進行輕量級分析。它也包含在Linux內核的tools / perf下，並且經常更新和增強，
Perf最初是在Linux中使用性能計數器子系統的工具，並且進行了各種增強以添加跟蹤功能，更詳細的內容請參考Perf介紹。

操作指南

  Command-Name                   Command-Description
  config                         Get and set variables in a configuration file.
  context-switches               process context-switches detail
  page-faults                    process page-faults detail
  lock                           Analyze lock events
  ftrace                         simple wrapper for kernel's ftrace functionality
  report                         Read perf.data (created by perf record) and display the profile
  analyze                        analyze process cpu usage
  record                         Run a command and record its profile into perf.data
  sched                          Tool to trace/measure scheduler properties (latencies)
  probe                          Define new dynamic tracepoints
  script                         Read perf.data (created by perf record) and display trace output
  version                        display the version of perf binary
  list                           List all symbolic event types
  annotate                       Read perf.data (created by perf record) and display annotated code
  create-java-perf-map           generate /tmp/perf-<pid>.map files for just-in-time(JIT)-compiled methods for use with perf
  stat                           Run a command and gather performance counter statistics
  proc-stat                      process performance stats

Perf插件集成了PerfMa自己增加的幾條命令如：analyze命令：
analyze -p [pid] （-p 指定進程採集熱點）
analyze -detail 查看進程CPU熱點抓取結果
同時支持perf原生的命令和參數，並且針對java程序集成了perf-map-agent 這個工具，可以協助顯示java的調用棧信息.具體使用方式見命令的幫助信息(如 help analyze)

插件倉庫

插件概況

Arthas

簡介

Arthas 是Alibaba開源的Java診斷工具，深受開發者喜愛，支持JDK 6+，支持Linux/Mac/Windows，採用命令行交互模式，同時提供豐富的 Tab 自動補全功能，進一步方便進行問題的定位和診斷。

操作指南

 Command-Name                   Command-Description
   attach                       attach [pid],attach a java process and start the Arthas server in localhost 3658,then connect it

 Tips:
 Arthas allows developers to troubleshoot production issues for Java applications without modifying code or restarting servers.

XPocket管控了Arthas在attach進程之前的輸入輸出，attach之後的具體使用請參考Arthas官方文檔

Arthas
插件倉庫

插件概況

JConsole

簡介

JConsole 是一個內置Java性能分析器，用於對JVM中內存，線程和類等的監控，這款工具的好處在於，佔用系統資源少，而且結合Jstat，可以有效監控到java內存的變動情況，以及引起變動的原因。在項目追蹤內存泄露問題時，很實用。

操作指南

 Command-Name                   Command-Description
   attach                       attach <local jvm pid>
  
 Tips:
 1.使用help獲取幫助信息。
 2.更詳細的功能，請attach一個進程後使用

注：插件化後的JConsole相比gui版本的JConsole在顯示與操作上有所區別，但是數據的採集方式是一樣的。

插件倉庫

插件概況

VJMap

簡介

分代版的jmap（新生代，存活區，老生代），是排查內存緩慢泄露，老生代增長過快原因的利器。因爲jmap -histo PID 打印的是整個Heap的對象統計信息，而爲了定位上面的問題，我們需要專門查看OldGen對象，和Survivor區大齡對象的工具。
vjmap的原始思路來源於R大的TBJMap ，翻新後支持JDK8，支持Survivor區大齡對象過濾。
注意：因爲VJMap的原理，只支持CMS和ParallelGC，不支持G1。

操作指南

 Command-Name                   Command-Description
   vjmap                        vjmap 1.0.9 - prints per GC generation (Eden, Survivor, OldGen) object details of a given process.

 Tips:
 Usage: vjmap <options> <PID>
 Usage: vjmap <options> <executable java path> <coredump file path>
 Usage "help vjmap" show options info
 
 Example:
  打印整個堆中對象的統計信息，按對象的total size排序:
  vjmap -all PID > /tmp/histo.log
  
  推薦，打印老年代的對象統計信息，按對象的oldgen size排序，比-all快很多，暫時只支持CMS:
  vjmap -old PID > /tmp/histo-old.log
  
  推薦，打印Survivor區的對象統計信息，默認age>=3
  vjmap -sur PID > /tmp/histo-sur.log
  
  推薦，打印Survivor區的對象統計信息，查看age>=4的對象
  vjmap -sur:minage=4 PID > /tmp/histo-sur.log
  
  推薦，打印Survivor區的對象統計信息，單獨查看age＝4的對象:
  vjmap -sur:age=4 PID > /tmp/histo-sur.log

VJMap
插件倉庫

插件概況

Doraemon

簡介

Doraemon是PerfMa開發的一款鏈接性能分析產品的體驗工具，操作簡單，功能強大，提供jvm參數分析，線程離線分析以及內存離線分析的功能

操作指南

  Command-Name                   Command-Description
    attach                         attach <local jvm pid>
    detach                         detach
    analyse                        use 'analyse <AbsolutePath>' to analyse memory dump file
    help                           command help info
    
  Tips:
  1.更豐富的操作，請先attach一個進程

插件概況

插件中心

更豐富的內容，建議您前往插件中心

Tips

sa-jdi.jar 主要用於支持插件VJMap的正常使用（注：由於jdk8以上開始實施模塊化，導致VJMap的運行機制不兼容）。
框架擴展開發的包依賴: com.perfma.xlab:xpocket-framework-spi:2.0.0-RELEASE

鏡像倉庫

碼雲XPocket

官方文檔 | 【JVM調優體系】「GC底層調優實戰」XPocket爲終結性能問題而生—開發指南

XPocket 用戶文檔

插件開源生態

XPocket在線教程

XPocket官方網站

XPocket插件中心

快速開始

1.下載模擬程序，解壓並運行

2.下載xpocket，然後解壓並運行

3.使用插件

4.切換插件

5.獲取幫助

6.管道操作

7.退出插件

8.退出XPocket

運行模式

1. telnet server模式

2. run once 模式

3. Java Agent模式

插件開發

現有插件

HSDB

簡介

操作指南

JDB

簡介

操作指南

Perf

簡介

操作指南

Arthas

簡介

操作指南

JConsole

簡介

操作指南

VJMap

簡介

操作指南

Doraemon

簡介

操作指南

插件中心

Tips

鏡像倉庫