1 /*! \page tracing Tracing Simulations for Visualization
3 \htmlinclude .tracing.doc.toc
5 \section tracing_tracing Tracing Simulations for Visualization
7 The trace visualization is widely used to observe and understand the behavior
8 of parallel applications and distributed algorithms. Usually, this is done in a
9 two-step fashion: the user instruments the application and the traces are
10 analyzed after the end of the execution. The visualization itself can highlights
11 unexpected behaviors, bottlenecks and sometimes can be used to correct
12 distributed algorithms. The SimGrid team has instrumented the library
13 in order to let users trace their simulations and analyze them. This part of the
14 user manual explains how the tracing-related features can be enabled and used
15 during the development of simulators using the SimGrid library.
17 \subsection tracing_tracing_howitworks How it works
19 For now, the SimGrid library is instrumented so users can trace the <b>platform
20 utilization</b> using the MSG, SimDAG and SMPI interface. This means that the tracing will
21 register how much power is used for each host and how much bandwidth is used for
22 each link of the platform. The idea with this type of tracing is to observe the
23 overall view of resources utilization in the first place, especially the
24 identification of bottlenecks, load-balancing among hosts, and so on.
26 The idea of the tracing facilities is to give SimGrid users to possibility to
27 classify MSG and SimDAG tasks by category, tracing the platform utilization
28 (hosts and links) for each of the categories. For that,
29 the tracing interface enables the declaration of categories and a function to
30 mark a task with a previously declared category. <em>The tasks that are not
31 classified according to a category are not traced</em>. Even if the user
32 does not specify any category, the simulations can still be traced in terms
33 of resource utilization by using a special parameter that is detailed below.
35 \subsection tracing_tracing_enabling Enabling using CMake
37 With the sources of SimGrid, it is possible to enable the tracing
38 using the parameter <b>-Denable_tracing=ON</b> when the cmake is executed.
39 The section \ref tracing_tracing_functions describes all the functions available
40 when this Cmake options is activated. These functions will have no effect
41 if SimGrid is configured without this option (they are wiped-out by the
45 $ cmake -Denable_tracing=ON .
49 \subsection instr_category_functions Tracing categories functions
50 \li \c TRACE_category(const char *category)
51 \li \c TRACE_category_with_color(const char *category, const char *color)
52 \li \c MSG_task_set_category(m_task_t task, const char *category)
53 \li \c MSG_task_get_category(m_task_t task)
55 \li <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
56 This function should be called after the creation of a SimDAG task, to define the
57 category of that task. The first parameter \c task must contain a task that was
58 created with the function \c MSG_task_create. The second parameter
59 \c category must contain a category that was previously defined by the function
62 \subsection instr_mark_functions Tracing marks functions
63 \li \c TRACE_declare_mark(const char *mark_type)
64 \li \c TRACE_mark(const char *mark_type, const char *mark_value)
66 \subsection instr_uservariables_functions Tracing user variables functions
70 \li \c TRACE_host_variable_declare(const char *variable)
71 \li \c TRACE_host_variable_declare_with_color(const char *variable, const char *color)
72 \li \c TRACE_host_variable_set(const char *host, const char *variable, double value)
73 \li \c TRACE_host_variable_add(const char *host, const char *variable, double value)
74 \li \c TRACE_host_variable_sub(const char *host, const char *variable, double value)
75 \li \c TRACE_host_variable_set_with_time(double time, const char *host, const char *variable, double value)
76 \li \c TRACE_host_variable_add_with_time(double time, const char *host, const char *variable, double value)
77 \li \c TRACE_host_variable_sub_with_time(double time, const char *host, const char *variable, double value)
81 \li \c TRACE_link_variable_declare(const char *variable)
82 \li \c TRACE_link_variable_declare_with_color(const char *variable, const char *color)
83 \li \c TRACE_link_variable_set(const char *link, const char *variable, double value)
84 \li \c TRACE_link_variable_add(const char *link, const char *variable, double value)
85 \li \c TRACE_link_variable_sub(const char *link, const char *variable, double value)
86 \li \c TRACE_link_variable_set_with_time(double time, const char *link, const char *variable, double value)
87 \li \c TRACE_link_variable_add_with_time(double time, const char *link, const char *variable, double value)
88 \li \c TRACE_link_variable_sub_with_time(double time, const char *link, const char *variable, double value)
90 For links, but use source and destination to get route:
92 \li \c TRACE_link_srcdst_variable_set(const char *src, const char *dst, const char *variable, double value)
93 \li \c TRACE_link_srcdst_variable_add(const char *src, const char *dst, const char *variable, double value)
94 \li \c TRACE_link_srcdst_variable_sub(const char *src, const char *dst, const char *variable, double value)
95 \li \c TRACE_link_srcdst_variable_set_with_time(double time, const char *src, const char *dst, const char *variable, double value)
96 \li \c TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value)
97 \li \c TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value)
99 \subsection tracing_tracing_options Tracing configuration Options
101 To check which tracing options are available for your simulator, you
102 can just run it with the option <b>--help-tracing</b>. These are the
103 options accepted by the tracing system of SimGrid as of today, you
104 can use them by running your simulator with the <b>--cfg=</b> switch:
109 Safe switch. It activates (or deactivates) the tracing system.
110 No other tracing options take effect if this one is not activated.
118 It activates the categorized resource utilization tracing. It should
119 be enabled if tracing categories are used by this simulator.
121 --cfg=tracing/categorized:1
125 tracing/uncategorized
127 It activates the uncategorized resource utilization tracing. Use it if
128 this simulator do not use tracing categories and resource use have to be
131 --cfg=tracing/uncategorized:1
137 A file with this name will be created to register the simulation. The file
138 is in the Paje format and can be analyzed using Triva or Paje visualization
139 tools. More information can be found in these webpages:
140 <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
141 <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
143 --cfg=tracing/filename:mytracefile.trace
145 If you do not provide this parameter, the trace file will be named simgrid.trace.
150 By default, the tracing system uses all routes in the platform file
151 to re-create a "graph" of the platform and register it in the trace file.
152 This option let the user tell the tracing system to use only the routes
153 that are composed with just one link.
155 --cfg=tracing/onelink_only:1
161 This option only has effect if this simulator is SMPI-based. Traces the MPI
162 interface and generates a trace that can be analyzed using Gantt-like
163 visualizations. Every MPI function (implemented by SMPI) is transformed in a
164 state, and point-to-point communications can be analyzed with arrows.
172 This option only has effect if this simulator is SMPI-based. The processes
173 are grouped by the hosts where they were executed.
175 --cfg=tracing/smpi/group:1
181 This option only has effect if this simulator is MSG-based. It traces the
182 behavior of all categorized MSG processes, grouping them by hosts. This option
183 can be used to track process location if this simulator has process migration.
185 --cfg=tracing/msg/process:1
191 This option put some events in a time-ordered buffer using the
192 insertion sort algorithm. The process of acquiring and releasing
193 locks to access this buffer and the cost of the sorting algorithm
194 make this process slow. The simulator performance can be severely
195 impacted if this option is activated, but you are sure to get a trace
196 file with events sorted.
198 --cfg=tracing/buffer:1
204 This option changes the way SimGrid register its platform on the trace
205 file. Normally, the tracing considers all routes (no matter their
206 size) on the platform file to re-create the resource topology. If this
207 option is activated, only the routes with one link are used to
208 register the topology within an AS. Routes among AS continue to be
211 --cfg=tracing/onelink_only:1
215 tracing/disable_destroy
217 Disable the destruction of containers at the end of simulation. This
218 can be used with simulators that have a different notion of time
219 (different from the simulated time).
221 --cfg=tracing/disable_destroy:1
227 This option generates a graph configuration file for Triva considering
228 categorized resource utilization.
230 --cfg=triva/categorized:graph_categorized.plist
236 This option generates a graph configuration file for Triva considering
237 uncategorized resource utilization.
239 --cfg=triva/uncategorized:graph_uncategorized.plist
242 \subsection tracing_tracing_example_parameters Case studies
244 Some scenarios that might help you decide which tracing options
245 you should use to analyze your simulator.
247 \li I want to trace the resource utilization of all hosts
248 and links of the platform, and my simulator <b>does not</b> use
249 the tracing API. For that, you can run a uncategorized trace
250 with the following parameters (it will work with <b>any</b> Simgrid
255 --cfg=tracing/uncategorized:1 \
256 --cfg=tracing/filename:mytracefile.trace \
257 --cfg=triva/uncategorized:uncat.plist
260 \li I want to trace only a subset of my MSG (or SimDAG) tasks.
261 For that, you will need to create tracing categories using the
262 <b>TRACE_category (...)</b> function (as explained above),
263 and then classify your tasks to a previously declared category
264 using the <b>TRACE_msg_set_task_category (...)</b>
265 (or <b>TRACE_sd_set_task_category (...)</b> for SimDAG tasks). After
266 recompiling, run your simulator with the following parameters:
270 --cfg=tracing/categorized:1 \
271 --cfg=tracing/filename:mytracefile.trace \
272 --cfg=triva/categorized:cat.plist
276 \subsection tracing_tracing_example Example of Instrumentation
278 A simplified example using the tracing mandatory functions.
281 int main (int argc, char **argv)
283 MSG_global_init (&argc, &argv);
285 //(... after deployment ...)
287 //note that category declaration must be called after MSG_create_environment
288 TRACE_category_with_color ("request", "1 0 0");
289 TRACE_category_with_color ("computation", "0.3 1 0.4");
290 TRACE_category ("finalize");
292 m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
293 m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
294 m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
295 m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
296 TRACE_msg_set_task_category (req1, "request");
297 TRACE_msg_set_task_category (req2, "request");
298 TRACE_msg_set_task_category (req3, "request");
299 TRACE_msg_set_task_category (req4, "request");
301 m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
302 TRACE_msg_set_task_category (comp, "computation");
304 m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
305 TRACE_msg_set_task_category (finalize, "finalize");
314 \subsection tracing_tracing_analyzing Analyzing the SimGrid Traces
316 The SimGrid library, during an instrumented simulation, creates a trace file in
317 the Paje file format that contains the platform utilization for the simulation
318 that was executed. The visualization analysis of this file is performed with the
319 visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
320 special configurations tunned to SimGrid needs. This part of the documentation
321 explains how to configure and use Triva to analyse a SimGrid trace file.
323 - <b>Installing Triva</b>: the tool is available in the Inria's Forge,
324 at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
325 Use the following command to get the sources, and then check the file
326 <i>INSTALL</i>. This file contains instructions to install
327 the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
328 be compiled in MacOSX natively, check <i>INSTALL.mac</i> file.
330 $ git clone git://scm.gforge.inria.fr/triva/triva.git
335 - <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
336 installation (you can execute it passing <em>--help</em> to check its
337 options). If the triva binary is not available after following the
338 installation instructions, you may want to execute the following command to
339 initialize the GNUstep environment variables. We strongly recommend that you
340 use the latest GNUstep packages, and not the packages available through apt-get
341 in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
342 available packages, you can execute this command:
344 $ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
346 You should be able to see this output after the installation of triva:
348 $ ./Triva.app/Triva --help
349 Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
350 Trace Analysis through Visualization
353 --ti_frequency {double} Animation: frequency of updates
354 --ti_hide Hide the TimeInterval window
355 --ti_forward {double} Animation: value to move time-slice
356 --ti_apply Apply the configuration
357 --ti_update Update on slider change
358 --ti_animate Start animation
359 --ti_start {double} Start of time slice
360 --ti_size {double} Size of time slice
362 --comparison Compare Trace Files (Experimental)
363 --graph Configurable Graph
364 --list Print Trace Type Hierarchy
365 --hierarchy Export Trace Type Hierarchy (dot)
366 --stat Trace Statistics and Memory Utilization
367 --instances List All Trace Entities
368 --linkview Link View (Experimental)
369 --treemap Squarified Treemap
370 --merge Merge Trace Files (Experimental)
371 --check Check Trace File Integrity
373 --gc_conf {file} Graph Configuration in Property List Format
374 --gc_apply Apply the configuration
375 --gc_hide Hide the GraphConfiguration window
377 Triva expects that the user choose one of the available options
378 (currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
379 and the trace file from the simulation.
381 - <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
382 the tool always takes into account the concept of the <em>time-slice</em>.
383 This concept means that what is being visualized in the screen is always
384 calculated considering a specific time frame, with its beggining and end
385 timestamp. The time-slice is configured by the user and can be changed
386 dynamically through the window called <em>Time Interval</em> that is opened
387 whenever a trace file is being analyzed. The next figure depicts the time-slice
388 configuration window.
389 In the top of the window, in the space named <i>Trace Time</i>,
390 the two fields show the beggining of the trace (which usually starts in 0) and
391 the end (that depends on the time simulated by SimGrid). The middle of the
392 window, in the square named <i>Time Slice Configuration</i>, contains the
393 aspects related to the time-slice, including its <i>start</i> and its
394 <i>size</i>. The gray rectangle in the bottom of this part indicates the
395 <i>current time-slice</i> that is considered for the drawings. If the checkbox
396 <i>Update Drawings on Sliders Change</i> is not selected, the button
397 <i>Apply</i> must be clicked in order to inform triva that the
398 new time-slice must be considered. The bottom part of the window, in the space
399 indicated by the square <i>Time Slice Animation</i> can be used to advance
400 the time-frame automatically. The user configures the amount of time that the
401 time-frame will forward and how frequent this update will happen. Once this is
402 configured, the user clicks the <i>Play</i> button in order to see the dynamic
403 changes on the drawings.
406 <a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
409 <b>Remarks:</b> when the trace has too many hosts or links, the computation to
410 take into account a new time-slice can be expensive. When this happens, the
411 <i>Frequency</i> parameter, but also updates caused by change on configurations
412 when the checkbox <i>Update Drawings on Sliders
413 Change</i> is selected will not be followed.
415 - <b>Understanding Triva - graph</b>: one possibility to analyze
416 SimGrid traces is to use Triva's graph view, using the
417 <em>--graph</em> parameter to activate this view, and
418 <em>--gc_conf</em> with a graph configuration to customize the graph
419 according to the traces. A valid graph configuration (we are using
421 href="http://en.wikipedia.org/wiki/Property_list">Property List
422 Format</a> to describe the configuration) can be created for any
423 SimGrid-based simulator using the
424 <em>--cfg=triva/uncategorized:graph_uncategorized.plist</em> or
425 <em>--cfg=triva/categorized:graph_categorized.plist</em> (if the
426 simulator defines resource utilization categories) when executing
429 <b>Basic SimGrid Configuration</b>: The basic description of the configuration
433 node = (LINK, HOST, );
434 edge = (HOST-LINK, LINK-HOST, LINK-LINK, );
437 The nodes of the graph will be created based on the <i>node</i>
438 parameter, which in this case is the different <em>"HOST"</em>s and
439 <em>"LINK"</em>s of the platform used to simulate. The <i>edge</i>
440 parameter indicates that the edges of the graph will be created based
441 on the <em>"HOST-LINK"</em>s, <em>"LINK-HOST"</em>s, and
442 <em>"LINK-LINK"</em>s of the platform. After the definition of these
443 two parameters, the configuration must detail how the nodes
444 (<em>HOST</em>s and <em>LINK</em>s) should be drawn.
446 For that, the configuration must have an entry for each of
447 the types used. For <em>HOST</em>, as basic configuration, we have:
453 values = (power_used);
457 The parameter <em>size</em> indicates which variable from the trace
458 file will be used to define the size of the node HOST in the
459 visualization. If the simulation was executed with availability
460 traces, the size of the nodes will be changed according to these
461 traces. The parameter <em>type</em> indicates which geometrical shape
462 will be used to represent HOST, and the <em>values</em> parameter
463 indicates which values from the trace will be used to fill the shape.
465 For <em>LINK</em> we have:
471 values = (bandwidth_used);
476 The same configuration parameters are used here: <em>type</em> (with a
477 rhombus), the <em>size</em> (whose value is from trace's bandwidth
478 variable) and the <em>values</em>.
480 <b>Customizing the Graph Representation</b>: triva is capable to handle
481 a customized graph representation based on the variables present in the trace
482 file. In the case of SimGrid, every time a category is created for tasks, two
483 variables in the trace file are defined: one to indicate node utilization (how
484 much power was used by that task category), and another to indicate link
485 utilization (how much bandwidth was used by that category). For instance, if the
486 user declares a category named <i>request</i>, there will be variables named
487 <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
488 <b>b</b> for bandwidth). It is important to notice that the variable
489 <i>prequest</i> in this case is only available for HOST, and
490 <i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
491 two categories for tasks: request and compute. To create a customized graph
492 representation with a proportional separation of host and link utilization, use
493 as configuration for HOST and LINK this:
499 values = (prequest, pcomputation);
504 values = (brequest, bcomputation);
508 This configuration enables the analysis of resource utilization by MSG tasks,
509 and the identification of load-balancing issues, network bottlenecks, for
512 <b>The Graph Visualization</b>: The next figure shows a graph visualization of a
513 given time-slice of the masterslave_forwarder example (present in the SimGrid
514 sources). The red color indicates tasks from the <i>compute</i> category. This
515 visualization was generated with the following configuration:
519 node = (LINK, HOST, );
520 edge = (HOST-LINK, LINK-HOST, LINK-LINK, );
525 values = (pcompute, pfinalize);
530 values = (bcompute, bfinalize);
537 <a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
541 - <b>Understading Triva - colors</b>: Colors are now registered in
542 trace files. See the tracing API to how to define them for your