<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.19.1">
<title>profile.cprof – Mix v1.7.2</title>
<link rel="stylesheet" href="dist/app-240d7fc7e5.css" />
<link rel="canonical" href="https://hexdocs.pm/mix/v1.7/Mix.Tasks.Profile.Cprof.html" />
<script src="dist/sidebar_items-0c0044e6e4.js"></script>
</head>
<body data-type="tasks">
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
<div class="main">
<button class="sidebar-button sidebar-toggle">
<span class="icon-menu" aria-hidden="true"></span>
<span class="sr-only">Toggle Sidebar</span>
</button>
<button class="sidebar-button night-mode-toggle">
<span class="icon-theme" aria-hidden="true"></span>
<span class="sr-only">Toggle Theme</span>
</button>
<section class="sidebar">
<a href="http://elixir-lang.org/docs.html" class="sidebar-projectLink">
<div class="sidebar-projectDetails">
<h1 class="sidebar-projectName">
Mix </h1>
<h2 class="sidebar-projectVersion">
v1.7.2
</h2>
</div>
<img src="assets/logo.png" alt="Mix" class="sidebar-projectImage">
</a>
<form class="sidebar-search" action="search.html">
<button type="submit" class="search-button">
<span class="icon-search" aria-hidden="true"></span>
</button>
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
</form>
<ul class="sidebar-listNav">
<li><a id="extras-list" href="#full-list">Pages</a></li>
<li><a id="modules-list" href="#full-list">Modules</a></li>
<li><a id="exceptions-list" href="#full-list">Exceptions</a></li>
<li><a id="tasks-list" href="#full-list">Mix Tasks</a></li>
</ul>
<div class="gradient"></div>
<ul id="full-list" class="sidebar-fullList"></ul>
</section>
<section class="content">
<div class="content-outer">
<div id="content" class="content-inner">
<h1>
<small class="visible-xs">Mix v1.7.2</small>
mix profile.cprof
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/tasks/profile.cprof.ex#L1" title="View Source" class="view-source" rel="help">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</h1>
<section id="moduledoc">
<p>Profiles the given file or expression using Erlang’s <code class="inline">cprof</code> tool.</p>
<p><code class="inline">cprof</code> can be useful when you want to discover the bottlenecks related
to function calls.</p>
<p>Before running the code, it invokes the <code class="inline">app.start</code> task which compiles
and loads your project. Then the target expression is profiled, together
with all matching function calls, by setting breakpoints containing
counters. These can only be set on BEAM code so BIFs cannot be call
count traced.</p>
<p>To profile the code, you can use syntax similar to the <code class="inline">mix run</code> task:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">mix</span><span class="w"> </span><span class="n">profile</span><span class="o">.</span><span class="n">cprof</span><span class="w"> </span><span class="o">-</span><span class="n">e</span><span class="w"> </span><span class="nc">Hello</span><span class="o">.</span><span class="n">world</span><span class="w">
</span><span class="n">mix</span><span class="w"> </span><span class="n">profile</span><span class="o">.</span><span class="n">cprof</span><span class="w"> </span><span class="o">-</span><span class="n">e</span><span class="w"> </span><span class="s">"[1, 2, 3] |> Enum.reverse |> Enum.map(&Integer.to_string/1)"</span><span class="w">
</span><span class="n">mix</span><span class="w"> </span><span class="n">profile</span><span class="o">.</span><span class="n">cprof</span><span class="w"> </span><span class="n">my_script</span><span class="o">.</span><span class="n">exs</span><span class="w"> </span><span class="n">arg1</span><span class="w"> </span><span class="n">arg2</span><span class="w"> </span><span class="n">arg3</span></code></pre>
<p>This task is automatically reenabled, so you can profile multiple times
in the same Mix invocation.</p>
<h2 id="module-command-line-options" class="section-heading">
<a href="#module-command-line-options" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Command line options
</h2>
<ul>
<li><code class="inline">--matching</code> - only profile calls matching the given <code class="inline">Module.function/arity</code> pattern
</li>
<li><code class="inline">--limit</code> - filters out any results with a call count less than the limit
</li>
<li><code class="inline">--module</code> - filters out any results not pertaining to the given module
</li>
<li><code class="inline">--config</code>, <code class="inline">-c</code> - loads the given configuration file
</li>
<li><code class="inline">--eval</code>, <code class="inline">-e</code> - evaluate the given code
</li>
<li><code class="inline">--require</code>, <code class="inline">-r</code> - requires pattern before running the command
</li>
<li><code class="inline">--parallel</code>, <code class="inline">-p</code> - makes all requires parallel
</li>
<li><code class="inline">--no-compile</code> - does not compile even if files require compilation
</li>
<li><code class="inline">--no-deps-check</code> - does not check dependencies
</li>
<li><code class="inline">--no-archives-check</code> - does not check archives
</li>
<li><code class="inline">--no-halt</code> - does not halt the system after running the command
</li>
<li><code class="inline">--no-start</code> - does not start applications after compilation
</li>
<li><code class="inline">--no-elixir-version-check</code> - does not check the Elixir version from mix.exs
</li>
</ul>
<h2 id="module-profile-output" class="section-heading">
<a href="#module-profile-output" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Profile output
</h2>
<p>Example output:</p>
<pre><code class="nohighlight makeup elixir"><span class="w"> </span><span class="nc">CNT</span><span class="w">
</span><span class="nc">Total</span><span class="w"> </span><span class="mi">15</span><span class="w">
</span><span class="nc">Enum</span><span class="w"> </span><span class="mi">6</span><span class="w"> </span><span class="o"><-</span><span class="o">-</span><span class="w">
</span><span class="nc">Enum</span><span class="o">.</span><span class="s">"-map/2-lists^map/1-0-"</span><span class="o">/</span><span class="mi">2</span><span class="w"> </span><span class="mi">4</span><span class="w">
</span><span class="nc">Enum</span><span class="o">.</span><span class="n">reverse</span><span class="o">/</span><span class="mi">1</span><span class="w"> </span><span class="mi">1</span><span class="w">
</span><span class="nc">Enum</span><span class="o">.</span><span class="n">map</span><span class="o">/</span><span class="mi">2</span><span class="w"> </span><span class="mi">1</span><span class="w">
</span><span class="ss">:elixir_compiler</span><span class="w"> </span><span class="mi">4</span><span class="w"> </span><span class="o"><-</span><span class="o">-</span><span class="w">
</span><span class="n">anonymous</span><span class="w"> </span><span class="k" data-group-id="8582142422-1">fn</span><span class="o">/</span><span class="mi">1</span><span class="w"> </span><span class="ow">in</span><span class="w"> </span><span class="ss">:elixir_compiler</span><span class="o">.</span><span class="c">__FILE__</span><span class="o">/</span><span class="mi">1</span><span class="w"> </span><span class="mi">3</span><span class="w">
</span><span class="n">anonymous</span><span class="w"> </span><span class="k" data-group-id="8582142422-2">fn</span><span class="o">/</span><span class="mi">0</span><span class="w"> </span><span class="ow">in</span><span class="w"> </span><span class="ss">:elixir_compiler</span><span class="o">.</span><span class="c">__FILE__</span><span class="o">/</span><span class="mi">1</span><span class="w"> </span><span class="mi">1</span><span class="w">
</span><span class="nc">String.Chars.Integer</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="o"><-</span><span class="o">-</span><span class="w">
</span><span class="nc">String.Chars.Integer</span><span class="o">.</span><span class="n">to_string</span><span class="o">/</span><span class="mi">1</span><span class="w"> </span><span class="mi">3</span><span class="w">
</span><span class="ss">:erlang</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="o"><-</span><span class="o">-</span><span class="w">
</span><span class="ss">:erlang</span><span class="o">.</span><span class="n">trace_pattern</span><span class="o">/</span><span class="mi">3</span><span class="w"> </span><span class="mi">2</span><span class="w">
</span><span class="nc">Profile</span><span class="w"> </span><span class="n">done</span><span class="w"> </span><span class="n">over</span><span class="w"> </span><span class="mi">20229</span><span class="w"> </span><span class="n">matching</span><span class="w"> </span><span class="n">functions</span></code></pre>
<p>The default output contains data gathered from all matching functions. The left
column structures each module and its total call count trace is presented on the right.
Each module has its count discriminated by function below. The <code class="inline"><--</code> symbol is meant to
help visualize where a new module call count begins.</p>
<p>The first row (Total) is the sum of all function calls. In the last row the number of
matching functions that were considered for profiling is presented.</p>
<p>When <code class="inline">--matching</code> option is specified, call count tracing will be started only for
the functions matching the given pattern:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">String.Chars.Integer</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="o"><-</span><span class="o">-</span><span class="w">
</span><span class="nc">String.Chars.Integer</span><span class="o">.</span><span class="n">to_string</span><span class="o">/</span><span class="mi">1</span><span class="w"> </span><span class="mi">3</span><span class="w">
</span><span class="nc">Profile</span><span class="w"> </span><span class="n">done</span><span class="w"> </span><span class="n">over</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="n">matching</span><span class="w"> </span><span class="n">functions</span></code></pre>
<p>The pattern can be a module name, such as <a href="https://hexdocs.pm/elixir/String.html"><code class="inline">String</code></a> to count all calls to that module,
a call without arity, such as <code class="inline">String.split</code>, to count all calls to that function
regardless of arity, or a call with arity, such as <a href="https://hexdocs.pm/elixir/String.html#split/2"><code class="inline">String.split/2</code></a>, to count all
calls to that exact module, function and arity.</p>
<h2 id="module-caveats" class="section-heading">
<a href="#module-caveats" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Caveats
</h2>
<p>You should be aware the profiler is stopped as soon as the code has finished running. This
may need special attention, when: running asynchronous code as function calls which were
called before the profiler stopped will not be counted; running synchronous code as long
running computations and a profiler without a proper MFA trace pattern or filter may
lead to a result set which is difficult to comprehend.</p>
<p>Other caveats are the impossibility to call count trace BIFs, since breakpoints can
only be set on BEAM code; functions calls performed by <code class="inline">:cprof</code> are not traced; the
maximum size of a call counter is equal to the host machine’s word size
(for example, 2147483647 in a 32-bit host).</p>
</section>
<section id="summary" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#summary">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Summary
</h1>
<div class="summary-functions summary">
<h2>
<a href="#functions">Functions</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#profile/2">profile(fun, opts \\ [])</a>
</div>
<div class="summary-synopsis"><p>Allows to programatically run the <code class="inline">cprof</code> profiler on expression in <code class="inline">fun</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#run/1">run(args)</a>
</div>
<div class="summary-synopsis"><p>A task needs to implement <code class="inline">run</code> which receives
a list of command line args</p>
</div>
</div>
</div>
</section>
<section id="functions" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#functions">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Functions
</h1>
<div class="detail" id="profile/2">
<span id="profile/1"></span>
<div class="detail-header">
<a href="#profile/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">profile(fun, opts \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/tasks/profile.cprof.ex#L169" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Allows to programatically run the <code class="inline">cprof</code> profiler on expression in <code class="inline">fun</code>.</p>
<h2 id="profile/2-options" class="section-heading">
<a href="#profile/2-options" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Options
</h2>
<ul>
<li><code class="inline">:matching</code> - only profile calls matching the given pattern in form of
<code class="inline">{module, function, arity}</code>, where each element may be replaced by <code class="inline">:_</code>
to allow any value
</li>
<li><code class="inline">:limit</code> - filters out any results with a call count less than the limit
</li>
<li><code class="inline">:module</code> - filters out any results not pertaining to the given module
</li>
</ul>
</section>
</div>
<div class="detail" id="run/1">
<div class="detail-header">
<a href="#run/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">run(args)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/tasks/profile.cprof.ex#L115" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>A task needs to implement <code class="inline">run</code> which receives
a list of command line args.</p>
<p>Callback implementation for <a href="Mix.Task.html#c:run/1"><code class="inline">Mix.Task.run/1</code></a>.</p>
</section>
</div>
</section>
<footer class="footer">
<p>
<span class="line">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener">ExDoc</a> (v0.19.1),
</span>
<span class="line">
designed by
<a href="https://twitter.com/dignifiedquire" target="_blank" rel="noopener" title="@dignifiedquire">Friedel Ziegelmayer</a>.
</span>
</p>
</footer>
</div>
</div>
</section>
</div>
<script src="dist/app-a0c90688fa.js"></script>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
016232f1d9a3f7bee85855d35a2bca58
>
files
>
251
