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 tracing_tracing_functions Tracing Functions
51 \li <b>\c TRACE_category (const char *category)</b>: This function should be used
52 to define a user category. The category can be used to differentiate the tasks
53 that are created during the simulation (for example, tasks from server1,
54 server2, or request tasks, computation tasks, communication tasks).
55 All resource utilization (host power and link bandwidth) will be
56 classified according to the task category. Tasks that do not belong to a
57 category are not traced. The color for the category that is being declared
58 is random (use next function to specify a color).
60 \li <b>\c TRACE_category_with_color (const char *category, const char *color)</b>: Same
61 as TRACE_category, but let user specify a color encoded as a RGB-like string with
62 three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
63 color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
65 \li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
66 This function should be called after the creation of a MSG task, to define the
67 category of that task. The first parameter \c task must contain a task that was
68 created with the function \c MSG_task_create. The second parameter
69 \c category must contain a category that was previously defined by the function
72 \li <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
73 This function should be called after the creation of a SimDAG task, to define the
74 category of that task. The first parameter \c task must contain a task that was
75 created with the function \c MSG_task_create. The second parameter
76 \c category must contain a category that was previously defined by the function
79 \li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
80 Declare a user variable that will be associated to host/link. A variable can
81 be used to trace user variables such as the number of tasks in a server,
82 the number of clients in an application (for hosts), and so on.
84 \li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
85 Set the value of a given user variable for a given host/link. The value
86 of this variable is always associated to the host/link. The host/link
87 parameters should be its name as the one listed in the platform file.
89 \li <b>\c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value)</b>:
90 Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
91 the time used to trace it. Users can specify a time that is not the
92 simulated clock time as defined by the core simulator. This allows
93 a fine-grain control of time definition, but should be used with
94 caution since the trace can be inconsistent if resource utilization
95 traces are also traced.
97 \li <b>\c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value)</b>:
98 Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
99 destination hosts (as the names from the platform file). The tracing library
100 will get the corresponding route that connects those two hosts (src and dst) and
101 [set|add|sub] the value's variable for all the links of the route.
103 \li <b>\c TRACE_link_srcdst_variable_[set|add|sub]_with_time (double time, const char *src, const char *dst, const char *variable, double value)</b>:
104 Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
106 \subsection tracing_tracing_options Tracing configuration Options
108 To check which tracing options are available for your simulator, you
109 can just run it with the option <b>--help-tracing</b>. These are the
110 options accepted by the tracing system of SimGrid as of today, you
111 can use them by running your simulator with the <b>--cfg=</b> switch:
116 Safe switch. It activates (or deactivates) the tracing system.
117 No other tracing options take effect if this one is not activated.
125 It activates the categorized resource utilization tracing. It should
126 be enabled if tracing categories are used by this simulator.
128 --cfg=tracing/categorized:1
132 tracing/uncategorized
134 It activates the uncategorized resource utilization tracing. Use it if
135 this simulator do not use tracing categories and resource use have to be
138 --cfg=tracing/uncategorized:1
144 A file with this name will be created to register the simulation. The file
145 is in the Paje format and can be analyzed using Triva or Paje visualization
146 tools. More information can be found in these webpages:
147 <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
148 <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
150 --cfg=tracing/filename:mytracefile.trace
152 If you do not provide this parameter, the trace file will be named simgrid.trace.
157 By default, the tracing system uses all routes in the platform file
158 to re-create a "graph" of the platform and register it in the trace file.
159 This option let the user tell the tracing system to use only the routes
160 that are composed with just one link.
162 --cfg=tracing/onelink_only:1
168 This option only has effect if this simulator is SMPI-based. Traces the MPI
169 interface and generates a trace that can be analyzed using Gantt-like
170 visualizations. Every MPI function (implemented by SMPI) is transformed in a
171 state, and point-to-point communications can be analyzed with arrows.
179 This option only has effect if this simulator is SMPI-based. The processes
180 are grouped by the hosts where they were executed.
182 --cfg=tracing/smpi/group:1
188 This option only has effect if this simulator is MSG-based. It traces the
189 behavior of all categorized MSG tasks, grouping them by hosts.
191 --cfg=tracing/msg/task:1
197 This option only has effect if this simulator is MSG-based. It traces the
198 behavior of all categorized MSG processes, grouping them by hosts. This option
199 can be used to track process location if this simulator has process migration.
201 --cfg=tracing/msg/process:1
207 This option generates a graph configuration file for Triva considering
208 categorized resource utilization.
210 --cfg=triva/categorized:graph_categorized.plist
216 This option generates a graph configuration file for Triva considering
217 uncategorized resource utilization.
219 --cfg=triva/categorized:graph_uncategorized.plist
222 \subsection tracing_tracing_example_parameters Case studies
224 Some scenarios that might help you decide which tracing options
225 you should use to analyze your simulator.
227 \li I want to trace the resource utilization of all hosts
228 and links of the platform, and my simulator <b>does not</b> use
229 the tracing API. For that, you can run a uncategorized trace
230 with the following parameters (it will work with <b>any</b> Simgrid
235 --cfg=tracing/uncategorized:1 \
236 --cfg=tracing/filename:mytracefile.trace \
237 --cfg=triva/uncategorized:uncat.plist
240 \li I want to trace only a subset of my MSG (or SimDAG) tasks.
241 For that, you will need to create tracing categories using the
242 <b>TRACE_category (...)</b> function (as explained above),
243 and then classify your tasks to a previously declared category
244 using the <b>TRACE_msg_set_task_category (...)</b>
245 (or <b>TRACE_sd_set_task_category (...)</b> for SimDAG tasks). After
246 recompiling, run your simulator with the following parameters:
250 --cfg=tracing/categorized:1 \
251 --cfg=tracing/filename:mytracefile.trace \
252 --cfg=triva/categorized:cat.plist
256 \subsection tracing_tracing_example Example of Instrumentation
258 A simplified example using the tracing mandatory functions.
261 int main (int argc, char **argv)
263 MSG_global_init (&argc, &argv);
265 //(... after deployment ...)
267 //note that category declaration must be called after MSG_create_environment
268 TRACE_category_with_color ("request", "1 0 0");
269 TRACE_category_with_color ("computation", "0.3 1 0.4");
270 TRACE_category ("finalize");
272 m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
273 m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
274 m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
275 m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
276 TRACE_msg_set_task_category (req1, "request");
277 TRACE_msg_set_task_category (req2, "request");
278 TRACE_msg_set_task_category (req3, "request");
279 TRACE_msg_set_task_category (req4, "request");
281 m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
282 TRACE_msg_set_task_category (comp, "computation");
284 m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
285 TRACE_msg_set_task_category (finalize, "finalize");
294 \subsection tracing_tracing_analyzing Analyzing the SimGrid Traces
296 The SimGrid library, during an instrumented simulation, creates a trace file in
297 the Paje file format that contains the platform utilization for the simulation
298 that was executed. The visualization analysis of this file is performed with the
299 visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
300 special configurations tunned to SimGrid needs. This part of the documentation
301 explains how to configure and use Triva to analyse a SimGrid trace file.
303 - <b>Installing Triva</b>: the tool is available in the INRIAGforge,
304 at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
305 Use the following command to get the sources, and then check the file
306 <i>INSTALL</i>. This file contains instructions to install
307 the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
308 be compiled in MacOSes natively, check <i>INSTALL.mac</i> file.
310 $ svn checkout svn://scm.gforge.inria.fr/svn/triva
315 - <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
316 installation (you can execute it passing <em>--help</em> to check its
317 options). If the triva binary is not available after following the
318 installation instructions, you may want to execute the following command to
319 initialize the GNUstep environment variables. We strongly recommend that you
320 use the latest GNUstep packages, and not the packages available through apt-get
321 in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
322 available packages, you can execute this command:
324 $ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
326 You should be able to see this output after the installation of triva:
328 $ ./Triva.app/Triva --help
329 Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
330 Trace Analysis through Visualization
333 --ti_frequency {double} Animation: frequency of updates
334 --ti_hide Hide the TimeInterval window
335 --ti_forward {double} Animation: value to move time-slice
336 --ti_apply Apply the configuration
337 --ti_update Update on slider change
338 --ti_animate Start animation
339 --ti_start {double} Start of time slice
340 --ti_size {double} Size of time slice
342 --comparison Compare Trace Files (Experimental)
343 --graph Configurable Graph
344 --list Print Trace Type Hierarchy
345 --hierarchy Export Trace Type Hierarchy (dot)
346 --stat Trace Statistics and Memory Utilization
347 --instances List All Trace Entities
348 --linkview Link View (Experimental)
349 --treemap Squarified Treemap
350 --merge Merge Trace Files (Experimental)
351 --check Check Trace File Integrity
353 --gc_conf {file} Graph Configuration in Property List Format
354 --gc_apply Apply the configuration
355 --gc_hide Hide the GraphConfiguration window
357 Triva expects that the user choose one of the available options
358 (currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
359 and the trace file from the simulation.
361 - <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
362 the tool always takes into account the concept of the <em>time-slice</em>.
363 This concept means that what is being visualized in the screen is always
364 calculated considering a specific time frame, with its beggining and end
365 timestamp. The time-slice is configured by the user and can be changed
366 dynamically through the window called <em>Time Interval</em> that is opened
367 whenever a trace file is being analyzed. The next figure depicts the time-slice
368 configuration window.
369 In the top of the window, in the space named <i>Trace Time</i>,
370 the two fields show the beggining of the trace (which usually starts in 0) and
371 the end (that depends on the time simulated by SimGrid). The middle of the
372 window, in the square named <i>Time Slice Configuration</i>, contains the
373 aspects related to the time-slice, including its <i>start</i> and its
374 <i>size</i>. The gray rectangle in the bottom of this part indicates the
375 <i>current time-slice</i> that is considered for the drawings. If the checkbox
376 <i>Update Drawings on Sliders Change</i> is not selected, the button
377 <i>Apply</i> must be clicked in order to inform triva that the
378 new time-slice must be considered. The bottom part of the window, in the space
379 indicated by the square <i>Time Slice Animation</i> can be used to advance
380 the time-frame automatically. The user configures the amount of time that the
381 time-frame will forward and how frequent this update will happen. Once this is
382 configured, the user clicks the <i>Play</i> button in order to see the dynamic
383 changes on the drawings.
386 <a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
389 <b>Remarks:</b> when the trace has too many hosts or links, the computation to
390 take into account a new time-slice can be expensive. When this happens, the
391 <i>Frequency</i> parameter, but also updates caused by change on configurations
392 when the checkbox <i>Update Drawings on Sliders
393 Change</i> is selected will not be followed.
395 - <b>Understanding Triva - graph</b>: this part of the documention explains how
396 to analyze the traces using the graph view of Triva, when the user executes
397 the tool passing <em>--graph</em> as parameter. Triva opens three windows when
398 this parameter is used: the <i>Time Interval</i> window (previously described),
399 the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
400 window. The Graph Representation is the window where drawings take place.
401 Initially, it is completely white waiting for a proper graph configuration input
402 by the user. We start the description of this type of analysis by describing the
403 <i>Graph Configuration</i> window (depicted below). By using a particular
405 can be used to customize the graph drawing according to
406 the SimGrid trace that was created with user-specific categories. Before delving
407 into the details of this customization, let us first explain the major parts of
408 the graph configuration window. The buttons located in the top-right corner can
409 be used to delete, copy and create a new configuration. The checkbox in the
410 top-middle part of the window indicates if the configuration typed in the
411 textfield is syntactically correct (we are using the non-XML
412 <a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
413 describe the configuration). The pop-up button located on the top-left corner
414 indicates the selected configuration (the user can have multiple graph
415 configurations). The bottom-left text field contains the name of the current
416 configuration (updates on this field must be followed by typing enter on the
417 keyboard to take into account the name change). The bottom-right <em>Apply</em>
418 button activates the current configuration, resulting on an update on the graph
422 <a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
425 <b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
426 basic configuration that should be used during the analysis of a SimGrid trace
427 file. The basic logic of the configuration is as follows:
433 The nodes of the graph will be created based on the <i>node</i> parameter, which
434 in this case is the different <em>"HOST"</em>s of the platform
435 used to simulate. The <i>edge</i> parameter indicates that the edges of the
436 graph will be created based on the <em>"LINK"</em>s of the platform. After the
437 definition of these two parameters, the configuration must detail how
438 <em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
439 must have an entry for each of the types used. For <em>HOST</em>, as basic
440 configuration, we have:
447 The parameter <em>size</em> indicates which variable from the trace file will be
448 used to define the size of the node HOST in the visualization. If the simulation
449 was executed with availability traces, the size of the nodes will be changed
450 according to these traces. The parameter <em>scale</em> indicates if the value
451 of the variable is <em>global</em> or <em>local</em>. If it is global, the value
452 will be relative to the power of all other hosts, if it is local, the value will
454 For <em>LINK</em> we have:
464 For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
465 the configuration must contain two additional parameters: <em>src</em> and
466 <em>dst</em> that are used to properly identify which nodes this edge is
467 connecting. The values <em>source</em> and <em>destination</em> are always present
468 in the SimGrid trace file and should not be changed in the configuration. The
469 parameter <em>size</em> for the LINK, in this case, is configured as the
470 variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
471 here is exactly the same used for nodes. The last parameter is the GraphViz
472 algorithm used to calculate the position of the nodes in the graph
475 graphviz-algorithm = neato;
478 <b>Customizing the Graph Representation</b>: triva is capable to handle
479 a customized graph representation based on the variables present in the trace
480 file. In the case of SimGrid, every time a category is created for tasks, two
481 variables in the trace file are defined: one to indicate node utilization (how
482 much power was used by that task category), and another to indicate link
483 utilization (how much bandwidth was used by that category). For instance, if the
484 user declares a category named <i>request</i>, there will be variables named
485 <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
486 <b>b</b> for bandwidth). It is important to notice that the variable
487 <i>prequest</i> in this case is only available for HOST, and
488 <i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
489 two categories for tasks: request and compute. To create a customized graph
490 representation with a proportional separation of host and link utilization, use
491 as configuration for HOST and LINK this:
500 values = (prequest, pcomputation);
513 values = (brequest, bcomputation);
517 Where <i>sep_host</i> contains a composition of type <i>separation</i> where
518 its max size is the <i>power</i> of the host and the variables <i>prequest</i>
519 and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
520 <i>sep_link</i> is also a separation where max is defined as the
521 <i>bandwidth</i> of the link, and the variables <i>brequest</i> and
522 <i>bcomputation</i> are drawn proportionally within a LINK.
523 <i>This configuration enables the analysis of resource utilization by MSG tasks,
524 and the identification of load-balancing issues, network bottlenecks, for
526 <b>Other compositions</b>: besides <i>separation</i>, it is possible to use
527 other types of compositions, such as gradients, and colors, like this:
532 values = (numberOfTasks);
536 values = (is_server);
539 Where <i>gra_host</i> creates a gradient within a node of the graph, using a
540 global scale and using as value a variable called <i>numberOfTasks</i>, that
541 could be declared by the user using the optional tracing functions of SimGrid.
542 If scale is global, the max and min value for the gradient will be equal to the
543 max and min numberOfTasks among all hosts, and if scale is local, the max and
544 min value based on the value of numberOfTasks locally in each host.
545 And <i>color_host</i> composition draws a square based on a positive value of
546 the variable <i>is_server</i>, that could also be defined by the user using the
547 SimGrid tracing functions. \n
548 <b>The Graph Visualization</b>: The next figure shows a graph visualization of a
549 given time-slice of the masterslave_forwarder example (present in the SimGrid
550 sources). The red color indicates tasks from the <i>compute</i> category. This
551 visualization was generated with the following configuration:
564 values = (pcompute, pfinalize);
570 size = bandwidth;\section tracing_tracing Tracing Simulations for Visualization
572 The trace visualization is widely used to observe and understand the behavior
573 of parallel applications and distributed algorithms. Usually, this is done in a
574 two-step fashion: the user instruments the application and the traces are
575 analyzed after the end of the execution. The visualization itself can highlights
576 unexpected behaviors, bottlenecks and sometimes can be used to correct
577 distributed algorithms. The SimGrid team has instrumented the library
578 in order to let users trace their simulations and analyze them. This part of the
579 user manual explains how the tracing-related features can be enabled and used
580 during the development of simulators using the SimGrid library.
582 \subsection tracing_tracing_howitworks How it works
584 For now, the SimGrid library is instrumented so users can trace the <b>platform
585 utilization</b> using the MSG, SimDAG and SMPI interface. This means that the tracing will
586 register how much power is used for each host and how much bandwidth is used for
587 each link of the platform. The idea with this type of tracing is to observe the
588 overall view of resources utilization in the first place, especially the
589 identification of bottlenecks, load-balancing among hosts, and so on.
591 The idea of the tracing facilities is to give SimGrid users to possibility to
592 classify MSG and SimDAG tasks by category, tracing the platform utilization
593 (hosts and links) for each of the categories. For that,
594 the tracing interface enables the declaration of categories and a function to
595 mark a task with a previously declared category. <em>The tasks that are not
596 classified according to a category are not traced</em>. Even if the user
597 does not specify any category, the simulations can still be traced in terms
598 of resource utilization by using a special parameter that is detailed below.
600 \subsection tracing_tracing_enabling Enabling using CMake
602 With the sources of SimGrid, it is possible to enable the tracing
603 using the parameter <b>-Denable_tracing=ON</b> when the cmake is executed.
604 The section \ref tracing_tracing_functions describes all the functions available
605 when this Cmake options is activated. These functions will have no effect
606 if SimGrid is configured without this option (they are wiped-out by the
610 $ cmake -Denable_tracing=ON .
614 \subsection tracing_tracing_functions Tracing Functions
616 \li <b>\c TRACE_category (const char *category)</b>: This function should be used
617 to define a user category. The category can be used to differentiate the tasks
618 that are created during the simulation (for example, tasks from server1,
619 server2, or request tasks, computation tasks, communication tasks).
620 All resource utilization (host power and link bandwidth) will be
621 classified according to the task category. Tasks that do not belong to a
622 category are not traced. The color for the category that is being declared
623 is random (use next function to specify a color).
625 \li <b>\c TRACE_category_with_color (const char *category, const char *color)</b>: Same
626 as TRACE_category, but let user specify a color encoded as a RGB-like string with
627 three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
628 color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
630 \li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
631 This function should be called after the creation of a MSG task, to define the
632 category of that task. The first parameter \c task must contain a task that was
633 created with the function \c MSG_task_create. The second parameter
634 \c category must contain a category that was previously defined by the function
637 \li <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
638 This function should be called after the creation of a SimDAG task, to define the
639 category of that task. The first parameter \c task must contain a task that was
640 created with the function \c MSG_task_create. The second parameter
641 \c category must contain a category that was previously defined by the function
644 \li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
645 Declare a user variable that will be associated to host/link. A variable can
646 be used to trace user variables such as the number of tasks in a server,
647 the number of clients in an application (for hosts), and so on.
649 \li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
650 Set the value of a given user variable for a given host/link. The value
651 of this variable is always associated to the host/link. The host/link
652 parameters should be its name as the one listed in the platform file.
654 \li <b>\c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value)</b>:
655 Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
656 the time used to trace it. Users can specify a time that is not the
657 simulated clock time as defined by the core simulator. This allows
658 a fine-grain control of time definition, but should be used with
659 caution since the trace can be inconsistent if resource utilization
660 traces are also traced.
662 \li <b>\c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value)</b>:
663 Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
664 destination hosts (as the names from the platform file). The tracing library
665 will get the corresponding route that connects those two hosts (src and dst) and
666 [set|add|sub] the value's variable for all the links of the route.
668 \li <b>\c TRACE_link_srcdst_variable_[set|add|sub]_with_time (double time, const char *src, const char *dst, const char *variable, double value)</b>:
669 Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
671 \subsection tracing_tracing_options Tracing configuration Options
673 These are the options accepted by the tracing system of SimGrid:
678 Safe switch. It activates (or deactivates) the tracing system.
679 No other tracing options take effect if this one is not activated.
684 Register the simulation platform in the trace file.
689 By default, the tracing system uses all routes in the platform file
690 to re-create a "graph" of the platform and register it in the trace file.
691 This option let the user tell the tracing system to use only the routes
692 that are composed with just one link.
697 It activates the categorized resource utilization tracing. It should
698 be enabled if tracing categories are used by this simulator.
701 tracing/uncategorized
703 It activates the uncategorized resource utilization tracing. Use it if
704 this simulator do not use tracing categories and resource use have to be
710 A file with this name will be created to register the simulation. The file
711 is in the Paje format and can be analyzed using Triva or Paje visualization
712 tools. More information can be found in these webpages:
713 <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
714 <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
719 This option only has effect if this simulator is SMPI-based. Traces the MPI
720 interface and generates a trace that can be analyzed using Gantt-like
721 visualizations. Every MPI function (implemented by SMPI) is transformed in a
722 state, and point-to-point communications can be analyzed with arrows.
727 This option only has effect if this simulator is SMPI-based. The processes
728 are grouped by the hosts where they were executed.
733 This option only has effect if this simulator is MSG-based. It traces the
734 behavior of all categorized MSG tasks, grouping them by hosts.
739 This option only has effect if this simulator is MSG-based. It traces the
740 behavior of all categorized MSG processes, grouping them by hosts. This option
741 can be used to track process location if this simulator has process migration.
745 triva/categorized:graph_categorized.plist
747 This option generates a graph configuration file for Triva considering
748 categorized resource utilization.
751 triva/uncategorized:graph_uncategorized.plist
753 This option generates a graph configuration file for Triva considering
754 uncategorized resource utilization.
756 \subsection tracing_tracing_example Example of Instrumentation
758 A simplified example using the tracing mandatory functions.
761 int main (int argc, char **argv)
763 MSG_global_init (&argc, &argv);
765 //(... after deployment ...)
767 //note that category declaration must be called after MSG_create_environment
768 TRACE_category_with_color ("request", "1 0 0");
769 TRACE_category_with_color ("computation", "0.3 1 0.4");
770 TRACE_category ("finalize");
772 m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
773 m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
774 m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
775 m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
776 TRACE_msg_set_task_category (req1, "request");
777 TRACE_msg_set_task_category (req2, "request");
778 TRACE_msg_set_task_category (req3, "request");
779 TRACE_msg_set_task_category (req4, "request");
781 m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
782 TRACE_msg_set_task_category (comp, "computation");
784 m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
785 TRACE_msg_set_task_category (finalize, "finalize");
794 \subsection tracing_tracing_analyzing Analyzing the SimGrid Traces
796 The SimGrid library, during an instrumented simulation, creates a trace file in
797 the Paje file format that contains the platform utilization for the simulation
798 that was executed. The visualization analysis of this file is performed with the
799 visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
800 special configurations tunned to SimGrid needs. This part of the documentation
801 explains how to configure and use Triva to analyse a SimGrid trace file.
803 - <b>Installing Triva</b>: the tool is available in the INRIAGforge,
804 at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
805 Use the following command to get the sources, and then check the file
806 <i>INSTALL</i>. This file contains instructions to install
807 the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
808 be compiled in MacOSes natively, check <i>INSTALL.mac</i> file.
810 $ svn checkout svn://scm.gforge.inria.fr/svn/triva
815 - <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
816 installation (you can execute it passing <em>--help</em> to check its
817 options). If the triva binary is not available after following the
818 installation instructions, you may want to execute the following command to
819 initialize the GNUstep environment variables. We strongly recommend that you
820 use the latest GNUstep packages, and not the packages available through apt-get
821 in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
822 available packages, you can execute this command:
824 $ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
826 You should be able to see this output after the installation of triva:
828 $ ./Triva.app/Triva --help
829 Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
830 Trace Analysis through Visualization
833 --ti_frequency {double} Animation: frequency of updates
834 --ti_hide Hide the TimeInterval window
835 --ti_forward {double} Animation: value to move time-slice
836 --ti_apply Apply the configuration
837 --ti_update Update on slider change
838 --ti_animate Start animation
839 --ti_start {double} Start of time slice
840 --ti_size {double} Size of time slice
842 --comparison Compare Trace Files (Experimental)
843 --graph Configurable Graph
844 --list Print Trace Type Hierarchy
845 --hierarchy Export Trace Type Hierarchy (dot)
846 --stat Trace Statistics and Memory Utilization
847 --instances List All Trace Entities
848 --linkview Link View (Experimental)
849 --treemap Squarified Treemap
850 --merge Merge Trace Files (Experimental)
851 --check Check Trace File Integrity
853 --gc_conf {file} Graph Configuration in Property List Format
854 --gc_apply Apply the configuration
855 --gc_hide Hide the GraphConfiguration window
857 Triva expects that the user choose one of the available options
858 (currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
859 and the trace file from the simulation.
861 - <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
862 the tool always takes into account the concept of the <em>time-slice</em>.
863 This concept means that what is being visualized in the screen is always
864 calculated considering a specific time frame, with its beggining and end
865 timestamp. The time-slice is configured by the user and can be changed
866 dynamically through the window called <em>Time Interval</em> that is opened
867 whenever a trace file is being analyzed. The next figure depicts the time-slice
868 configuration window.
869 In the top of the window, in the space named <i>Trace Time</i>,
870 the two fields show the beggining of the trace (which usually starts in 0) and
871 the end (that depends on the time simulated by SimGrid). The middle of the
872 window, in the square named <i>Time Slice Configuration</i>, contains the
873 aspects related to the time-slice, including its <i>start</i> and its
874 <i>size</i>. The gray rectangle in the bottom of this part indicates the
875 <i>current time-slice</i> that is considered for the drawings. If the checkbox
876 <i>Update Drawings on Sliders Change</i> is not selected, the button
877 <i>Apply</i> must be clicked in order to inform triva that the
878 new time-slice must be considered. The bottom part of the window, in the space
879 indicated by the square <i>Time Slice Animation</i> can be used to advance
880 the time-frame automatically. The user configures the amount of time that the
881 time-frame will forward and how frequent this update will happen. Once this is
882 configured, the user clicks the <i>Play</i> button in order to see the dynamic
883 changes on the drawings.
886 <a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
889 <b>Remarks:</b> when the trace has too many hosts or links, the computation to
890 take into account a new time-slice can be expensive. When this happens, the
891 <i>Frequency</i> parameter, but also updates caused by change on configurations
892 when the checkbox <i>Update Drawings on Sliders
893 Change</i> is selected will not be followed.
895 - <b>Understanding Triva - graph</b>: this part of the documention explains how
896 to analyze the traces using the graph view of Triva, when the user executes
897 the tool passing <em>--graph</em> as parameter. Triva opens three windows when
898 this parameter is used: the <i>Time Interval</i> window (previously described),
899 the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
900 window. The Graph Representation is the window where drawings take place.
901 Initially, it is completely white waiting for a proper graph configuration input
902 by the user. We start the description of this type of analysis by describing the
903 <i>Graph Configuration</i> window (depicted below). By using a particular
905 can be used to customize the graph drawing according to
906 the SimGrid trace that was created with user-specific categories. Before delving
907 into the details of this customization, let us first explain the major parts of
908 the graph configuration window. The buttons located in the top-right corner can
909 be used to delete, copy and create a new configuration. The checkbox in the
910 top-middle part of the window indicates if the configuration typed in the
911 textfield is syntactically correct (we are using the non-XML
912 <a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
913 describe the configuration). The pop-up button located on the top-left corner
914 indicates the selected configuration (the user can have multiple graph
915 configurations). The bottom-left text field contains the name of the current
916 configuration (updates on this field must be followed by typing enter on the
917 keyboard to take into account the name change). The bottom-right <em>Apply</em>
918 button activates the current configuration, resulting on an update on the graph
922 <a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
925 <b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
926 basic configuration that should be used during the analysis of a SimGrid trace
927 file. The basic logic of the configuration is as follows:
933 The nodes of the graph will be created based on the <i>node</i> parameter, which
934 in this case is the different <em>"HOST"</em>s of the platform
935 used to simulate. The <i>edge</i> parameter indicates that the edges of the
936 graph will be created based on the <em>"LINK"</em>s of the platform. After the
937 definition of these two parameters, the configuration must detail how
938 <em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
939 must have an entry for each of the types used. For <em>HOST</em>, as basic
940 configuration, we have:
947 The parameter <em>size</em> indicates which variable from the trace file will be
948 used to define the size of the node HOST in the visualization. If the simulation
949 was executed with availability traces, the size of the nodes will be changed
950 according to these traces. The parameter <em>scale</em> indicates if the value
951 of the variable is <em>global</em> or <em>local</em>. If it is global, the value
952 will be relative to the power of all other hosts, if it is local, the value will
954 For <em>LINK</em> we have:
964 For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
965 the configuration must contain two additional parameters: <em>src</em> and
966 <em>dst</em> that are used to properly identify which nodes this edge is
967 connecting. The values <em>source</em> and <em>destination</em> are always present
968 in the SimGrid trace file and should not be changed in the configuration. The
969 parameter <em>size</em> for the LINK, in this case, is configured as the
970 variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
971 here is exactly the same used for nodes. The last parameter is the GraphViz
972 algorithm used to calculate the position of the nodes in the graph
975 graphviz-algorithm = neato;
978 <b>Customizing the Graph Representation</b>: triva is capable to handle
979 a customized graph representation based on the variables present in the trace
980 file. In the case of SimGrid, every time a category is created for tasks, two
981 variables in the trace file are defined: one to indicate node utilization (how
982 much power was used by that task category), and another to indicate link
983 utilization (how much bandwidth was used by that category). For instance, if the
984 user declares a category named <i>request</i>, there will be variables named
985 <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
986 <b>b</b> for bandwidth). It is important to notice that the variable
987 <i>prequest</i> in this case is only available for HOST, and
988 <i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
989 two categories for tasks: request and compute. To create a customized graph
990 representation with a proportional separation of host and link utilization, use
991 as configuration for HOST and LINK this:
1000 values = (prequest, pcomputation);
1013 values = (brequest, bcomputation);
1017 Where <i>sep_host</i> contains a composition of type <i>separation</i> where
1018 its max size is the <i>power</i> of the host and the variables <i>prequest</i>
1019 and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
1020 <i>sep_link</i> is also a separation where max is defined as the
1021 <i>bandwidth</i> of the link, and the variables <i>brequest</i> and
1022 <i>bcomputation</i> are drawn proportionally within a LINK.
1023 <i>This configuration enables the analysis of resource utilization by MSG tasks,
1024 and the identification of load-balancing issues, network bottlenecks, for
1026 <b>Other compositions</b>: besides <i>separation</i>, it is possible to use
1027 other types of compositions, such as gradients, and colors, like this:
1032 values = (numberOfTasks);
1036 values = (is_server);
1039 Where <i>gra_host</i> creates a gradient within a node of the graph, using a
1040 global scale and using as value a variable called <i>numberOfTasks</i>, that
1041 could be declared by the user using the optional tracing functions of SimGrid.
1042 If scale is global, the max and min value for the gradient will be equal to the
1043 max and min numberOfTasks among all hosts, and if scale is local, the max and
1044 min value based on the value of numberOfTasks locally in each host.
1045 And <i>color_host</i> composition draws a square based on a positive value of
1046 the variable <i>is_server</i>, that could also be defined by the user using the
1047 SimGrid tracing functions. \n
1048 <b>The Graph Visualization</b>: The next figure shows a graph visualization of a
1049 given time-slice of the masterslave_forwarder example (present in the SimGrid
1050 sources). The red color indicates tasks from the <i>compute</i> category. This
1051 visualization was generated with the following configuration:
1064 values = (pcompute, pfinalize);
1076 values = (bcompute, bfinalize);
1079 graphviz-algorithm = neato;
1084 <a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
1088 - <b>Understading Triva - colors</b>: An important issue when using Triva is how
1089 to define colors. To do that, we have to know which variables are defined in
1090 the trace file generated by the SimGrid library. The parameter <em>--list</em>
1091 lists the variables for a given trace file:
1093 $ Triva -l masterslave_forwarder.trace
1111 We can see that HOST has seven variables (from power to pfinalize) and LINK has
1112 four (from bandwidth to bfinalize). To define a red color for the
1113 <i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
1114 <i>compute</i>), execute:
1116 $ defaults write Triva 'pcompute Color' '1 0 0'
1117 $ defaults write Triva 'bcompute Color' '1 0 0'
1119 Where the three numbers in each line are the RGB color with values from 0 to 1.
1126 values = (bcompute, bfinalize);
1129 graphviz-algorithm = neato;
1134 <a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
1138 - <b>Understading Triva - colors</b>: An important issue when using Triva is how
1139 to define colors. To do that, we have to know which variables are defined in
1140 the trace file generated by the SimGrid library. The parameter <em>--list</em>
1141 lists the variables for a given trace file:
1143 $ Triva -l masterslave_forwarder.trace
1161 We can see that HOST has seven variables (from power to pfinalize) and LINK has
1162 four (from bandwidth to bfinalize). To define a red color for the
1163 <i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
1164 <i>compute</i>), execute:
1166 $ defaults write Triva 'pcompute Color' '1 0 0'
1167 $ defaults write Triva 'bcompute Color' '1 0 0'
1169 Where the three numbers in each line are the RGB color with values from 0 to 1.