forked from huiqing/percept2
/
percept2_sampling.html
executable file
·127 lines (105 loc) · 7.74 KB
/
percept2_sampling.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
<!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>
<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="#sample-3">sample/3</a></td><td>Start the profiler and collects information about the system.</td></tr>
<tr><td valign="top"><a href="#sample-4">sample/4</a></td><td>Start the profiler and collects information about the system.</td></tr>
<tr><td valign="top"><a href="#sample-5">sample/5</a></td><td>Start the profiler and collects information about the system.</td></tr>
</table>
<h2><a name="functions">Function Details</a></h2>
<h3 class="function"><a name="sample-3">sample/3</a></h3>
<div class="spec">
<p><tt>sample(Items::[any()], 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>) -> 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><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 intervals, which is 100 milliseconds.</p>
<p><code>OutDir</code> tells the profiler 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 could be
<code>sample_A.dat</code>. Profiling data is formatted in the 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. To use the
one of the pre-defined plotting scripts to viusalise the data collected, the following steps
can be followed. We assume Gnuplot is already installed, otherwise install it first.</p>
<p>1) start the Gnuplot tool.</p>
<p>2) in gnuplot, go to the <code>OutDir</code> directory, in which the data files are stored.</p>
<p>3) load the corresponding gnuplot script for the data to be visualised. For
example, to visualise the memory usage data in file <code>sample_mem_info.dat</code>,
the gnuplot script to load is <code>/path/to/sample_mem_info.plt</code>. The snapshot
next shows an example output the memory usage graph.</p>
<img src="percept2_sample_mem.png" alt="the front page of Percept2" width="850" height="500"> </p>
<h3 class="function"><a name="sample-4">sample/4</a></h3>
<div class="spec">
<p><tt>sample(Items::[any()], EntryOrTime::<a href="#type-entry_mfa">entry_mfa()</a> | <a href="#type-milliseconds">milliseconds()</a>, TimeInterval::<a href="#type-milliseconds">milliseconds()</a>, OutDir::<a href="file.html#type-filename">file:filename()</a>) -> ok</tt><br></p>
</div><p><p>Start the profiler and collects information about the system.</p>
Different from <a href="percept2_sampling.html#sample-2">sample/2</a>,
the function allows the user to specify the time interval.</p>
<h3 class="function"><a name="sample-5">sample/5</a></h3>
<div class="spec">
<p><tt>sample(Items::[any()], EntryOrTime::<a href="#type-entry_mfa">entry_mfa()</a> | <a href="#type-milliseconds">milliseconds()</a>, TimeInterval::<a href="#type-milliseconds">milliseconds()</a>, FilterFun::fun((term()) -> boolean()), OutDir::<a href="file.html#type-filename">file:filename()</a>) -> 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#sample-2">sample/2</a>.</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, Sep 24 2012, 11:08:26.</i></p>
</body>
</html>