{"id":13696715,"url":"https://github.com/pandening/Java-debug-tool","last_synced_at":"2025-05-03T17:32:10.032Z","repository":{"id":38195538,"uuid":"237739792","full_name":"pandening/Java-debug-tool","owner":"pandening","description":"Java dynamic debug tool","archived":false,"fork":false,"pushed_at":"2024-04-15T11:50:47.000Z","size":46089,"stargazers_count":93,"open_issues_count":5,"forks_count":22,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-20T16:45:44.299Z","etag":null,"topics":["agent","debug","dynamic-debug","java","jvmti","profiling","tool"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pandening.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-02T08:16:47.000Z","updated_at":"2024-05-12T19:51:43.319Z","dependencies_parsed_at":"2024-05-12T19:51:39.273Z","dependency_job_id":"28e8008c-305d-4aff-96b7-b8461f052df4","html_url":"https://github.com/pandening/Java-debug-tool","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandening%2FJava-debug-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandening%2FJava-debug-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandening%2FJava-debug-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandening%2FJava-debug-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pandening","download_url":"https://codeload.github.com/pandening/Java-debug-tool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224369708,"owners_count":17299944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","debug","dynamic-debug","java","jvmti","profiling","tool"],"created_at":"2024-08-02T18:00:45.514Z","updated_at":"2025-05-03T17:32:10.022Z","avatar_url":"https://github.com/pandening.png","language":"Java","readme":"## Java-debug-tool\n\n### what is Java-debug-tool\n\nJava-debug-tool is a dynamic debugging tool. it provides some debugging commands to debug your code in runtime.\n\n### development plan\n\n[new features / bug fix / code clean / etc.](roadmap.md)\n\n### require\n\n* java 8 + , java 7 support is on the way ...\n* Unix like OS\n* libc\n\n\n### install Java-debug-tool\n\n#### download \u0026 install the Java-debug-tool\n\n```bash\nwget https://github.com/pandening/storm-ml/releases/download/8.0/javadebug-tool-install.sh\nsh javadebug-tool-install.sh\n```\n\n#### attach to target jvm\n\n```bash\n./javadebug-agent-launch.sh pid@ip:port \n./javadebug-agent-launch.sh pid@ip\n./javadebug-agent-launch.sh pid\n```\nthe default port is 11234.\n\n\n#### debug client launch\n\n```bash\n./javadebug-client-launch.sh \n./javadebug-client-launch.sh ip:port\n```\n\n\n### Ability\n\nJava-debug-tool including 2-part ability, debugging and profiling.\n\n#### debugging\n\ndebug your code in runtime, the main command list :\n\n* mt (method trace)\n* fc (find class)\n\nthe simplest usage of 'mt' command like this : \n\n```bash\n\n  mt -c [class name with package] -m [method name]\n\n```\n\nthere are many other options for mt command:\n\n* timeout   : set command execute timeout (seconds unit)\n* t         : the debug event type\n    * return : stop debug when method exit\n    * throw  : stop debug when method throw exception\n        *       e  ： the target exception class name [with package]\n        *       tl :  set the target invoked line, ref [line]\n        *       te :  set the target line's expression ref [line]   \n    * watch  : stop debug when the params match\n        *       i  : the spring expression\n        *       tl :  set the target invoked line, ref [line]\n        *       te :  set the target line's expression ref [line]   \n    * custom : call method \u0026 debug itself \n        *       i  : the params\n        *       tl :  set the target invoked line, ref [line]\n        *       te :  set the target line's expression ref [line]    \n    * line   : stop debug when special line is invoked(and the spring expression is true). \n        *       tl :  set the target invoked line\n        *       te :  set the target line's expression\n    * record : record some method calls  \n        *       u  : show the record method call with index [from 0 inc]\n        *       n  : the record count limit\n        *       time : timeout for recording\n* l       :  just show the target line's debug info\n\nfor 'fc' command, it's very easy to use:\n\n```bash\n\n[case 1] you know the class name and want to find the class \n   fc -class [class name]\n[case 2] you just want to find some classes by the regex\n   fc -r [regex to match class]   \n\n\n```\n\nthe 'l' option can set the output class limit. like this:\n\n```bash\n\nfc -r regex -l 10\n\n```\n\n#### profiling\n\n\njava-debug-tool can profiling your code, there are some command can get the performance data in run time;\n\n* thread\n* monitor\n* cputime\n\nthe thread command can get the cpu usage of each thread, and the call stack, and you can get the topN busy thread by this command:\n\nthread command options:\n\n* top       : [topN] get the topN busy thread info\n* status    : [R(runnable)|W(waiting)|TW(timed waiting)|B(blocking)] get the target status' thread info\n* tid      : [thread id] get the thread info by thread id\n\nmonitor (aka collect) command options :\n* t  : the monitor event type, multi type can split with ',' like thread,mem\n    * thread : the thread statistic info\n    * mem    : the mem info\n    * class  : the class info\n    * gc     : the gc info\n* i  : the interval (secs)\n\nthe default event is thread, the default interval is 5 seconds\n\nthe cputime command can get the cpu usage of the target jvm, the interval is 30 seconds, the base usage of this command is :\n\n```bash\n\nct -o csv\n\n```\n\nthe 'o' option set the output format, you can set one from [csv,json]; the csv format is recommend, you need to wait 30 seconds\nbefore the command execute successfully. the output like this:\n\n```text\n\n---------------------------------------------------------------------------------------------\nCommand            \t：ct\nRound              \t：1\nClientId           \t：10000\nClientType         \t：console:1\nVersion            \t：version:1\nCommandCost        \t：32125 (ms)\nSTW_Cost           \t：0 (ms)\nTime:              \t: Mon Feb 03 17:33:10 CST 2020\n---------------------------------------------------------------------------------------------\nStart Time : Mon Feb 03 17:32:38 CST 2020\nStop Time : Mon Feb 03 17:33:10 CST 2020\nTotal cpu usage : 35.425249999999984 ms\n\ntime;usr_ms;sys_ms;avg_usr_ms;avg_sys_ms;nivc_switch_per_sec;nvc_switch_per_sec\n0;22.729;13.790;20.770;14.655;514;11\n1;18.769;11.816;20.770;14.655;499;18\n2;19.048;12.215;20.770;14.655;483;13\n3;22.882;14.352;20.770;14.655;483;9\n4;49.963;17.214;20.770;14.655;479;18\n5;23.305;15.979;20.770;14.655;456;16\n6;22.382;13.520;20.770;14.655;491;8\n7;25.801;11.920;20.770;14.655;543;7\n8;18.927;12.211;20.770;14.655;509;14\n9;22.440;9.026;20.770;14.655;541;6\n10;20.290;13.212;20.770;14.655;472;13\n11;19.866;15.524;20.770;14.655;456;5\n12;24.528;16.648;20.770;14.655;447;19\n13;19.002;16.981;20.770;14.655;457;11\n14;20.882;16.202;20.770;14.655;452;15\n15;20.041;15.652;20.770;14.655;484;16\n16;17.661;10.187;20.770;14.655;507;4\n17;15.381;10.135;20.770;14.655;498;12\n18;18.671;16.080;20.770;14.655;446;13\n19;27.149;17.041;20.770;14.655;481;14\n20;18.231;13.681;20.770;14.655;502;14\n21;17.777;13.696;20.770;14.655;480;12\n22;18.266;16.266;20.770;14.655;450;17\n23;20.510;16.447;20.770;14.655;480;13\n24;19.699;16.250;20.770;14.655;474;14\n25;19.966;15.105;20.770;14.655;455;24\n26;25.839;15.825;20.770;14.655;447;15\n27;19.736;16.556;20.770;14.655;455;17\n28;18.673;16.246;20.770;14.655;440;18\n29;18.499;16.801;20.770;14.655;447;16\n\n---------------------------------------------------------------------------------------------\n\n```\n\n* time                  : the time line\n* usr_ms                : user time mills\n* sys_ms                : system time mills\n* avg_usr_ms            : the avg user time mills\n* avg_sys_ms            : the avg system time mills\n* nivc_switch_per_sec   : the nivc switch per sec\n* nvc_switch_per_sec    ：the nvc switch per sec\n\n```text\n        \n        |\n        |\n        |     \n        |\n        |\n    val |\n        |\n        |\n        |\n        |\n        |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _\n               time line [0 - 29] \n\n```\n\nfor profiling, you can choose [async-profiler](bin/async-profiler) which already including in bin path of java-debug-tool.\n\n### Demo \n\nwe will use a simple case to show the usage of java-debug-tool:\n\n```java\nimport java.util.Random;\nimport java.util.concurrent.TimeUnit;\n\npublic class Demo {\n\n    private void say(String word, boolean tag, int rdm) {\n        if (word == null) {\n            word = \"test say\";\n        }\n        int length = word.length();\n        if (tag) {\n            length += 1;\n        } else {\n            length -= 1;\n        }\n        word += \"@\" + length;\n        System.out.println(word);\n        if (rdm \u003e 5) {\n            throw new IllegalStateException(\"test exception\");\n        }\n    }\n\n    private static final String[] list = {\"a\", \"ab\", \"abc\", \"abcd\"};\n\n    public static void main(String[] args) {\n        Demo demo = new Demo();\n        Random random = new Random(47);\n        new Thread(new Runnable() {\n            @Override\n            public void run() {\n                for(;;) {\n                    try {\n                        demo.say(list[random.nextInt(4)], random.nextBoolean(), random.nextInt(10));\n                        TimeUnit.MILLISECONDS.sleep(100);\n                    } catch (Exception e) {\n                        e.printStackTrace();\n                    }\n                }\n            }\n        }, \"demo-thread\").start();\n    }\n\n}\n\n```\n\nthe 'mt' command (aka method trace) is the main command of java-debug-tool, this command \ncan offer many runtime info of target method:\n\n* Action time\n* caller thread\n* method params\n* line cost\n* invoked line number\n* line variables\n* return val\n* exception\n* call stack\n\n![mt command detail](https://p1.meituan.net/travelcube/f5ac2f15e1c8794448ed980fe6eed91397685.png)\n\n\n### usage\n\nusing 'list' command to show all of the commands, then use 'help' command to get the usage of the command;\n\n```bash\n\n  list\n  h -cmd list\n  h -cmd mt\n  h -cmd monitor\n  ...\n\n```\n\n![list command](https://p1.meituan.net/travelcube/70b00b644f4d9b5408df122b7c226631140733.png)\n```text\n127.0.0.1:11234\u003elist\n\n---------------------------------------------------------------------------------------------\nCommand            \t：list\nRound              \t：2\nClientId           \t：10000\nClientType         \t：console:1\nVersion            \t：version:1\nCommandCost        \t：4 (ms)\nSTW_Cost           \t：0 (ms)\nTime:              \t: Sun Feb 02 17:22:20 CST 2020\n---------------------------------------------------------------------------------------------\nfc\nhelp\nlist\nexit\nalive\nredefine\nrollback\nlock\nset\ninfo\ntrace\nmt\nct\nthread\nmonitor\nbtrace\n\n---------------------------------------------------------------------------------------------\n```\n\n![help command](https://p1.meituan.net/travelcube/d4a8eaeaa070396cf6f472e53b9685a9111432.png)\n```text\n127.0.0.1:11234\u003eh -cmd list\n\n---------------------------------------------------------------------------------------------\nCommand            \t：h\nRound              \t：3\nClientId           \t：10000\nClientType         \t：console:1\nVersion            \t：version:1\nCommandCost        \t：7 (ms)\nSTW_Cost           \t：0 (ms)\nTime:              \t: Sun Feb 02 17:22:39 CST 2020\n---------------------------------------------------------------------------------------------\nCommand    \t: list | all\nFunction   \t: list commands\nUsage      \t: list | all\nType       \t: COMPUTE\n\n---------------------------------------------------------------------------------------------\n```\n\n![monitor command](https://p0.meituan.net/travelcube/74c50cdff72994f8ac6f02d922262528158297.png)\n```text\n--------------------------------------------------------------------------------\n                Thread Dynamic Statistic\n--------------------------------------------------------------------------------\n-----      -----                                              -----      -----\ntid        name                                                 s        cpu%\n-----      -----                                              -----      -----\n11         test-test-R-worker                                   TW       95%\n20         Java-Debug-Tool-WebSocket-Server-Worker              R        5%\n\nTotal Thread : 13, New : 0, Runnable : 7, Blocked : 0, Waiting : 4, Timed Waiting : 2, Terminated : 0\n--- System Load ---\nAvailableProcessors                     8\nSystemLoadAverage              3.18652343\nProcessCpuLoad                 0.01164025\n\n\n--------------------------------------------------------------------------------\nq\n```\n\n![method trace command](https://p0.meituan.net/travelcube/e19e52ee5dc4aa941d9be79c8e2dc0aa262152.png)\n```text\n127.0.0.1:11234\u003emt -c R -m call\n\n---------------------------------------------------------------------------------------------\nCommand            \t：mt\nRound              \t：6\nClientId           \t：10000\nClientType         \t：console:1\nVersion            \t：version:1\nCommandCost        \t：411 (ms)\nSTW_Cost           \t：68 (ms)\nTime:              \t: Sun Feb 02 17:23:52 CST 2020\n---------------------------------------------------------------------------------------------\n[R.call] invoke by Thread:Thread[test-test-R-worker,5,main]\nwith params\n[\n[0] @class:java.lang.Integer -\u003e 6,\n[1] @class:java.lang.Integer -\u003e 6,\n[2] @class:C -\u003e {\"@class\":\"C\",\"a\":0},\n[3] @unknown -\u003e NULL,\n[4] @unknown -\u003e NULL,\n[5] @unknown -\u003e NULL,\n[6] @unknown -\u003e NULL,\n[7] @class:java.util.ArrayList -\u003e [\"java.util.ArrayList\",[{\"@class\":\"R$MMM\",\"data\":\"test\"}]]\n]\n[0 ms] (73) [mmmList1 = [\"java.util.ArrayList\",[{\"@class\":\"R$MMM\",\"data\":\"test\"}]]]\n[0 ms] (74)\n[0 ms] (75)\n[0 ms] (79)\n[0 ms] (83) [el = -1]\n[0 ms] (84)\n[0 ms] (89)\n[0 ms] (93)\n[0 ms] (97)\n[0 ms] (99) [sa = 1]\n[0 ms] (100)\n[1 ms] (101) [ii = 0]\n[0 ms] (102) [ij = 0]\n[0 ms] (103) [jk = 1]\n[0 ms] (104) [f = 1.0]\n[0 ms] (105) [d = 0.123]\n[0 ms] (106) [name = \"hello6,6\"]\n[0 ms] (107) [list = [\"java.util.ArrayList\",[6,7]]]\n[0 ms] (108)\n[0 ms] (109)\n[0 ms] (110)\n[0 ms] (112)\n[0 ms] (115)\n[0 ms] (118)\n[0 ms] (119)\nthrow exception:[java.lang.IllegalArgumentException:  i + j \u003c= 10:66]  at line:119 with cost:3 ms\n -R.call\n  -R$1.run at line:152\n   -java.lang.Thread.run at line:748\n\n---------------------------------------------------------------------------------------------\n```\n\n[usage](usage.md)\n\n### develop\n\n#### the module / dir\n\n* agent\n\nthe agent code, do attach work.\n\n\n* core\n\nthe java-debug-tool's biz codes, including netty-handler, debug-client / debug-server, command handler, etc;\n\n* test\n\nthe test module, test codes write here;\n\n* script\n\nthe java-debug-tool's script dir;\n\n* bin\n\nthe target bin dir;\n\n\n#### pack \n\n```bash\n \n cd script\n ./javadebug-pack.sh\n\n```\n\nenjoy !\n\n### License\n\n```text\n\n//\n//  ========================================================================\n//  Copyright (c) 2018-2019 HuJian/Pandening soft collection.\n//  ------------------------------------------------------------------------\n//  All rights reserved. This program and the accompanying materials\n//  are made available under the terms of the #{license} Public License #{version}\n//  EG:\n//      The Eclipse Public License is available at\n//      http://www.eclipse.org/legal/epl-v10.html\n//\n//      The Apache License v2.0 is available at\n//      http://www.opensource.org/licenses/apache2.0.php\n//\n//  You may elect to redistribute this code under either of these licenses.\n//  You should bear the consequences of using the software (named 'java-debug-tool')\n//  and any modify must be create an new pull request and attach an text to describe\n//  the change detail.\n//  ========================================================================\n//\n\n```\n\n### Thanks\n\n* [Netty](https://github.com/netty/netty) : Transport support.\n* [JLine](https://github.com/jline/jline2) : Console support.\n* [jna](https://github.com/java-native-access/jna) : java native access support.\n* [ASM](https://github.com/llbit/ow2-asm) :  java bytecode weaver.\n* [arthas](https://github.com/alibaba/arthas) : java-debut-tool reference arthas.\n* [async-profiler](https://github.com/jvm-profiling-tools/async-profiler) : profiling support. \n\nThanks for the excellent work in these projects!\n","funding_links":[],"categories":["Java","3. Application"],"sub_categories":["Java"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpandening%2FJava-debug-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpandening%2FJava-debug-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpandening%2FJava-debug-tool/lists"}