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 These are the options accepted by the tracing system of SimGrid:
113 Safe switch. It activates (or deactivates) the tracing system.
114 No other tracing options take effect if this one is not activated.
119 Register the simulation platform in the trace file.
124 By default, the tracing system uses all routes in the platform file
125 to re-create a "graph" of the platform and register it in the trace file.
126 This option let the user tell the tracing system to use only the routes
127 that are composed with just one link.
132 It activates the categorized resource utilization tracing. It should
133 be enabled if tracing categories are used by this simulator.
136 tracing/uncategorized
138 It activates the uncategorized resource utilization tracing. Use it if
139 this simulator do not use tracing categories and resource use have to be
145 A file with this name will be created to register the simulation. The file
146 is in the Paje format and can be analyzed using Triva or Paje visualization
147 tools. More information can be found in these webpages:
148 <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
149 <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
154 This option only has effect if this simulator is SMPI-based. Traces the MPI
155 interface and generates a trace that can be analyzed using Gantt-like
156 visualizations. Every MPI function (implemented by SMPI) is transformed in a
157 state, and point-to-point communications can be analyzed with arrows.
162 This option only has effect if this simulator is SMPI-based. The processes
163 are grouped by the hosts where they were executed.
168 This option only has effect if this simulator is MSG-based. It traces the
169 behavior of all categorized MSG tasks, grouping them by hosts.
174 This option only has effect if this simulator is MSG-based. It traces the
175 behavior of all categorized MSG processes, grouping them by hosts. This option
176 can be used to track process location if this simulator has process migration.
180 triva/categorized:graph_categorized.plist
182 This option generates a graph configuration file for Triva considering
183 categorized resource utilization.
186 triva/uncategorized:graph_uncategorized.plist
188 This option generates a graph configuration file for Triva considering
189 uncategorized resource utilization.
191 \subsection tracing_tracing_example Example of Instrumentation
193 A simplified example using the tracing mandatory functions.
196 int main (int argc, char **argv)
198 MSG_global_init (&argc, &argv);
200 //(... after deployment ...)
202 //note that category declaration must be called after MSG_create_environment
203 TRACE_category_with_color ("request", "1 0 0");
204 TRACE_category_with_color ("computation", "0.3 1 0.4");
205 TRACE_category ("finalize");
207 m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
208 m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
209 m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
210 m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
211 TRACE_msg_set_task_category (req1, "request");
212 TRACE_msg_set_task_category (req2, "request");
213 TRACE_msg_set_task_category (req3, "request");
214 TRACE_msg_set_task_category (req4, "request");
216 m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
217 TRACE_msg_set_task_category (comp, "computation");
219 m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
220 TRACE_msg_set_task_category (finalize, "finalize");
229 \subsection tracing_tracing_analyzing Analyzing the SimGrid Traces
231 The SimGrid library, during an instrumented simulation, creates a trace file in
232 the Paje file format that contains the platform utilization for the simulation
233 that was executed. The visualization analysis of this file is performed with the
234 visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
235 special configurations tunned to SimGrid needs. This part of the documentation
236 explains how to configure and use Triva to analyse a SimGrid trace file.
238 - <b>Installing Triva</b>: the tool is available in the INRIAGforge,
239 at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
240 Use the following command to get the sources, and then check the file
241 <i>INSTALL</i>. This file contains instructions to install
242 the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
243 be compiled in MacOSes natively, check <i>INSTALL.mac</i> file.
245 $ svn checkout svn://scm.gforge.inria.fr/svn/triva
250 - <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
251 installation (you can execute it passing <em>--help</em> to check its
252 options). If the triva binary is not available after following the
253 installation instructions, you may want to execute the following command to
254 initialize the GNUstep environment variables. We strongly recommend that you
255 use the latest GNUstep packages, and not the packages available through apt-get
256 in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
257 available packages, you can execute this command:
259 $ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
261 You should be able to see this output after the installation of triva:
263 $ ./Triva.app/Triva --help
264 Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
265 Trace Analysis through Visualization
268 --ti_frequency {double} Animation: frequency of updates
269 --ti_hide Hide the TimeInterval window
270 --ti_forward {double} Animation: value to move time-slice
271 --ti_apply Apply the configuration
272 --ti_update Update on slider change
273 --ti_animate Start animation
274 --ti_start {double} Start of time slice
275 --ti_size {double} Size of time slice
277 --comparison Compare Trace Files (Experimental)
278 --graph Configurable Graph
279 --list Print Trace Type Hierarchy
280 --hierarchy Export Trace Type Hierarchy (dot)
281 --stat Trace Statistics and Memory Utilization
282 --instances List All Trace Entities
283 --linkview Link View (Experimental)
284 --treemap Squarified Treemap
285 --merge Merge Trace Files (Experimental)
286 --check Check Trace File Integrity
288 --gc_conf {file} Graph Configuration in Property List Format
289 --gc_apply Apply the configuration
290 --gc_hide Hide the GraphConfiguration window
292 Triva expects that the user choose one of the available options
293 (currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
294 and the trace file from the simulation.
296 - <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
297 the tool always takes into account the concept of the <em>time-slice</em>.
298 This concept means that what is being visualized in the screen is always
299 calculated considering a specific time frame, with its beggining and end
300 timestamp. The time-slice is configured by the user and can be changed
301 dynamically through the window called <em>Time Interval</em> that is opened
302 whenever a trace file is being analyzed. The next figure depicts the time-slice
303 configuration window.
304 In the top of the window, in the space named <i>Trace Time</i>,
305 the two fields show the beggining of the trace (which usually starts in 0) and
306 the end (that depends on the time simulated by SimGrid). The middle of the
307 window, in the square named <i>Time Slice Configuration</i>, contains the
308 aspects related to the time-slice, including its <i>start</i> and its
309 <i>size</i>. The gray rectangle in the bottom of this part indicates the
310 <i>current time-slice</i> that is considered for the drawings. If the checkbox
311 <i>Update Drawings on Sliders Change</i> is not selected, the button
312 <i>Apply</i> must be clicked in order to inform triva that the
313 new time-slice must be considered. The bottom part of the window, in the space
314 indicated by the square <i>Time Slice Animation</i> can be used to advance
315 the time-frame automatically. The user configures the amount of time that the
316 time-frame will forward and how frequent this update will happen. Once this is
317 configured, the user clicks the <i>Play</i> button in order to see the dynamic
318 changes on the drawings.
321 <a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
324 <b>Remarks:</b> when the trace has too many hosts or links, the computation to
325 take into account a new time-slice can be expensive. When this happens, the
326 <i>Frequency</i> parameter, but also updates caused by change on configurations
327 when the checkbox <i>Update Drawings on Sliders
328 Change</i> is selected will not be followed.
330 - <b>Understanding Triva - graph</b>: this part of the documention explains how
331 to analyze the traces using the graph view of Triva, when the user executes
332 the tool passing <em>--graph</em> as parameter. Triva opens three windows when
333 this parameter is used: the <i>Time Interval</i> window (previously described),
334 the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
335 window. The Graph Representation is the window where drawings take place.
336 Initially, it is completely white waiting for a proper graph configuration input
337 by the user. We start the description of this type of analysis by describing the
338 <i>Graph Configuration</i> window (depicted below). By using a particular
340 can be used to customize the graph drawing according to
341 the SimGrid trace that was created with user-specific categories. Before delving
342 into the details of this customization, let us first explain the major parts of
343 the graph configuration window. The buttons located in the top-right corner can
344 be used to delete, copy and create a new configuration. The checkbox in the
345 top-middle part of the window indicates if the configuration typed in the
346 textfield is syntactically correct (we are using the non-XML
347 <a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
348 describe the configuration). The pop-up button located on the top-left corner
349 indicates the selected configuration (the user can have multiple graph
350 configurations). The bottom-left text field contains the name of the current
351 configuration (updates on this field must be followed by typing enter on the
352 keyboard to take into account the name change). The bottom-right <em>Apply</em>
353 button activates the current configuration, resulting on an update on the graph
357 <a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
360 <b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
361 basic configuration that should be used during the analysis of a SimGrid trace
362 file. The basic logic of the configuration is as follows:
368 The nodes of the graph will be created based on the <i>node</i> parameter, which
369 in this case is the different <em>"HOST"</em>s of the platform
370 used to simulate. The <i>edge</i> parameter indicates that the edges of the
371 graph will be created based on the <em>"LINK"</em>s of the platform. After the
372 definition of these two parameters, the configuration must detail how
373 <em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
374 must have an entry for each of the types used. For <em>HOST</em>, as basic
375 configuration, we have:
382 The parameter <em>size</em> indicates which variable from the trace file will be
383 used to define the size of the node HOST in the visualization. If the simulation
384 was executed with availability traces, the size of the nodes will be changed
385 according to these traces. The parameter <em>scale</em> indicates if the value
386 of the variable is <em>global</em> or <em>local</em>. If it is global, the value
387 will be relative to the power of all other hosts, if it is local, the value will
389 For <em>LINK</em> we have:
399 For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
400 the configuration must contain two additional parameters: <em>src</em> and
401 <em>dst</em> that are used to properly identify which nodes this edge is
402 connecting. The values <em>source</em> and <em>destination</em> are always present
403 in the SimGrid trace file and should not be changed in the configuration. The
404 parameter <em>size</em> for the LINK, in this case, is configured as the
405 variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
406 here is exactly the same used for nodes. The last parameter is the GraphViz
407 algorithm used to calculate the position of the nodes in the graph
410 graphviz-algorithm = neato;
413 <b>Customizing the Graph Representation</b>: triva is capable to handle
414 a customized graph representation based on the variables present in the trace
415 file. In the case of SimGrid, every time a category is created for tasks, two
416 variables in the trace file are defined: one to indicate node utilization (how
417 much power was used by that task category), and another to indicate link
418 utilization (how much bandwidth was used by that category). For instance, if the
419 user declares a category named <i>request</i>, there will be variables named
420 <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
421 <b>b</b> for bandwidth). It is important to notice that the variable
422 <i>prequest</i> in this case is only available for HOST, and
423 <i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
424 two categories for tasks: request and compute. To create a customized graph
425 representation with a proportional separation of host and link utilization, use
426 as configuration for HOST and LINK this:
435 values = (prequest, pcomputation);
448 values = (brequest, bcomputation);
452 Where <i>sep_host</i> contains a composition of type <i>separation</i> where
453 its max size is the <i>power</i> of the host and the variables <i>prequest</i>
454 and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
455 <i>sep_link</i> is also a separation where max is defined as the
456 <i>bandwidth</i> of the link, and the variables <i>brequest</i> and
457 <i>bcomputation</i> are drawn proportionally within a LINK.
458 <i>This configuration enables the analysis of resource utilization by MSG tasks,
459 and the identification of load-balancing issues, network bottlenecks, for
461 <b>Other compositions</b>: besides <i>separation</i>, it is possible to use
462 other types of compositions, such as gradients, and colors, like this:
467 values = (numberOfTasks);
471 values = (is_server);
474 Where <i>gra_host</i> creates a gradient within a node of the graph, using a
475 global scale and using as value a variable called <i>numberOfTasks</i>, that
476 could be declared by the user using the optional tracing functions of SimGrid.
477 If scale is global, the max and min value for the gradient will be equal to the
478 max and min numberOfTasks among all hosts, and if scale is local, the max and
479 min value based on the value of numberOfTasks locally in each host.
480 And <i>color_host</i> composition draws a square based on a positive value of
481 the variable <i>is_server</i>, that could also be defined by the user using the
482 SimGrid tracing functions. \n
483 <b>The Graph Visualization</b>: The next figure shows a graph visualization of a
484 given time-slice of the masterslave_forwarder example (present in the SimGrid
485 sources). The red color indicates tasks from the <i>compute</i> category. This
486 visualization was generated with the following configuration:
499 values = (pcompute, pfinalize);
505 size = bandwidth;\section tracing_tracing Tracing Simulations for Visualization
507 The trace visualization is widely used to observe and understand the behavior
508 of parallel applications and distributed algorithms. Usually, this is done in a
509 two-step fashion: the user instruments the application and the traces are
510 analyzed after the end of the execution. The visualization itself can highlights
511 unexpected behaviors, bottlenecks and sometimes can be used to correct
512 distributed algorithms. The SimGrid team has instrumented the library
513 in order to let users trace their simulations and analyze them. This part of the
514 user manual explains how the tracing-related features can be enabled and used
515 during the development of simulators using the SimGrid library.
517 \subsection tracing_tracing_howitworks How it works
519 For now, the SimGrid library is instrumented so users can trace the <b>platform
520 utilization</b> using the MSG, SimDAG and SMPI interface. This means that the tracing will
521 register how much power is used for each host and how much bandwidth is used for
522 each link of the platform. The idea with this type of tracing is to observe the
523 overall view of resources utilization in the first place, especially the
524 identification of bottlenecks, load-balancing among hosts, and so on.
526 The idea of the tracing facilities is to give SimGrid users to possibility to
527 classify MSG and SimDAG tasks by category, tracing the platform utilization
528 (hosts and links) for each of the categories. For that,
529 the tracing interface enables the declaration of categories and a function to
530 mark a task with a previously declared category. <em>The tasks that are not
531 classified according to a category are not traced</em>. Even if the user
532 does not specify any category, the simulations can still be traced in terms
533 of resource utilization by using a special parameter that is detailed below.
535 \subsection tracing_tracing_enabling Enabling using CMake
537 With the sources of SimGrid, it is possible to enable the tracing
538 using the parameter <b>-Denable_tracing=ON</b> when the cmake is executed.
539 The section \ref tracing_tracing_functions describes all the functions available
540 when this Cmake options is activated. These functions will have no effect
541 if SimGrid is configured without this option (they are wiped-out by the
545 $ cmake -Denable_tracing=ON .
549 \subsection tracing_tracing_functions Tracing Functions
551 \li <b>\c TRACE_category (const char *category)</b>: This function should be used
552 to define a user category. The category can be used to differentiate the tasks
553 that are created during the simulation (for example, tasks from server1,
554 server2, or request tasks, computation tasks, communication tasks).
555 All resource utilization (host power and link bandwidth) will be
556 classified according to the task category. Tasks that do not belong to a
557 category are not traced. The color for the category that is being declared
558 is random (use next function to specify a color).
560 \li <b>\c TRACE_category_with_color (const char *category, const char *color)</b>: Same
561 as TRACE_category, but let user specify a color encoded as a RGB-like string with
562 three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
563 color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
565 \li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
566 This function should be called after the creation of a MSG task, to define the
567 category of that task. The first parameter \c task must contain a task that was
568 created with the function \c MSG_task_create. The second parameter
569 \c category must contain a category that was previously defined by the function
572 \li <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
573 This function should be called after the creation of a SimDAG task, to define the
574 category of that task. The first parameter \c task must contain a task that was
575 created with the function \c MSG_task_create. The second parameter
576 \c category must contain a category that was previously defined by the function
579 \li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
580 Declare a user variable that will be associated to host/link. A variable can
581 be used to trace user variables such as the number of tasks in a server,
582 the number of clients in an application (for hosts), and so on.
584 \li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
585 Set the value of a given user variable for a given host/link. The value
586 of this variable is always associated to the host/link. The host/link
587 parameters should be its name as the one listed in the platform file.
589 \li <b>\c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value)</b>:
590 Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
591 the time used to trace it. Users can specify a time that is not the
592 simulated clock time as defined by the core simulator. This allows
593 a fine-grain control of time definition, but should be used with
594 caution since the trace can be inconsistent if resource utilization
595 traces are also traced.
597 \li <b>\c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value)</b>:
598 Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
599 destination hosts (as the names from the platform file). The tracing library
600 will get the corresponding route that connects those two hosts (src and dst) and
601 [set|add|sub] the value's variable for all the links of the route.
603 \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>:
604 Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
606 \subsection tracing_tracing_options Tracing configuration Options
608 These are the options accepted by the tracing system of SimGrid:
613 Safe switch. It activates (or deactivates) the tracing system.
614 No other tracing options take effect if this one is not activated.
619 Register the simulation platform in the trace file.
624 By default, the tracing system uses all routes in the platform file
625 to re-create a "graph" of the platform and register it in the trace file.
626 This option let the user tell the tracing system to use only the routes
627 that are composed with just one link.
632 It activates the categorized resource utilization tracing. It should
633 be enabled if tracing categories are used by this simulator.
636 tracing/uncategorized
638 It activates the uncategorized resource utilization tracing. Use it if
639 this simulator do not use tracing categories and resource use have to be
645 A file with this name will be created to register the simulation. The file
646 is in the Paje format and can be analyzed using Triva or Paje visualization
647 tools. More information can be found in these webpages:
648 <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
649 <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
654 This option only has effect if this simulator is SMPI-based. Traces the MPI
655 interface and generates a trace that can be analyzed using Gantt-like
656 visualizations. Every MPI function (implemented by SMPI) is transformed in a
657 state, and point-to-point communications can be analyzed with arrows.
662 This option only has effect if this simulator is SMPI-based. The processes
663 are grouped by the hosts where they were executed.
668 This option only has effect if this simulator is MSG-based. It traces the
669 behavior of all categorized MSG tasks, grouping them by hosts.
674 This option only has effect if this simulator is MSG-based. It traces the
675 behavior of all categorized MSG processes, grouping them by hosts. This option
676 can be used to track process location if this simulator has process migration.
680 triva/categorized:graph_categorized.plist
682 This option generates a graph configuration file for Triva considering
683 categorized resource utilization.
686 triva/uncategorized:graph_uncategorized.plist
688 This option generates a graph configuration file for Triva considering
689 uncategorized resource utilization.
691 \subsection tracing_tracing_example Example of Instrumentation
693 A simplified example using the tracing mandatory functions.
696 int main (int argc, char **argv)
698 MSG_global_init (&argc, &argv);
700 //(... after deployment ...)
702 //note that category declaration must be called after MSG_create_environment
703 TRACE_category_with_color ("request", "1 0 0");
704 TRACE_category_with_color ("computation", "0.3 1 0.4");
705 TRACE_category ("finalize");
707 m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
708 m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
709 m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
710 m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
711 TRACE_msg_set_task_category (req1, "request");
712 TRACE_msg_set_task_category (req2, "request");
713 TRACE_msg_set_task_category (req3, "request");
714 TRACE_msg_set_task_category (req4, "request");
716 m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
717 TRACE_msg_set_task_category (comp, "computation");
719 m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
720 TRACE_msg_set_task_category (finalize, "finalize");
729 \subsection tracing_tracing_analyzing Analyzing the SimGrid Traces
731 The SimGrid library, during an instrumented simulation, creates a trace file in
732 the Paje file format that contains the platform utilization for the simulation
733 that was executed. The visualization analysis of this file is performed with the
734 visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
735 special configurations tunned to SimGrid needs. This part of the documentation
736 explains how to configure and use Triva to analyse a SimGrid trace file.
738 - <b>Installing Triva</b>: the tool is available in the INRIAGforge,
739 at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
740 Use the following command to get the sources, and then check the file
741 <i>INSTALL</i>. This file contains instructions to install
742 the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
743 be compiled in MacOSes natively, check <i>INSTALL.mac</i> file.
745 $ svn checkout svn://scm.gforge.inria.fr/svn/triva
750 - <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
751 installation (you can execute it passing <em>--help</em> to check its
752 options). If the triva binary is not available after following the
753 installation instructions, you may want to execute the following command to
754 initialize the GNUstep environment variables. We strongly recommend that you
755 use the latest GNUstep packages, and not the packages available through apt-get
756 in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
757 available packages, you can execute this command:
759 $ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
761 You should be able to see this output after the installation of triva:
763 $ ./Triva.app/Triva --help
764 Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
765 Trace Analysis through Visualization
768 --ti_frequency {double} Animation: frequency of updates
769 --ti_hide Hide the TimeInterval window
770 --ti_forward {double} Animation: value to move time-slice
771 --ti_apply Apply the configuration
772 --ti_update Update on slider change
773 --ti_animate Start animation
774 --ti_start {double} Start of time slice
775 --ti_size {double} Size of time slice
777 --comparison Compare Trace Files (Experimental)
778 --graph Configurable Graph
779 --list Print Trace Type Hierarchy
780 --hierarchy Export Trace Type Hierarchy (dot)
781 --stat Trace Statistics and Memory Utilization
782 --instances List All Trace Entities
783 --linkview Link View (Experimental)
784 --treemap Squarified Treemap
785 --merge Merge Trace Files (Experimental)
786 --check Check Trace File Integrity
788 --gc_conf {file} Graph Configuration in Property List Format
789 --gc_apply Apply the configuration
790 --gc_hide Hide the GraphConfiguration window
792 Triva expects that the user choose one of the available options
793 (currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
794 and the trace file from the simulation.
796 - <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
797 the tool always takes into account the concept of the <em>time-slice</em>.
798 This concept means that what is being visualized in the screen is always
799 calculated considering a specific time frame, with its beggining and end
800 timestamp. The time-slice is configured by the user and can be changed
801 dynamically through the window called <em>Time Interval</em> that is opened
802 whenever a trace file is being analyzed. The next figure depicts the time-slice
803 configuration window.
804 In the top of the window, in the space named <i>Trace Time</i>,
805 the two fields show the beggining of the trace (which usually starts in 0) and
806 the end (that depends on the time simulated by SimGrid). The middle of the
807 window, in the square named <i>Time Slice Configuration</i>, contains the
808 aspects related to the time-slice, including its <i>start</i> and its
809 <i>size</i>. The gray rectangle in the bottom of this part indicates the
810 <i>current time-slice</i> that is considered for the drawings. If the checkbox
811 <i>Update Drawings on Sliders Change</i> is not selected, the button
812 <i>Apply</i> must be clicked in order to inform triva that the
813 new time-slice must be considered. The bottom part of the window, in the space
814 indicated by the square <i>Time Slice Animation</i> can be used to advance
815 the time-frame automatically. The user configures the amount of time that the
816 time-frame will forward and how frequent this update will happen. Once this is
817 configured, the user clicks the <i>Play</i> button in order to see the dynamic
818 changes on the drawings.
821 <a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
824 <b>Remarks:</b> when the trace has too many hosts or links, the computation to
825 take into account a new time-slice can be expensive. When this happens, the
826 <i>Frequency</i> parameter, but also updates caused by change on configurations
827 when the checkbox <i>Update Drawings on Sliders
828 Change</i> is selected will not be followed.
830 - <b>Understanding Triva - graph</b>: this part of the documention explains how
831 to analyze the traces using the graph view of Triva, when the user executes
832 the tool passing <em>--graph</em> as parameter. Triva opens three windows when
833 this parameter is used: the <i>Time Interval</i> window (previously described),
834 the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
835 window. The Graph Representation is the window where drawings take place.
836 Initially, it is completely white waiting for a proper graph configuration input
837 by the user. We start the description of this type of analysis by describing the
838 <i>Graph Configuration</i> window (depicted below). By using a particular
840 can be used to customize the graph drawing according to
841 the SimGrid trace that was created with user-specific categories. Before delving
842 into the details of this customization, let us first explain the major parts of
843 the graph configuration window. The buttons located in the top-right corner can
844 be used to delete, copy and create a new configuration. The checkbox in the
845 top-middle part of the window indicates if the configuration typed in the
846 textfield is syntactically correct (we are using the non-XML
847 <a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
848 describe the configuration). The pop-up button located on the top-left corner
849 indicates the selected configuration (the user can have multiple graph
850 configurations). The bottom-left text field contains the name of the current
851 configuration (updates on this field must be followed by typing enter on the
852 keyboard to take into account the name change). The bottom-right <em>Apply</em>
853 button activates the current configuration, resulting on an update on the graph
857 <a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
860 <b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
861 basic configuration that should be used during the analysis of a SimGrid trace
862 file. The basic logic of the configuration is as follows:
868 The nodes of the graph will be created based on the <i>node</i> parameter, which
869 in this case is the different <em>"HOST"</em>s of the platform
870 used to simulate. The <i>edge</i> parameter indicates that the edges of the
871 graph will be created based on the <em>"LINK"</em>s of the platform. After the
872 definition of these two parameters, the configuration must detail how
873 <em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
874 must have an entry for each of the types used. For <em>HOST</em>, as basic
875 configuration, we have:
882 The parameter <em>size</em> indicates which variable from the trace file will be
883 used to define the size of the node HOST in the visualization. If the simulation
884 was executed with availability traces, the size of the nodes will be changed
885 according to these traces. The parameter <em>scale</em> indicates if the value
886 of the variable is <em>global</em> or <em>local</em>. If it is global, the value
887 will be relative to the power of all other hosts, if it is local, the value will
889 For <em>LINK</em> we have:
899 For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
900 the configuration must contain two additional parameters: <em>src</em> and
901 <em>dst</em> that are used to properly identify which nodes this edge is
902 connecting. The values <em>source</em> and <em>destination</em> are always present
903 in the SimGrid trace file and should not be changed in the configuration. The
904 parameter <em>size</em> for the LINK, in this case, is configured as the
905 variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
906 here is exactly the same used for nodes. The last parameter is the GraphViz
907 algorithm used to calculate the position of the nodes in the graph
910 graphviz-algorithm = neato;
913 <b>Customizing the Graph Representation</b>: triva is capable to handle
914 a customized graph representation based on the variables present in the trace
915 file. In the case of SimGrid, every time a category is created for tasks, two
916 variables in the trace file are defined: one to indicate node utilization (how
917 much power was used by that task category), and another to indicate link
918 utilization (how much bandwidth was used by that category). For instance, if the
919 user declares a category named <i>request</i>, there will be variables named
920 <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
921 <b>b</b> for bandwidth). It is important to notice that the variable
922 <i>prequest</i> in this case is only available for HOST, and
923 <i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
924 two categories for tasks: request and compute. To create a customized graph
925 representation with a proportional separation of host and link utilization, use
926 as configuration for HOST and LINK this:
935 values = (prequest, pcomputation);
948 values = (brequest, bcomputation);
952 Where <i>sep_host</i> contains a composition of type <i>separation</i> where
953 its max size is the <i>power</i> of the host and the variables <i>prequest</i>
954 and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
955 <i>sep_link</i> is also a separation where max is defined as the
956 <i>bandwidth</i> of the link, and the variables <i>brequest</i> and
957 <i>bcomputation</i> are drawn proportionally within a LINK.
958 <i>This configuration enables the analysis of resource utilization by MSG tasks,
959 and the identification of load-balancing issues, network bottlenecks, for
961 <b>Other compositions</b>: besides <i>separation</i>, it is possible to use
962 other types of compositions, such as gradients, and colors, like this:
967 values = (numberOfTasks);
971 values = (is_server);
974 Where <i>gra_host</i> creates a gradient within a node of the graph, using a
975 global scale and using as value a variable called <i>numberOfTasks</i>, that
976 could be declared by the user using the optional tracing functions of SimGrid.
977 If scale is global, the max and min value for the gradient will be equal to the
978 max and min numberOfTasks among all hosts, and if scale is local, the max and
979 min value based on the value of numberOfTasks locally in each host.
980 And <i>color_host</i> composition draws a square based on a positive value of
981 the variable <i>is_server</i>, that could also be defined by the user using the
982 SimGrid tracing functions. \n
983 <b>The Graph Visualization</b>: The next figure shows a graph visualization of a
984 given time-slice of the masterslave_forwarder example (present in the SimGrid
985 sources). The red color indicates tasks from the <i>compute</i> category. This
986 visualization was generated with the following configuration:
999 values = (pcompute, pfinalize);
1011 values = (bcompute, bfinalize);
1014 graphviz-algorithm = neato;
1019 <a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
1023 - <b>Understading Triva - colors</b>: An important issue when using Triva is how
1024 to define colors. To do that, we have to know which variables are defined in
1025 the trace file generated by the SimGrid library. The parameter <em>--list</em>
1026 lists the variables for a given trace file:
1028 $ Triva -l masterslave_forwarder.trace
1046 We can see that HOST has seven variables (from power to pfinalize) and LINK has
1047 four (from bandwidth to bfinalize). To define a red color for the
1048 <i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
1049 <i>compute</i>), execute:
1051 $ defaults write Triva 'pcompute Color' '1 0 0'
1052 $ defaults write Triva 'bcompute Color' '1 0 0'
1054 Where the three numbers in each line are the RGB color with values from 0 to 1.
1061 values = (bcompute, bfinalize);
1064 graphviz-algorithm = neato;
1069 <a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
1073 - <b>Understading Triva - colors</b>: An important issue when using Triva is how
1074 to define colors. To do that, we have to know which variables are defined in
1075 the trace file generated by the SimGrid library. The parameter <em>--list</em>
1076 lists the variables for a given trace file:
1078 $ Triva -l masterslave_forwarder.trace
1096 We can see that HOST has seven variables (from power to pfinalize) and LINK has
1097 four (from bandwidth to bfinalize). To define a red color for the
1098 <i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
1099 <i>compute</i>), execute:
1101 $ defaults write Triva 'pcompute Color' '1 0 0'
1102 $ defaults write Triva 'bcompute Color' '1 0 0'
1104 Where the three numbers in each line are the RGB color with values from 0 to 1.