doc/percept2_sampling.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Module percept2_sampling</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
</head>
<body bgcolor="white">
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<hr>

<h1>Module percept2_sampling</h1>
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#types">Data Types</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>  
This module provides a collection of functions for reporting information  
regarding memory usage, garbage collection, scheduler utilization, and  
message/run queue length, etc.

<p><b>Authors:</b> Huiqing Li (<a href="mailto:H.Li@kent.ac.uk"><tt>H.Li@kent.ac.uk</tt></a>).</p>

<h2><a name="description">Description</a></h2><p>  
This module provides a collection of functions for reporting information  
regarding memory usage, garbage collection, scheduler utilization, and  
message/run queue length, etc. This is done by sampling-based profiling, i.e.  
the profiler probes the running Erlang system at regular intervals. Sampling  
profiling is typically less numerically accurate and specific, but has less  
impact on the system. Data collected by the profiler are stored in files,  
and the Gnuplot tool can be used for graph visualisation of the data.</p>
 
  The following Erlang functions are used for the purpose of data collection
  <a href="http://www.erlang.org/doc/man/erlang.html#statistics-1">erlang:statistics/1</a>,
  <a href="http://www.erlang.org/doc/man/erlang.html#memory-1">erlang:memory/1</a>,
  <a href="http://www.erlang.org/doc/man/erlang.html#system_info-1">erlang:system_info/1</a>
  and <a href="http://www.erlang.org/doc/man/erlang.html#process_info-2">erlang:process_info/1</a>.
<h2><a name="types">Data Types</a></h2>

<h3 class="typedecl"><a name="type-entry_mfa">entry_mfa()</a></h3>
<p><tt>entry_mfa() = {atom(), atom(), list()}</tt></p>


<h3 class="typedecl"><a name="type-milliseconds">milliseconds()</a></h3>
<p><tt>milliseconds() = non_neg_integer()</tt></p>


<h3 class="typedecl"><a name="type-regname">regname()</a></h3>
<p><tt>regname() = atom()</tt></p>


<h3 class="typedecl"><a name="type-sample_item">sample_item()</a></h3>
<p><tt>sample_item() = run_queue | run_queues | scheduler_utilisation | process_count | schedulers_online | mem_info | {message_queue_len, pid() | <a href="#type-regname">regname()</a>} | all</tt></p>
<p>  the 'all' options covers all the the options apart from 'message_queue_len'.</p>

<h3 class="typedecl"><a name="type-seconds">seconds()</a></h3>
<p><tt>seconds() = non_neg_integer()</tt></p>


<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#start-3">start/3</a></td><td>Start the profiler and collects information about the system.</td></tr>
<tr><td valign="top"><a href="#start-4">start/4</a></td><td>Start the profiler and collects information about the system.</td></tr>
<tr><td valign="top"><a href="#start-5">start/5</a></td><td>Start the profiler and collects information about the system.</td></tr>
<tr><td valign="top"><a href="#stop-0">stop/0</a></td><td>Stop the sampling.</td></tr>
</table>

<h2><a name="functions">Function Details</a></h2>

<h3 class="function"><a name="start-3">start/3</a></h3>
<div class="spec">
<p><tt>start(Items::[<a href="#type-sample_item">sample_item()</a>], EntryOrTime::<a href="#type-entry_mfa">entry_mfa()</a> | <a href="#type-milliseconds">milliseconds()</a>, OutDir::<a href="file.html#type-filename">file:filename()</a>) -&gt; ok</tt><br></p>
</div><p><p>Start the profiler and collects information about the system.</p>
 
  The type of information collected is specified by <code>Items</code>:
 <ul>
  <code>run_queue</code>: returns the sum length of all run queues, that is, the total number of processes that are ready to run.
 </ul>
 <ul>
  <code>run_queues</code>: returns the length of each run queue, that is, the number of processes that are ready to run in each run queue.
 </ul>
 <ul>
  <code>scheduler_utilisation</code>: returns the scheduler-utilisation rate per scheduler.
 </ul>
 <ul>
  <code>schedulers_online</code>: returns the amount of schedulers online.
 </ul>
 <ul>
  <code>process_count</code>: returns the number of processes currently existing at the local node as an integer.
 </ul>
 <ul>
  <code>mem_info</code>: returns information about memory dynamically allocated by the Erlang emulator. Information
  about the following memory types is collected:
  processes, ets, atom, code and binary. See <a href="http://www.erlang.org/doc/man/erlang.html#memory-1">erlang:memory/1</a>.
 </ul>
 <ul>
  <code>message_queue_len</code>: returns the number of messages currently in the message queue of the process.
 </ul>
 <ul>
  <code>all</code>:  this option covers all the above options apart from <code>message_queue_len</code>.
 </ul><p>
 If an entry function is specified, this function profiles the system
  for the whole duration until the entry function returns; otherwise it profiles
  the system for the time period specified. The system is probed at the default
  time interval, which is 10 milliseconds. It is also possible to stop the sampling
  manually using <a href="percept2_sampling.html#stop-0">stop/0</a>,</p>
 
  <p><code>OutDir</code> tells the tool where to put the data files generated. A data file is generated
  for each type of information in <code>Items</code>. For an item <code>A</code>, the name of the data file would be
  <code>sample_A.dat</code>.</p>
 
   <p>Sampling data is formatted in a way so that the graph plotting tool <code>Gnuplot</code>
   can be used for visualisation.  A pre-defined plotting script is available for
   each type of information collected, and these scripts are in the <code>percept2/gplt</code> directory.   
If you are familiar with Gnuplot, you could generate the diagrams in Gnuplot command-line.   
Alternately, you could visualise the sampling data through Percept2, which uses Gnuplot to   
generate the graphs behind the scene. (It is likely that we will get rid of the dependence to   
Gnuplot in the future).</p>
 
   <p>To visualise the sampling data, one could select the <code>Visualise sampling data</code> from the Percept2 main menu,   
and this should lead to a page as shown in the screenshot next.</p>
 
  <p><img src="percept2_sample.png" alt="Visualise sampling data" width="850" height="500"> </p>
 
  <p>In this page, select the type of data you would like to see, enter the data file name, and the
  path leading to this file, then click on the <code>Generate Graph</code> button. This should leads to a page showing  
the graph. The screenshot next shows an example output.</p>
 
   <img src="percept2_sample_mem.png" alt="the front page of Percept2" width="850" height="500"> 
 </p>

<h3 class="function"><a name="start-4">start/4</a></h3>
<div class="spec">
<p><tt>start(Items::[any()], EntryOrTime::<a href="#type-entry_mfa">entry_mfa()</a> | <a href="#type-seconds">seconds()</a>, TimeInterval::<a href="#type-milliseconds">milliseconds()</a>, OutDir::<a href="file.html#type-filename">file:filename()</a>) -&gt; ok</tt><br></p>
</div><p><p>Start the profiler and collects information about the system.</p>
 
  Different from <a href="percept2_sampling.html#start-3">start/3</a>,
  this function allows the user to specify the time interval.</p>

<h3 class="function"><a name="start-5">start/5</a></h3>
<div class="spec">
<p><tt>start(Items::[any()], EntryOrTime::<a href="#type-entry_mfa">entry_mfa()</a> | <a href="#type-seconds">seconds()</a>, TimeInterval::<a href="#type-milliseconds">milliseconds()</a>, FilterFun::fun((term()) -&gt; boolean()), OutDir::<a href="file.html#type-filename">file:filename()</a>) -&gt; ok</tt><br></p>
</div><p><p>Start the profiler and collects information about the system.</p>
 
  Apart from allowing the user to specify the time interval, this
  function also allows the user to supply a filter function, so that
  only those data that satisfy certain condition are logged.
  See <a href="percept2_sampling.html#start-3">start/3</a>.</p>

<h3 class="function"><a name="stop-0">stop/0</a></h3>
<div class="spec">
<p><tt>stop() -&gt; {error, not_started} | ok</tt><br></p>
</div><p>Stop the sampling.</p>
<hr>

<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<p><i>Generated by EDoc, Mar 28 2013, 21:53:01.</i></p>
</body>
</html>