/usr/share/doc/simgrid/html/tracing.html is in simgrid-doc 3.10-7.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>SimGrid: Tracing Simulations</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="stylesheet.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">SimGrid
 <span id="projectnumber">3.10</span>
</div>
<div id="projectbrief">Versatile Simulation of Distributed Systems</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="http://simgrid.gforge.inria.fr/"><span>Home page</span></a></li>
<li><a href="http://simgrid.gforge.inria.fr/documentation.html"><span>Online documentation</span></a></li>
<li><a href="https://gforge.inria.fr/projects/simgrid"><span>Dev's Corner</span></a></li>
<li> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.2 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('tracing.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Tracing Simulations </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Tracing is widely used to observe and understand the behavior of parallel applications and distributed algorithms. Usually, this is done in a two-step fashion: the user instruments the application and the traces are analyzed after the end of the execution. The analysis can highlights unexpected behaviors, bottlenecks and sometimes can be used to correct distributed algorithms. The SimGrid team has instrumented the library in order to let users trace their simulations and analyze them. This part of the user manual explains how the tracing-related features can be enabled and used during the development of simulators using the SimGrid library.</p>
<h1><a class="anchor" id="tracing_tracing_enabling"></a>
Enabling using CMake</h1>
<p>With the sources of SimGrid, it is possible to enable the tracing using the parameter <b>-Denable_tracing=ON</b> when the cmake is executed. The sections <a class="el" href="tracing.html#instr_category_functions">Tracing categories functions</a>, <a class="el" href="tracing.html#instr_mark_functions">Tracing marks functions</a>, and <a class="el" href="tracing.html#instr_uservariables_functions">Tracing user variables functions</a> describe all the functions available when this Cmake options is activated. These functions will have no effect if SimGrid is configured without this option (they are wiped-out by the C-preprocessor).</p>
<pre class="fragment">$ cmake -Denable_tracing=ON .
$ make
</pre><h1><a class="anchor" id="instr_category_functions"></a>
Tracing categories functions</h1>
<p>The SimGrid library is instrumented so users can trace the platform utilization using MSG, SimDAG and SMPI interfaces. It registers how much power is used for each host and how much bandwidth is used for each link of the platform. The idea with this type of tracing is to observe the overall view of resources utilization in the first place, especially the identification of bottlenecks, load-balancing among hosts, and so on.</p>
<p>Another possibility is to trace resource utilization by categories. Categorized resource utilization tracing gives SimGrid users to possibility to classify MSG and SimDAG tasks by category, tracing resource utilization for each of the categories. The functions below let the user declare a category and apply it to tasks. <em>The tasks that are not classified according to a category are not traced</em>. Even if the user does not specify any category, the simulations can still be traced in terms of resource utilization by using a special parameter that is detailed below (see section <a class="el" href="tracing.html#tracing_tracing_options">Tracing configuration Options</a>).</p>
<ul>
<li><code><a class="el" href="group__TRACE__category.html#ga2c341df9553b432c507d4ab2a87e8685" title="Declare a new category with a random color.">TRACE_category(const char *category)</a></code> </li>
<li><code><a class="el" href="group__TRACE__category.html#ga5abe9661fe1a1382c9be63984fea6931" title="Declare a new category with a color.">TRACE_category_with_color(const char *category, const char *color)</a></code> </li>
<li><code><a class="el" href="group__msg__task__usage.html#gaff6a660d1f3a37ff7ee3daee0e3ae3b7" title="Sets the tracing category of a task.">MSG_task_set_category(msg_task_t task, const char *category)</a></code> </li>
<li><code><a class="el" href="group__msg__task__usage.html#ga4d8a840bc4a7f1b28ba351069de9b9c3" title="Gets the current tracing category of a task.">MSG_task_get_category(msg_task_t task)</a></code> </li>
<li><code>SD_task_set_category(SD_task_t task, const char *category)</code> </li>
<li><code>SD_task_get_category(SD_task_t task)</code> </li>
</ul>
<h1><a class="anchor" id="instr_mark_functions"></a>
Tracing marks functions</h1>
<ul>
<li><code><a class="el" href="group__TRACE__mark.html#gacd215a0072a5d4ec7c5b11610b7bef20" title="Declare a new type for tracing mark.">TRACE_declare_mark(const char *mark_type)</a></code> </li>
<li><code><a class="el" href="group__TRACE__mark.html#gac8f263e9033090c2e73c7a2e2a98088a" title="Create a new instance of a tracing mark type.">TRACE_mark(const char *mark_type, const char *mark_value)</a></code> </li>
</ul>
<h1><a class="anchor" id="instr_uservariables_functions"></a>
Tracing user variables functions</h1>
<p>For hosts:</p>
<ul>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga1672865b1bc48cff5bdb759edf0a7c90" title="Declare a new user variable associated to hosts.">TRACE_host_variable_declare(const char *variable)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gaacaaa40fa93265cc87dc804edb6a61b3" title="Declare a new user variable associated to hosts with a color.">TRACE_host_variable_declare_with_color(const char *variable, const char *color)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga650d08f8e0547ffe3d3c5a6a6ceebcdf" title="Set the value of a variable of a host.">TRACE_host_variable_set(const char *host, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gae0a8625485d9cffc5c12676b65cd959c" title="Add a value to a variable of a host.">TRACE_host_variable_add(const char *host, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga287fcd04c563ff2f795460850e4fc5d6" title="Subtract a value from a variable of a host.">TRACE_host_variable_sub(const char *host, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga3adacb71a4ab331c93efdf250f73cbfc" title="Set the value of a variable of a host at a given timestamp.">TRACE_host_variable_set_with_time(double time, const char *host, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gab6e7856a8181341e524cb4c9920c24ba" title="Add a value to a variable of a host at a given timestamp.">TRACE_host_variable_add_with_time(double time, const char *host, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gae9ab3b84945d21bd06529d6705471d65" title="Subtract a value from a variable of a host at a given timestamp.">TRACE_host_variable_sub_with_time(double time, const char *host, const char *variable, double value)</a></code> </li>
</ul>
<p>For links:</p>
<ul>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga0b79340b330704fc7f30596988ce937c" title="Declare a new user variable associated to links.">TRACE_link_variable_declare(const char *variable)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga1c3d1a22e56a7a9a2fa6e5e6feb7978e" title="Declare a new user variable associated to links with a color.">TRACE_link_variable_declare_with_color(const char *variable, const char *color)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga5a521dffa1a5705e9e65d77053ef0cfa" title="Set the value of a variable of a link.">TRACE_link_variable_set(const char *link, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gabbc55f2a3e25e49248be7d9b71f15cb8" title="Add a value to a variable of a link.">TRACE_link_variable_add(const char *link, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga009ecbc92025f7f2106386e5c8822e0b" title="Subtract a value from a variable of a link.">TRACE_link_variable_sub(const char *link, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gaccafa87e0e58f2f3e282a7d23e56d792" title="Set the value of a variable of a link at a given timestamp.">TRACE_link_variable_set_with_time(double time, const char *link, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga139bde27fec64c468d16b5231fc41118" title="Add a value to a variable of a link at a given timestamp.">TRACE_link_variable_add_with_time(double time, const char *link, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gae6b2b2b1f2ad80588d5b4eccb7d5ab6c" title="Subtract a value from a variable of a link at a given timestamp.">TRACE_link_variable_sub_with_time(double time, const char *link, const char *variable, double value)</a></code> </li>
</ul>
<p>For links, but use source and destination to get route:</p>
<ul>
<li><code><a class="el" href="group__TRACE__user__variables.html#gab93d0d4ffb907c4d4b43cdc53cbe4f8c" title="Set the value of the variable present in the links connecting source and destination.">TRACE_link_srcdst_variable_set(const char *src, const char *dst, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gae19a0f01ea6240ceaba534dab0f15919" title="Add a value to the variable present in the links connecting source and destination.">TRACE_link_srcdst_variable_add(const char *src, const char *dst, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#gaa0af1adaf2ee2e0ea3b045e8ef5c4edf" title="Subtract a value from the variable present in the links connecting source and destination.">TRACE_link_srcdst_variable_sub(const char *src, const char *dst, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga1abd4aeafd36e40fd2aa8f15566df013" title="Set the value of the variable present in the links connecting source and destination at a given times...">TRACE_link_srcdst_variable_set_with_time(double time, const char *src, const char *dst, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga0fec5f8d16e8d8ba4c82b2dba1ba6234" title="Add a value to the variable present in the links connecting source and destination at a given timesta...">TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value)</a></code> </li>
<li><code><a class="el" href="group__TRACE__user__variables.html#ga37278937e06f41f0a0b06b6b91bbdfa6" title="Subtract a value from the variable present in the links connecting source and destination at a given ...">TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value)</a></code> </li>
</ul>
<h1><a class="anchor" id="tracing_tracing_options"></a>
Tracing configuration Options</h1>
<p>To check which tracing options are available for your simulator, you can just run it with the option </p>
<pre class="fragment">--help-tracing </pre><p> to get a very detailed and updated explanation of each tracing parameter. These are some of the options accepted by the tracing system of SimGrid, you can use them by running your simulator with the <b>–cfg=</b> switch:</p>
<ul>
<li><b><code>tracing</code> </b>: Safe switch. It activates (or deactivates) the tracing system. No other tracing options take effect if this one is not activated. <pre class="fragment">--cfg=tracing:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/categorized</code> </b>: It activates the categorized resource utilization tracing. It should be enabled if tracing categories are used by this simulator. <pre class="fragment">--cfg=tracing/categorized:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/uncategorized</code> </b>: It activates the uncategorized resource utilization tracing. Use it if this simulator do not use tracing categories and resource use have to be traced. <pre class="fragment">--cfg=tracing/uncategorized:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/filename</code> </b>: A file with this name will be created to register the simulation. The file is in the Paje format and can be analyzed using Viva or Paje visualization tools. More information can be found in these webpages: <a href="http://github.com/schnorr/viva/">http://github.com/schnorr/viva/</a> <a href="http://github.com/schnorr/pajeng/">http://github.com/schnorr/pajeng/</a> <pre class="fragment">--cfg=tracing/filename:mytracefile.trace
</pre> If you do not provide this parameter, the trace file will be named simgrid.trace.</li>
</ul>
<ul>
<li><b><code>tracing/onelink_only</code> </b>: By default, the tracing system uses all routes in the platform file to re-create a "graph" of the platform and register it in the trace file. This option let the user tell the tracing system to use only the routes that are composed with just one link. <pre class="fragment">--cfg=tracing/onelink_only:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/smpi</code> </b>: This option only has effect if this simulator is SMPI-based. Traces the MPI interface and generates a trace that can be analyzed using Gantt-like visualizations. Every MPI function (implemented by SMPI) is transformed in a state, and point-to-point communications can be analyzed with arrows. <pre class="fragment">--cfg=tracing/smpi:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/smpi/group</code> </b>: This option only has effect if this simulator is SMPI-based. The processes are grouped by the hosts where they were executed. <pre class="fragment">--cfg=tracing/smpi/group:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/smpi/computing</code> </b>: This option only has effect if this simulator is SMPI-based. The parts external to SMPI are also outputted to the trace. Provides better way to analyze the data automatically. <pre class="fragment">--cfg=tracing/smpi/computing:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/smpi/internals</code> </b>: This option only has effect if this simulator is SMPI-based. Display internal communications happening during a collective MPI call. <pre class="fragment">--cfg=tracing/smpi/internals:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/smpi/display_sizes</code> </b>: This option only has effect if this simulator is SMPI-based. Display the sizes of the messages exchanged in the trace, both in the links and on the states. For collective, size means the global size of data sent by the process in general. <pre class="fragment">--cfg=tracing/smpi/display_sizes:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/msg/process</code> </b>: This option only has effect if this simulator is MSG-based. It traces the behavior of all categorized MSG processes, grouping them by hosts. This option can be used to track process location if this simulator has process migration. <pre class="fragment">--cfg=tracing/msg/process:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/buffer</code> </b>: This option put some events in a time-ordered buffer using the insertion sort algorithm. The process of acquiring and releasing locks to access this buffer and the cost of the sorting algorithm make this process slow. The simulator performance can be severely impacted if this option is activated, but you are sure to get a trace file with events sorted. <pre class="fragment">--cfg=tracing/buffer:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/onelink_only</code> </b>: This option changes the way SimGrid register its platform on the trace file. Normally, the tracing considers all routes (no matter their size) on the platform file to re-create the resource topology. If this option is activated, only the routes with one link are used to register the topology within an AS. Routes among AS continue to be traced as usual. <pre class="fragment">--cfg=tracing/onelink_only:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/disable_destroy</code> </b>: Disable the destruction of containers at the end of simulation. This can be used with simulators that have a different notion of time (different from the simulated time). <pre class="fragment">--cfg=tracing/disable_destroy:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/basic</code> </b>: Some visualization tools are not able to parse correctly the Paje file format. Use this option if you are using one of these tools to visualize the simulation trace. Keep in mind that the trace might be incomplete, without all the information that would be registered otherwise. <pre class="fragment">--cfg=tracing/basic:yes
</pre></li>
</ul>
<ul>
<li><b><code>tracing/comment</code> </b>: Use this to add a comment line to the top of the trace file. <pre class="fragment">--cfg=tracing/comment:my_string
</pre></li>
</ul>
<ul>
<li><b><code>tracing/comment_file</code> </b>: Use this to add the contents of a file to the top of the trace file as comment. <pre class="fragment">--cfg=tracing/comment_file:textual_file.txt
</pre></li>
</ul>
<ul>
<li><b><code>viva/categorized</code> </b>: This option generates a graph configuration file for Viva considering categorized resource utilization. <pre class="fragment">--cfg=viva/categorized:graph_categorized.plist
</pre></li>
</ul>
<ul>
<li><b><code>viva/uncategorized</code> </b>: This option generates a graph configuration file for Viva considering uncategorized resource utilization. <pre class="fragment">--cfg=viva/uncategorized:graph_uncategorized.plist
</pre></li>
</ul>
<p>Please pass </p>
<pre class="fragment">--help-tracing </pre><p> to your simulator for the updated list of tracing options.</p>
<h1><a class="anchor" id="tracing_tracing_example_parameters"></a>
Case studies</h1>
<p>Some scenarios that might help you decide which tracing options you should use to analyze your simulator.</p>
<ul>
<li>I want to trace the resource utilization of all hosts and links of the platform, and my simulator <b>does not</b> use the tracing API. For that, you can run a uncategorized trace with the following parameters (it will work with <b>any</b> Simgrid simulator): <pre class="fragment">./your_simulator \
--cfg=tracing:yes \
--cfg=tracing/uncategorized:yes \
--cfg=tracing/filename:mytracefile.trace \
--cfg=viva/uncategorized:uncat.plist
</pre></li>
</ul>
<ul>
<li>I want to trace only a subset of my MSG (or SimDAG) tasks. For that, you will need to create tracing categories using the <b>TRACE_category (...)</b> function (as explained above), and then classify your tasks to a previously declared category using the <b>MSG_task_set_category (...)</b> (or <b>SD_task_set_category (...)</b> for SimDAG tasks). After recompiling, run your simulator with the following parameters: <pre class="fragment">./your_simulator \
--cfg=tracing:yes \
--cfg=tracing/categorized:yes \
--cfg=tracing/filename:mytracefile.trace \
--cfg=viva/categorized:cat.plist
</pre></li>
</ul>
<h1><a class="anchor" id="tracing_tracing_example"></a>
Example of Instrumentation</h1>
<p>A simplified example using the tracing mandatory functions.</p>
<pre class="fragment">int main (int argc, char **argv)
{
MSG_init (&argc, &argv);
//(... after deployment ...)
//note that category declaration must be called after MSG_create_environment
TRACE_category_with_color ("request", "1 0 0");
TRACE_category_with_color ("computation", "0.3 1 0.4");
TRACE_category ("finalize");
msg_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
msg_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
msg_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
msg_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
MSG_task_set_category (req1, "request");
MSG_task_set_category (req2, "request");
MSG_task_set_category (req3, "request");
MSG_task_set_category (req4, "request");
msg_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
MSG_task_set_category (comp, "computation");
msg_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
MSG_task_set_category (finalize, "finalize");
//(...)
MSG_clean();
return 0;
}
</pre><h1><a class="anchor" id="tracing_tracing_analyzing"></a>
Analyzing SimGrid Simulation Traces</h1>
<p>A SimGrid-based simulator, when executed with the correct parameters (see above) creates a trace file in the Paje file format holding the simulated behavior of the application or the platform. You have several options to analyze this trace file:</p>
<ul>
<li>Dump its contents to a CSV-like format using <code>pj_dump</code> (see <a href="https://github.com/schnorr/pajeng/wiki/pj_dump">PajeNG's wiki on pj_dump</a> and more generally the <a href="https://github.com/schnorr/pajeng/">PajeNG suite</a>) and use gnuplot to plot resource usage, time spent on blocking/executing functions, and so on. Filtering capabilities are at your hand by doing <code>grep</code>, with the best regular expression you can provide, to get only parts of the trace (for instance, only a subset of resources or processes).</li>
</ul>
<ul>
<li>Derive statistics from trace metrics (the ones built-in with any SimGrid simulation, but also those metrics you injected in the trace using the TRACE module) using the <a href="http://www.r-project.org/">R project</a> and all its modules. You can also combine R with <a href="http://ggplot2.org/">ggplot2</a> to get a number of high quality plots from your simulation metrics. You need to <code>pj_dump</code> the contents of the SimGrid trace file to use R.</li>
</ul>
<ul>
<li>Visualize the behavior of your simulation using classic space/time views (gantt-charts) provided by the <a href="https://github.com/schnorr/pajeng/">PajeNG suite</a> and any other tool that supports the <a href="http://paje.sourceforge.net/download/publication/lang-paje.pdf">Paje file format</a>. Consider this option if you need to understand the causality of your distributed simulation.</li>
</ul>
<ul>
<li>Visualize the behavior of your simulation with treemaps (specially if your simulation has a platform with several thousand resources), provided by the <a href="http://github.com/schnorr/viva/">Viva</a> visualization tool. See <a href="https://github.com/schnorr/viva/wiki">Viva's wiki</a> for further details on what is a treemap and how to use it.</li>
</ul>
<ul>
<li>Correlate the behavior of your simulator with the platform topology with an interactive, force-directed, and hierarchical graph visualization, provided by <a href="http://github.com/schnorr/viva/">Viva</a>. Check <a href="https://github.com/schnorr/viva/wiki">Viva's wiki</a> for further details. This <a href="http://hal.inria.fr/hal-00738321/">research report</a>, published at ISPASS 2013, has a detailed description of this visualization technique.</li>
</ul>
<ul>
<li>You can also check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html">tutorial section</a> that contains a dedicated tutorial with several suggestions on how to use the tracing infrastructure. Look for the SimGrid User::Visualization 101 tutorial.</li>
</ul>
<ul>
<li>Ask for help on the <a href="#" onclick="location.href='mai'+'lto:'+'sim'+'gr'+'id-'+'us'+'er@'+'li'+'sts'+'.g'+'for'+'ge'+'.in'+'ri'+'a.f'+'r'; return false;">simgrid-user@lists.gforge.inria.fr</a> mailing list, giving us a detailed explanation on what your simulator does and what kind of information you want to trace. You can also check the <a href="http://lists.gforge.inria.fr/pipermail/simgrid-user/">mailing list archive</a> for old messages regarding tracing and analysis.</li>
</ul>
<h2><a class="anchor" id="tracing_viva_analysis"></a>
Viva Visualization Tool</h2>
<p>This subsection describe some of the concepts regarding the <a href="http://github.com/schnorr/viva/">Viva Visualization Tool</a> and its relation with SimGrid traces. You should refer to Viva's website for further details on all its visualization techniques.</p>
<h3><a class="anchor" id="tracing_viva_time_slice"></a>
Time Slice</h3>
<p>The analysis of a trace file using the tool always takes into account the concept of the <em>time-slice</em>. This concept means that what is being visualized in the screen is always calculated considering a specific time frame, with its beggining and end timestamp. The time-slice is configured by the user and can be changed dynamically through the window called <em>Time Interval</em> that is opened whenever a trace file is being analyzed. Users are capable to select the beggining and size of the time slice.</p>
<h3><a class="anchor" id="tracing_viva_graph"></a>
Hierarchical Graph View</h3>
<p>As stated above (see section <a class="el" href="tracing.html#tracing_tracing_analyzing">Analyzing SimGrid Simulation Traces</a>), one possibility to analyze SimGrid traces is to use Viva's graph view with a graph configuration to customize the graph according to the traces. A valid graph configuration (we are using the non-XML <a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to describe the configuration) can be created for any SimGrid-based simulator using the <em>–cfg=viva/uncategorized:graph_uncategorized.plist</em> or <em>–cfg=viva/categorized:graph_categorized.plist</em> (if the simulator defines resource utilization categories) when executing the simulation.</p>
<h3><a class="anchor" id="basic_conf"></a>
Basic Graph Configuration</h3>
<p>The basic description of the configuration is as follows: </p>
<pre class="fragment">{
node = (LINK, HOST, );
edge = (HOST-LINK, LINK-HOST, LINK-LINK, );
</pre><p>The nodes of the graph will be created based on the <em>node</em> parameter, which in this case is the different <em>"HOST"</em>s and <em>"LINK"</em>s of the platform used to simulate. The <em>edge</em> parameter indicates that the edges of the graph will be created based on the <em>"HOST-LINK"</em>s, <em>"LINK-HOST"</em>s, and <em>"LINK-LINK"</em>s of the platform. After the definition of these two parameters, the configuration must detail how the nodes (<em>HOST</em>s and <em>LINK</em>s) should be drawn.</p>
<p>For that, the configuration must have an entry for each of the types used. For <em>HOST</em>, as basic configuration, we have:</p>
<pre class="fragment"> HOST = {
type = square;
size = power;
values = (power_used);
};
</pre><p>The parameter <em>size</em> indicates which variable from the trace file will be used to define the size of the node HOST in the visualization. If the simulation was executed with availability traces, the size of the nodes will be changed according to these traces. The parameter <em>type</em> indicates which geometrical shape will be used to represent HOST, and the <em>values</em> parameter indicates which values from the trace will be used to fill the shape.</p>
<p>For <em>LINK</em> we have:</p>
<pre class="fragment"> LINK = {
type = rhombus;
size = bandwidth;
values = (bandwidth_used);
};
}
</pre><p>The same configuration parameters are used here: <em>type</em> (with a rhombus), the <em>size</em> (whose value is from trace's bandwidth variable) and the <em>values</em>.</p>
<h3><a class="anchor" id="custom_graph"></a>
Customizing the Graph Representation</h3>
<p>Viva is capable to handle a customized graph representation based on the variables present in the trace file. In the case of SimGrid, every time a category is created for tasks, two variables in the trace file are defined: one to indicate node utilization (how much power was used by that task category), and another to indicate link utilization (how much bandwidth was used by that category). For instance, if the user declares a category named <em>request</em>, there will be variables named <b>p</b><em>request</em> and a <b>b</b><em>request</em> (<b>p</b> for power and <b>b</b> for bandwidth). It is important to notice that the variable <em>prequest</em> in this case is only available for HOST, and <em>brequest</em> is only available for LINK. <b>Example</b>: suppose there are two categories for tasks: request and compute. To create a customized graph representation with a proportional separation of host and link utilization, use as configuration for HOST and LINK this:</p>
<pre class="fragment"> HOST = {
type = square;
size = power;
values = (prequest, pcomputation);
};
LINK = {
type = rhombus;
size = bandwidth;
values = (brequest, bcomputation);
};
</pre><p>This configuration enables the analysis of resource utilization by MSG tasks through the identification of load-balancing issues and network bottlenecks, for instance. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Sun Nov 17 2013 21:34:47 for SimGrid by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.1.2 </li>
</ul>
</div>
</body>
</html>
|