You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
arthas/en/trace.html

452 lines
22 KiB
HTML

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>trace &mdash; Arthas 3.1.7 documentation</title>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<script type="text/javascript" src="_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/overrides.css" type="text/css" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="stack" href="stack.html" />
<link rel="prev" title="Fundamental Fields in Expressions" href="advice-class.html" />
<script src="_static/center_page.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/github.min.css">
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home"> Arthas
</a>
<div class="version">
3.1.7
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference external" href="https://alibaba.github.io/arthas/arthas-tutorials?language=en">Online tutorials(Recommend)</a></li>
<li class="toctree-l1"><a class="reference internal" href="install-detail.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="quick-start.html">Quick start</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced-use.html">Advanced usage</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="commands.html">Commands</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="dashboard.html">dashboard</a></li>
<li class="toctree-l2"><a class="reference internal" href="thread.html">thread</a></li>
<li class="toctree-l2"><a class="reference internal" href="jvm.html">jvm</a></li>
<li class="toctree-l2"><a class="reference internal" href="sysprop.html">sysprop</a></li>
<li class="toctree-l2"><a class="reference internal" href="sysenv.html">sysenv</a></li>
<li class="toctree-l2"><a class="reference internal" href="vmoption.html">vmoption</a></li>
<li class="toctree-l2"><a class="reference internal" href="logger.html">logger</a></li>
<li class="toctree-l2"><a class="reference internal" href="mbean.html">mbean</a></li>
<li class="toctree-l2"><a class="reference internal" href="getstatic.html">getstatic</a></li>
<li class="toctree-l2"><a class="reference internal" href="ognl.html">ognl</a></li>
<li class="toctree-l2"><a class="reference internal" href="sc.html">sc</a></li>
<li class="toctree-l2"><a class="reference internal" href="sm.html">sm</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump.html">dump</a></li>
<li class="toctree-l2"><a class="reference internal" href="heapdump.html">heapdump</a></li>
<li class="toctree-l2"><a class="reference internal" href="jad.html">jad</a></li>
<li class="toctree-l2"><a class="reference internal" href="classloader.html">classloader</a></li>
<li class="toctree-l2"><a class="reference internal" href="mc.html">mc</a></li>
<li class="toctree-l2"><a class="reference internal" href="redefine.html">redefine</a></li>
<li class="toctree-l2"><a class="reference internal" href="monitor.html">monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="watch.html">watch</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">trace</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#parameters">Parameters</a></li>
<li class="toctree-l3"><a class="reference internal" href="#notice">Notice</a></li>
<li class="toctree-l3"><a class="reference internal" href="#usage">Usage</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#start-demo">Start Demo</a></li>
<li class="toctree-l4"><a class="reference internal" href="#trace-method">trace method</a></li>
<li class="toctree-l4"><a class="reference internal" href="#trace-times-limit">trace times limit</a></li>
<li class="toctree-l4"><a class="reference internal" href="#include-jdk-method">Include jdk method</a></li>
<li class="toctree-l4"><a class="reference internal" href="#filtering-by-cost">Filtering by cost</a></li>
<li class="toctree-l4"><a class="reference internal" href="#trace-multiple-classes-or-multiple-methods">trace multiple classes or multiple methods</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="stack.html">stack</a></li>
<li class="toctree-l2"><a class="reference internal" href="tt.html">tt</a></li>
<li class="toctree-l2"><a class="reference internal" href="profiler.html">profiler</a></li>
<li class="toctree-l2"><a class="reference internal" href="cat.html">cat</a></li>
<li class="toctree-l2"><a class="reference internal" href="grep.html">grep</a></li>
<li class="toctree-l2"><a class="reference internal" href="pwd.html">pwd</a></li>
<li class="toctree-l2"><a class="reference internal" href="options.html">options</a></li>
<li class="toctree-l2"><a class="reference internal" href="commands.html#basic-arthas-commands">Basic Arthas Commands</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="web-console.html">WebConsole</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker.html">Docker</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/alibaba/arthas/issues?q=label%3Auser-case">User cases</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/alibaba/arthas/issues?q=label%3Aquestion-answered">Questions and answers</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/alibaba/arthas">Fork me at GitHub</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/alibaba/arthas/blob/master/CONTRIBUTING.md#">Compile and debug/CONTRIBUTING</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/alibaba/arthas/releases">Release Notes</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Arthas</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li><a href="commands.html">All Commands</a> &raquo;</li>
<li>trace</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/alibaba/arthas/blob/master/site/src/site/sphinx/en/trace.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="trace">
<h1>trace<a class="headerlink" href="#trace" title="Permalink to this headline"></a></h1>
<blockquote>
<div><p>Trace method calling path, and output the time cost for each node in the path.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">trace</span></code> can track the calling path specified by <code class="docutils literal notranslate"><span class="pre">class-pattern</span></code> / <code class="docutils literal notranslate"><span class="pre">method-pattern</span></code>, and calculate the time cost on the whole path.</p>
<div class="section" id="parameters">
<h2>Parameters<a class="headerlink" href="#parameters" title="Permalink to this headline"></a></h2>
<table border="1" class="docutils">
<thead>
<tr>
<th align="right">Name</th>
<th align="left">Specification</th>
</tr>
</thead>
<tbody>
<tr>
<td align="right"><em>class-pattern</em></td>
<td align="left">pattern for the class name</td>
</tr>
<tr>
<td align="right"><em>method-pattern</em></td>
<td align="left">pattern for the method name</td>
</tr>
<tr>
<td align="right"><em>condition-express</em></td>
<td align="left">condition expression</td>
</tr>
<tr>
<td align="right"><code>[E]</code></td>
<td align="left">enable regex match, the default behavior is wildcards match</td>
</tr>
<tr>
<td align="right"><code>[n:]</code></td>
<td align="left">execution times</td>
</tr>
<tr>
<td align="right">#cost</td>
<td align="left">time cost</td>
</tr>
</tbody>
</table><p>Theres one thing worthy noting here is observation expression. The observation expression supports OGNL grammar, for example, you can come up a expression like this <code class="docutils literal notranslate"><span class="pre">&quot;{params,returnObj}&quot;</span></code>. All OGNL expressions are supported as long as they are legal to the grammar.</p>
<p>Thanks for <code class="docutils literal notranslate"><span class="pre">advice</span></code>s data structure, it is possible to observe from varieties of different angles. Inside <code class="docutils literal notranslate"><span class="pre">advice</span></code> parameter, all necessary information for notification can be found.</p>
<p>Pls. refer to <a class="reference internal" href="advice-class.html"><span class="doc">core parameters in expression</span></a> for more details.</p>
<ul class="simple">
<li><p>Pls. also refer to <a class="reference external" href="https://github.com/alibaba/arthas/issues/71">https://github.com/alibaba/arthas/issues/71</a> for more advanced usage</p></li>
<li><p>OGNL official site: <a class="reference external" href="https://commons.apache.org/proper/commons-ognl/language-guide.html">https://commons.apache.org/proper/commons-ognl/language-guide.html</a></p></li>
</ul>
<p>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: <code class="docutils literal notranslate"><span class="pre">trace</span> <span class="pre">*StringUtils</span> <span class="pre">isBlank</span> <span class="pre">'#cost&gt;100'</span></code> means trace result will only be output when the executing time exceeds 100ms.</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">watch</span></code>/<code class="docutils literal notranslate"><span class="pre">stack</span></code>/<code class="docutils literal notranslate"><span class="pre">trace</span></code>, these three commands all support <code class="docutils literal notranslate"><span class="pre">#cost</span></code>.</p>
</div></blockquote>
</div>
<div class="section" id="notice">
<h2>Notice<a class="headerlink" href="#notice" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">trace</span></code> 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.</p>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline"></a></h2>
<div class="section" id="start-demo">
<h3>Start Demo<a class="headerlink" href="#start-demo" title="Permalink to this headline"></a></h3>
<p>Start <code class="docutils literal notranslate"><span class="pre">arthas-demo</span></code> in <a class="reference internal" href="quick-start.html"><span class="doc">Quick Start</span></a>.</p>
</div>
<div class="section" id="trace-method">
<h3>trace method<a class="headerlink" href="#trace-method" title="Permalink to this headline"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight hljs"><pre class="bash">$ trace demo.MathGame run
Press Q or Ctrl+C to abort.
Affect(class-cnt:1 , method-cnt:1) cost in 28 ms.
`---ts=2019-12-04 00:45:08;thread_name=main;id=1;is_daemon=false;priority=5;TCCL=sun.misc.Launcher$AppClassLoader@3d4eac69
`---[0.617465ms] demo.MathGame:run()
`---[0.078946ms] demo.MathGame:primeFactors() #24 [throws Exception]
`---ts=2019-12-04 00:45:09;thread_name=main;id=1;is_daemon=false;priority=5;TCCL=sun.misc.Launcher$AppClassLoader@3d4eac69
`---[1.276874ms] demo.MathGame:run()
`---[0.03752ms] demo.MathGame:primeFactors() #24 [throws Exception]</pre></div>
</div>
</div>
<div class="section" id="trace-times-limit">
<h3>trace times limit<a class="headerlink" href="#trace-times-limit" title="Permalink to this headline"></a></h3>
<p>If the method invoked many times, use <code class="docutils literal notranslate"><span class="pre">-n</span></code> options to specify trace times. For example, the command will exit when received a trace result.</p>
<div class="highlight-bash notranslate"><div class="highlight hljs"><pre class="bash">$ trace demo.MathGame run -n 1
Press Q or Ctrl+C to abort.
Affect(class-cnt:1 , method-cnt:1) cost in 20 ms.
`---ts=2019-12-04 00:45:53;thread_name=main;id=1;is_daemon=false;priority=5;TCCL=sun.misc.Launcher$AppClassLoader@3d4eac69
`---[0.549379ms] demo.MathGame:run()
+---[0.059839ms] demo.MathGame:primeFactors() #24
`---[0.232887ms] demo.MathGame:print() #25
Command execution times exceed limit: 1, so command will exit. You can set it with -n option.</pre></div>
</div>
</div>
<div class="section" id="include-jdk-method">
<h3>Include jdk method<a class="headerlink" href="#include-jdk-method" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">--skipJDKMethod</span> <span class="pre">&lt;value&gt;</span> </code> skip jdk method trace, default value true.</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight hljs"><pre class="bash">$ trace --skipJDKMethod false demo.MathGame run
Press Q or Ctrl+C to abort.
Affect(class-cnt:1 , method-cnt:1) cost in 60 ms.
`---ts=2019-12-04 00:44:41;thread_name=main;id=1;is_daemon=false;priority=5;TCCL=sun.misc.Launcher$AppClassLoader@3d4eac69
`---[1.357742ms] demo.MathGame:run()
+---[0.028624ms] java.util.Random:nextInt() #23
+---[0.045534ms] demo.MathGame:primeFactors() #24 [throws Exception]
+---[0.005372ms] java.lang.StringBuilder:&lt;init&gt;() #28
+---[0.012257ms] java.lang.Integer:valueOf() #28
+---[0.234537ms] java.lang.String:format() #28
+---[min=0.004539ms,max=0.005778ms,total=0.010317ms,count=2] java.lang.StringBuilder:append() #28
+---[0.013777ms] java.lang.Exception:getMessage() #28
+---[0.004935ms] java.lang.StringBuilder:toString() #28
`---[0.06941ms] java.io.PrintStream:println() #28
`---ts=2019-12-04 00:44:42;thread_name=main;id=1;is_daemon=false;priority=5;TCCL=sun.misc.Launcher$AppClassLoader@3d4eac69
`---[3.030432ms] demo.MathGame:run()
+---[0.010473ms] java.util.Random:nextInt() #23
+---[0.023715ms] demo.MathGame:primeFactors() #24 [throws Exception]
+---[0.005198ms] java.lang.StringBuilder:&lt;init&gt;() #28
+---[0.006405ms] java.lang.Integer:valueOf() #28
+---[0.178583ms] java.lang.String:format() #28
+---[min=0.011636ms,max=0.838077ms,total=0.849713ms,count=2] java.lang.StringBuilder:append() #28
+---[0.008747ms] java.lang.Exception:getMessage() #28
+---[0.019768ms] java.lang.StringBuilder:toString() #28
`---[0.076457ms] java.io.PrintStream:println() #28</pre></div>
</div>
</div>
<div class="section" id="filtering-by-cost">
<h3>Filtering by cost<a class="headerlink" href="#filtering-by-cost" title="Permalink to this headline"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight hljs"><pre class="bash">$ trace demo.MathGame run &#x27;#cost &gt; 10&#x27;
Press Ctrl+C to abort.
Affect(class-cnt:1 , method-cnt:1) cost in 41 ms.
`---ts=2018-12-04 01:12:02;thread_name=main;id=1;is_daemon=false;priority=5;TCCL=sun.misc.Launcher$AppClassLoader@3d4eac69
`---[12.033735ms] demo.MathGame:run()
+---[0.006783ms] java.util.Random:nextInt()
+---[11.852594ms] demo.MathGame:primeFactors()
`---[0.05447ms] demo.MathGame:print()</pre></div>
</div>
<blockquote>
<div><p>Only the call path whichs time cost is higher than <code class="docutils literal notranslate"><span class="pre">10ms</span></code> will be shown. This feature is handy to focus on whats needed to focus when troubleshoot.</p>
</div></blockquote>
<ul class="simple">
<li><p>Here Arthas provides the similar functionality JProfile and other commercial software provide. Compared to these professional softwares, Arthas doesnt deduce the time cost <code class="docutils literal notranslate"><span class="pre">trace</span></code> itself takes, therefore it is not as accurate as these softwares offer. More classes and methods on the calling path, more inaccurate <code class="docutils literal notranslate"><span class="pre">trace</span></code> output is, but it is still helpful for diagnostics where the bottleneck is.</p></li>
<li><p>“[12.033735ms]” means the method on the node takes <code class="docutils literal notranslate"><span class="pre">12.033735</span></code> ms.</p></li>
<li><p>“[min=0.005428ms,max=0.094064ms,total=0.105228ms,count=3] demo:call()” means aggregating all same method calls into one single line. The minimum time cost is <code class="docutils literal notranslate"><span class="pre">0.005428</span></code> ms, the maximum time cost is <code class="docutils literal notranslate"><span class="pre">0.094064</span></code> ms, and the total time cost for all method calls (<code class="docutils literal notranslate"><span class="pre">3</span></code> times in total) to “demo:call()” is <code class="docutils literal notranslate"><span class="pre">0.105228ms</span></code>. If “throws Exception” appears in this line, it means some exceptions have been thrown from this method calls.</p></li>
<li><p>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.</p></li>
</ul>
</div>
<div class="section" id="trace-multiple-classes-or-multiple-methods">
<h3>trace multiple classes or multiple methods<a class="headerlink" href="#trace-multiple-classes-or-multiple-methods" title="Permalink to this headline"></a></h3>
<p>The trace command will only trace the subcalls in the method to the trace, and will not trace down multiple layers. Because traces are expensive, multi-layer traces can lead to a lot of classes and methods that ultimately have to be traced.</p>
<p>You can use the regular expression to match multiple classes and methods on the path to achieve a multi-layer trace effect to some extent.</p>
<div class="highlight-bash notranslate"><div class="highlight hljs"><pre class="bash">Trace -E com.test.ClassA|org.test.ClassB method1|method2|method3</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="stack.html" class="btn btn-neutral float-right" title="stack" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="advice-class.html" class="btn btn-neutral float-left" title="Fundamental Fields in Expressions" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2018-2019, Alibaba Middleware Group, and contributors
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
<div class="github-fork-ribbon-wrapper right">
<div class="github-fork-ribbon">
<a href="https://github.com/alibaba/arthas" target="_blank">Fork me at GitHub</a>
</div>
</div>
<script type="text/javascript" src="_static/add_badges.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/highlight.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlightjs-line-numbers.js/2.5.0/highlightjs-line-numbers.min.js"></script>
<script>
document.querySelectorAll('div.hljs > pre').forEach(function(block) {
hljs.highlightBlock(block);
hljs.lineNumbersBlock(block);
});
</script>
<script>
var _hmt = _hmt || [];
(function() {
var hm = document.createElement("script");
hm.src = "https://hm.baidu.com/hm.js?d5c5e25b100f0eb51a4c35c8a86ea9b4";
var s = document.getElementsByTagName("script")[0];
s.parentNode.insertBefore(hm, s);
})();
</script>
</body>
</html>