doc/tracing.doc

   1 /*! \page tracing Tracing Simulations for Visualization
   2
   3 \htmlinclude .tracing.doc.toc
   4
   5 \section tracing_tracing Tracing Simulations for Visualization
   6
   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.
  16
  17 \subsection tracing_tracing_howitworks How it works
  18
  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.
  25
  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.
  34
  35 \subsection tracing_tracing_enabling Enabling using CMake
  36
  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
  42 C-preprocessor).
  43
  44 \verbatim
  45 $ cmake -Denable_tracing=ON .
  46 $ make
  47 \endverbatim
  48
  49 \subsection tracing_tracing_functions Tracing Functions
  50
  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).
  59
  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.
  64
  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
  70 \c TRACE_category.
  71
  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
  77 \c TRACE_category.
  78
  79 \li <b>\c TRACE_declare_mark(const char *mark_type)</b>: This function
  80 declares a new Paje event type in the trace file that can be used by
  81 simulators to declare application-level marks. This function is
  82 independent of which API is used in SimGrid.
  83
  84 \li <b>\c TRACE_mark(const char *mark_type, const char *mark_value)</b>:
  85 This function creates a mark in the trace file. The first parameter
  86 had to be previously declared using \c TRACE_declare_mark, the second
  87 is the identifier for this mark instance. We recommend that the \c
  88 mark_value (the second parameter) is a unique value for the whole
  89 trace file (the whole simulation). Nevertheless, this is not a strong
  90 requirement: the trace will be valid if there are multiple mark
  91 identifiers for the same trace.
  92
  93 \li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
  94 Declare a user variable that will be associated to host/link. A variable can
  95 be used to trace user variables such as the number of tasks in a server,
  96 the number of clients in an application (for hosts), and so on.
  97
  98 \li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
  99 Set the value of a given user variable for a given host/link. The value
 100 of this variable is always associated to the host/link. The host/link
 101 parameters should be its name as the one listed in the platform file.
 102
 103 \li <b>\c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value)</b>:
 104 Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
 105 the time used to trace it. Users can specify a time that is not the
 106 simulated clock time as defined by the core simulator. This allows
 107 a fine-grain control of time definition, but should be used with
 108 caution since the trace can be inconsistent if resource utilization
 109 traces are also traced.
 110
 111 \li <b>\c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value)</b>:
 112 Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
 113 destination hosts (as the names from the platform file). The tracing library
 114 will get the corresponding route that connects those two hosts (src and dst) and
 115 [set|add|sub] the value's variable for all the links of the route.
 116
 117 \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>:
 118 Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
 119
 120 \subsection tracing_tracing_options Tracing configuration Options
 121
 122 To check which tracing options are available for your simulator, you
 123 can just run it with the option <b>--help-tracing</b>. These are the
 124 options accepted by the tracing system of SimGrid as of today, you
 125 can use them by running your simulator with the <b>--cfg=</b> switch:
 126
 127 \li <b>\c
 128 tracing
 129 </b>:
 130   Safe switch. It activates (or deactivates) the tracing system.
 131   No other tracing options take effect if this one is not activated.
 132 \verbatim
 133 --cfg=tracing:1
 134 \endverbatim
 135
 136 \li <b>\c
 137 tracing/categorized
 138 </b>:
 139   It activates the categorized resource utilization tracing. It should
 140   be enabled if tracing categories are used by this simulator.
 141 \verbatim
 142 --cfg=tracing/categorized:1
 143 \endverbatim
 144
 145 \li <b>\c
 146 tracing/uncategorized
 147 </b>:
 148   It activates the uncategorized resource utilization tracing. Use it if
 149   this simulator do not use tracing categories and resource use have to be
 150   traced.
 151 \verbatim
 152 --cfg=tracing/uncategorized:1
 153 \endverbatim
 154
 155 \li <b>\c
 156 tracing/filename
 157 </b>:
 158   A file with this name will be created to register the simulation. The file
 159   is in the Paje format and can be analyzed using Triva or Paje visualization
 160   tools. More information can be found in these webpages:
 161      <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
 162      <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
 163 \verbatim
 164 --cfg=tracing/filename:mytracefile.trace
 165 \endverbatim
 166   If you do not provide this parameter, the trace file will be named simgrid.trace.
 167
 168 \li <b>\c
 169 tracing/onelink_only
 170 </b>:
 171   By default, the tracing system uses all routes in the platform file
 172   to re-create a "graph" of the platform and register it in the trace file.
 173   This option let the user tell the tracing system to use only the routes
 174   that are composed with just one link.
 175 \verbatim
 176 --cfg=tracing/onelink_only:1
 177 \endverbatim
 178
 179 \li <b>\c
 180 tracing/smpi
 181 </b>:
 182   This option only has effect if this simulator is SMPI-based. Traces the MPI
 183   interface and generates a trace that can be analyzed using Gantt-like
 184   visualizations. Every MPI function (implemented by SMPI) is transformed in a
 185   state, and point-to-point communications can be analyzed with arrows.
 186 \verbatim
 187 --cfg=tracing/smpi:1
 188 \endverbatim
 189
 190 \li <b>\c
 191 tracing/smpi/group
 192 </b>:
 193   This option only has effect if this simulator is SMPI-based. The processes
 194   are grouped by the hosts where they were executed.
 195 \verbatim
 196 --cfg=tracing/smpi/group:1
 197 \endverbatim
 198
 199 \li <b>\c
 200 tracing/msg/task
 201 </b>:
 202   This option only has effect if this simulator is MSG-based. It traces the
 203   behavior of all categorized MSG tasks, grouping them by hosts.
 204 \verbatim
 205 --cfg=tracing/msg/task:1
 206 \endverbatim
 207
 208 \li <b>\c
 209 tracing/msg/process
 210 </b>:
 211   This option only has effect if this simulator is MSG-based. It traces the
 212   behavior of all categorized MSG processes, grouping them by hosts. This option
 213   can be used to track process location if this simulator has process migration.
 214 \verbatim
 215 --cfg=tracing/msg/process:1
 216 \endverbatim
 217
 218 \li <b>\c
 219 triva/categorized
 220 </b>:
 221   This option generates a graph configuration file for Triva considering
 222   categorized resource utilization.
 223 \verbatim
 224 --cfg=triva/categorized:graph_categorized.plist
 225 \endverbatim
 226
 227 \li <b>\c
 228 triva/uncategorized
 229 </b>:
 230   This option generates a graph configuration file for Triva considering
 231   uncategorized resource utilization.
 232 \verbatim
 233 --cfg=triva/categorized:graph_uncategorized.plist
 234 \endverbatim
 235
 236 \subsection tracing_tracing_example_parameters Case studies
 237
 238 Some scenarios that might help you decide which tracing options
 239 you should use to analyze your simulator.
 240
 241 \li I want to trace the resource utilization of all hosts
 242 and links of the platform, and my simulator <b>does not</b> use
 243 the tracing API. For that, you can run a uncategorized trace
 244 with the following parameters (it will work with <b>any</b> Simgrid
 245 simulator):
 246 \verbatim
 247 ./your_simulator \
 248           --cfg=tracing:1 \
 249           --cfg=tracing/uncategorized:1 \
 250           --cfg=tracing/filename:mytracefile.trace \
 251           --cfg=triva/uncategorized:uncat.plist
 252 \endverbatim
 253
 254 \li I want to trace only a subset of my MSG (or SimDAG) tasks.
 255 For that, you will need to create tracing categories using the
 256 <b>TRACE_category (...)</b> function (as explained above),
 257 and then classify your tasks to a previously declared category
 258 using the <b>TRACE_msg_set_task_category (...)</b>
 259 (or <b>TRACE_sd_set_task_category (...)</b> for SimDAG tasks). After
 260 recompiling, run your simulator with the following parameters:
 261 \verbatim
 262 ./your_simulator \
 263           --cfg=tracing:1 \
 264           --cfg=tracing/categorized:1 \
 265           --cfg=tracing/filename:mytracefile.trace \
 266           --cfg=triva/categorized:cat.plist
 267 \endverbatim
 268
 269
 270 \subsection tracing_tracing_example Example of Instrumentation
 271
 272 A simplified example using the tracing mandatory functions.
 273
 274 \verbatim
 275 int main (int argc, char **argv)
 276 {
 277   MSG_global_init (&argc, &argv);
 278
 279   //(... after deployment ...)
 280
 281   //note that category declaration must be called after MSG_create_environment
 282   TRACE_category_with_color ("request", "1 0 0");
 283   TRACE_category_with_color ("computation", "0.3 1 0.4");
 284   TRACE_category ("finalize");
 285
 286   m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
 287   m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
 288   m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
 289   m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
 290   TRACE_msg_set_task_category (req1, "request");
 291   TRACE_msg_set_task_category (req2, "request");
 292   TRACE_msg_set_task_category (req3, "request");
 293   TRACE_msg_set_task_category (req4, "request");
 294
 295   m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
 296   TRACE_msg_set_task_category (comp, "computation");
 297
 298   m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
 299   TRACE_msg_set_task_category (finalize, "finalize");
 300
 301   //(...)
 302
 303   MSG_clean();
 304   return 0;
 305 }
 306 \endverbatim
 307
 308 \subsection tracing_tracing_analyzing Analyzing the SimGrid Traces
 309
 310 The SimGrid library, during an instrumented simulation, creates a trace file in
 311 the Paje file format that contains the platform utilization for the simulation
 312 that was executed. The visualization analysis of this file is performed with the
 313 visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
 314 special configurations tunned to SimGrid needs. This part of the documentation
 315 explains how to configure and use Triva to analyse a SimGrid trace file.
 316
 317 - <b>Installing Triva</b>: the tool is available in the INRIAGforge,
 318 at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
 319 Use the following command to get the sources, and then check the file
 320 <i>INSTALL</i>. This file contains instructions to install
 321 the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
 322 be compiled in MacOSes natively, check <i>INSTALL.mac</i> file.
 323 \verbatim
 324 $ svn checkout svn://scm.gforge.inria.fr/svn/triva
 325 $ cd triva
 326 $ cat INSTALL
 327 \endverbatim
 328
 329 - <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
 330   installation (you can execute it passing <em>--help</em> to check its
 331 options). If the triva binary is not available after following the
 332 installation instructions, you may want to execute the following command to
 333 initialize the GNUstep environment variables. We strongly recommend that you
 334 use the latest GNUstep packages, and not the packages available through apt-get
 335 in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
 336 available packages, you can execute this command:
 337 \verbatim
 338 $ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
 339 \endverbatim
 340 You should be able to see this output after the installation of triva:
 341 \verbatim
 342 $ ./Triva.app/Triva --help
 343 Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
 344 Trace Analysis through Visualization
 345
 346 TimeInterval
 347     --ti_frequency {double}    Animation: frequency of updates
 348     --ti_hide                  Hide the TimeInterval window
 349     --ti_forward {double}      Animation: value to move time-slice
 350     --ti_apply                 Apply the configuration
 351     --ti_update                Update on slider change
 352     --ti_animate               Start animation
 353     --ti_start {double}        Start of time slice
 354     --ti_size {double}         Size of time slice
 355 Triva
 356     --comparison               Compare Trace Files (Experimental)
 357     --graph                    Configurable Graph
 358     --list                     Print Trace Type Hierarchy
 359     --hierarchy                Export Trace Type Hierarchy (dot)
 360     --stat                     Trace Statistics and Memory Utilization
 361     --instances                List All Trace Entities
 362     --linkview                 Link View (Experimental)
 363     --treemap                  Squarified Treemap
 364     --merge                    Merge Trace Files (Experimental)
 365     --check                    Check Trace File Integrity
 366 GraphConfiguration
 367     --gc_conf {file}           Graph Configuration in Property List Format
 368     --gc_apply                 Apply the configuration
 369     --gc_hide                  Hide the GraphConfiguration window
 370 \endverbatim
 371 Triva expects that the user choose one of the available options
 372 (currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
 373 and the trace file from the simulation.
 374
 375 - <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
 376   the tool always takes into account the concept of the <em>time-slice</em>.
 377 This concept means that what is being visualized in the screen is always
 378 calculated considering a specific time frame, with its beggining and end
 379 timestamp. The time-slice is configured by the user and can be changed
 380 dynamically through the window called <em>Time Interval</em> that is opened
 381 whenever a trace file is being analyzed. The next figure depicts the time-slice
 382 configuration window.
 383 In the top of the window, in the space named <i>Trace Time</i>,
 384 the two fields show the beggining of the trace (which usually starts in 0) and
 385 the end (that depends on the time simulated by SimGrid). The middle of the
 386 window, in the square named <i>Time Slice Configuration</i>, contains the
 387 aspects related to the time-slice, including its <i>start</i> and its
 388 <i>size</i>. The gray rectangle in the bottom of this part indicates the
 389 <i>current time-slice</i> that is considered for the drawings. If the checkbox
 390 <i>Update Drawings on Sliders Change</i> is not selected, the button
 391 <i>Apply</i> must be clicked in order to inform triva that the
 392 new time-slice must be considered. The bottom part of the window, in the space
 393 indicated by the square <i>Time Slice Animation</i> can be used to advance
 394 the time-frame automatically. The user configures the amount of time that the
 395 time-frame will forward and how frequent this update will happen. Once this is
 396 configured, the user clicks the <i>Play</i> button in order to see the dynamic
 397 changes on the drawings.
 398 <center>
 399 \htmlonly
 400 <a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
 401 \endhtmlonly
 402 </center>
 403 <b>Remarks:</b> when the trace has too many hosts or links, the computation to
 404 take into account a new time-slice can be expensive. When this happens, the
 405 <i>Frequency</i> parameter, but also updates caused by change on configurations
 406 when the checkbox <i>Update Drawings on Sliders
 407 Change</i> is selected will not be followed.
 408
 409 - <b>Understanding Triva - graph</b>: this part of the documention explains how
 410   to analyze the traces using the graph view of Triva, when the user executes
 411 the tool passing <em>--graph</em> as parameter. Triva opens three windows when
 412 this parameter is used: the <i>Time Interval</i> window (previously described),
 413 the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
 414 window. The Graph Representation is the window where drawings take place.
 415 Initially, it is completely white waiting for a proper graph configuration input
 416 by the user. We start the description of this type of analysis by describing the
 417 <i>Graph Configuration</i> window (depicted below). By using a particular
 418 configuration, triva
 419 can be used to customize the graph drawing according to
 420 the SimGrid trace that was created with user-specific categories. Before delving
 421 into the details of this customization, let us first explain the major parts of
 422 the graph configuration window. The buttons located in the top-right corner can
 423 be used to delete, copy and create a new configuration. The checkbox in the
 424 top-middle part of the window indicates if the configuration typed in the
 425 textfield is syntactically correct (we are using the non-XML
 426 <a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
 427 describe the configuration). The pop-up button located on the top-left corner
 428 indicates the selected configuration (the user can have multiple graph
 429 configurations). The bottom-left text field contains the name of the current
 430 configuration (updates on this field must be followed by typing enter on the
 431 keyboard to take into account the name change). The bottom-right <em>Apply</em>
 432 button activates the current configuration, resulting on an update on the graph
 433 drawings.
 434 <center>
 435 \htmlonly
 436 <a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
 437 \endhtmlonly
 438 </center>
 439 <b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
 440 basic configuration that should be used during the analysis of a SimGrid trace
 441 file. The basic logic of the configuration is as follows:
 442 \verbatim
 443 {
 444   node = (HOST);
 445   edge = (LINK);
 446 \endverbatim
 447 The nodes of the graph will be created based on the <i>node</i> parameter, which
 448 in this case is the different <em>"HOST"</em>s of the platform
 449 used to simulate. The <i>edge</i> parameter indicates that the edges of the
 450 graph will be created based on the <em>"LINK"</em>s of the platform. After the
 451 definition of these two parameters, the configuration must detail how
 452 <em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
 453 must have an entry for each of the types used. For <em>HOST</em>, as basic
 454 configuration, we have:
 455 \verbatim
 456   HOST = {
 457     size = power;
 458     scale = global;
 459   };
 460 \endverbatim
 461 The parameter <em>size</em> indicates which variable from the trace file will be
 462 used to define the size of the node HOST in the visualization. If the simulation
 463 was executed with availability traces, the size of the nodes will be changed
 464 according to these traces. The parameter <em>scale</em> indicates if the value
 465 of the variable is <em>global</em> or <em>local</em>. If it is global, the value
 466 will be relative to the power of all other hosts, if it is local, the value will
 467 be relative locally.
 468 For <em>LINK</em> we have:
 469 \verbatim
 470   LINK = {
 471     src = source;
 472     dst = destination;
 473
 474     size = bandwidth;
 475     scale = global;
 476   };
 477 \endverbatim
 478 For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
 479 the configuration must contain two additional parameters: <em>src</em> and
 480 <em>dst</em> that are used to properly identify which nodes this edge is
 481 connecting. The values <em>source</em> and <em>destination</em> are always present
 482 in the SimGrid trace file and should not be changed in the configuration. The
 483 parameter <em>size</em> for the LINK, in this case, is configured as the
 484 variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
 485 here is exactly the same used for nodes. The last parameter is the GraphViz
 486 algorithm used to calculate the position of the nodes in the graph
 487 representation.
 488 \verbatim
 489   graphviz-algorithm = neato;
 490 }
 491 \endverbatim
 492 <b>Customizing the Graph Representation</b>: triva is capable to handle
 493 a customized graph representation based on the variables present in the trace
 494 file. In the case of SimGrid, every time a category is created for tasks, two
 495 variables in the trace file are defined: one to indicate node utilization (how
 496 much power was used by that task category), and another to indicate link
 497 utilization (how much bandwidth was used by that category). For instance, if the
 498 user declares a category named <i>request</i>, there will be variables named
 499 <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
 500 <b>b</b> for bandwidth). It is important to notice that the variable
 501 <i>prequest</i> in this case is only available for HOST, and
 502 <i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
 503 two categories for tasks: request and compute. To create a customized graph
 504 representation with a proportional separation of host and link utilization, use
 505 as configuration for HOST and LINK this:
 506 \verbatim
 507   HOST = {
 508     size = power;
 509     scale = global;
 510
 511     sep_host = {
 512       type = separation;
 513       size = power;
 514       values = (prequest, pcomputation);
 515     };
 516   };
 517
 518   LINK = {
 519     src = source;
 520     dst = destination;
 521     size = bandwidth;
 522     scale = global;
 523
 524     sep_link = {
 525       type = separation;
 526       size = bandwidth;
 527       values = (brequest, bcomputation);
 528     };
 529   };
 530 \endverbatim
 531 Where <i>sep_host</i> contains a composition of type <i>separation</i> where
 532 its max size is the <i>power</i> of the host and the variables <i>prequest</i>
 533 and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
 534 <i>sep_link</i> is also a separation where max is defined as the
 535 <i>bandwidth</i> of the link, and the variables <i>brequest</i> and
 536 <i>bcomputation</i> are drawn proportionally within a LINK.
 537 <i>This configuration enables the analysis of resource utilization by MSG tasks,
 538 and the identification of load-balancing issues, network bottlenecks, for
 539 instance.</i> \n
 540 <b>Other compositions</b>: besides <i>separation</i>, it is possible to use
 541 other types of compositions, such as gradients, and colors, like this:
 542 \verbatim
 543     gra_host = {
 544       type = gradient;
 545       scale = global;
 546       values = (numberOfTasks);
 547     };
 548     color_host = {
 549       type = color;
 550       values = (is_server);
 551     };
 552 \endverbatim
 553 Where <i>gra_host</i> creates a gradient within a node of the graph, using a
 554 global scale and using as value a variable called <i>numberOfTasks</i>, that
 555 could be declared by the user using the optional tracing functions of SimGrid.
 556 If scale is global, the max and min value for the gradient will be equal to the
 557 max and min numberOfTasks among all hosts, and if scale is local, the max and
 558 min value based on the value of numberOfTasks locally in each host.
 559 And <i>color_host</i> composition draws a square based on a positive value of
 560 the variable <i>is_server</i>, that could also be defined by the user using the
 561 SimGrid tracing functions. \n
 562 <b>The Graph Visualization</b>: The next figure shows a graph visualization of a
 563 given time-slice of the masterslave_forwarder example (present in the SimGrid
 564 sources). The red color indicates tasks from the <i>compute</i> category. This
 565 visualization was generated with the following configuration:
 566 \verbatim
 567 {
 568   node = (HOST);
 569   edge = (LINK);
 570
 571   HOST = {
 572     size = power;
 573     scale = global;
 574
 575     sep_host = {
 576       type = separation;
 577       size = power;
 578       values = (pcompute, pfinalize);
 579     };
 580   };
 581   LINK = {
 582     src = source;
 583     dst = destination;
 584     size = bandwidth;\section tracing_tracing Tracing Simulations for Visualization
 585
 586 The trace visualization is widely used to observe and understand the behavior
 587 of parallel applications and distributed algorithms. Usually, this is done in a
 588 two-step fashion: the user instruments the application and the traces are
 589 analyzed after the end of the execution. The visualization itself can highlights
 590 unexpected behaviors, bottlenecks and sometimes can be used to correct
 591 distributed algorithms. The SimGrid team has instrumented the library
 592 in order to let users trace their simulations and analyze them. This part of the
 593 user manual explains how the tracing-related features can be enabled and used
 594 during the development of simulators using the SimGrid library.
 595
 596 \subsection tracing_tracing_howitworks How it works
 597
 598 For now, the SimGrid library is instrumented so users can trace the <b>platform
 599 utilization</b> using the MSG, SimDAG and SMPI interface. This means that the tracing will
 600 register how much power is used for each host and how much bandwidth is used for
 601 each link of the platform. The idea with this type of tracing is to observe the
 602 overall view of resources utilization in the first place, especially the
 603 identification of bottlenecks, load-balancing among hosts, and so on.
 604
 605 The idea of the tracing facilities is to give SimGrid users to possibility to
 606 classify MSG and SimDAG tasks by category, tracing the platform utilization
 607 (hosts and links) for each of the categories. For that,
 608 the tracing interface enables the declaration of categories and a function to
 609 mark a task with a previously declared category. <em>The tasks that are not
 610 classified according to a category are not traced</em>. Even if the user
 611 does not specify any category, the simulations can still be traced in terms
 612 of resource utilization by using a special parameter that is detailed below.
 613
 614 \subsection tracing_tracing_enabling Enabling using CMake
 615
 616 With the sources of SimGrid, it is possible to enable the tracing
 617 using the parameter <b>-Denable_tracing=ON</b> when the cmake is executed.
 618 The section \ref tracing_tracing_functions describes all the functions available
 619 when this Cmake options is activated. These functions will have no effect
 620 if SimGrid is configured without this option (they are wiped-out by the
 621 C-preprocessor).
 622
 623 \verbatim
 624 $ cmake -Denable_tracing=ON .
 625 $ make
 626 \endverbatim
 627
 628 \subsection tracing_tracing_functions Tracing Functions
 629
 630 \li <b>\c TRACE_category (const char *category)</b>: This function should be used
 631 to define a user category. The category can be used to differentiate the tasks
 632 that are created during the simulation (for example, tasks from server1,
 633 server2, or request tasks, computation tasks, communication tasks).
 634 All resource utilization (host power and link bandwidth) will be
 635 classified according to the task category. Tasks that do not belong to a
 636 category are not traced. The color for the category that is being declared
 637 is random (use next function to specify a color).
 638
 639 \li <b>\c TRACE_category_with_color (const char *category, const char *color)</b>: Same
 640 as TRACE_category, but let user specify a color encoded as a RGB-like string with
 641 three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
 642 color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
 643
 644 \li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
 645 This function should be called after the creation of a MSG task, to define the
 646 category of that task. The first parameter \c task must contain a task that was
 647 created with the function \c MSG_task_create. The second parameter
 648 \c category must contain a category that was previously defined by the function
 649 \c TRACE_category.
 650
 651 \li <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
 652 This function should be called after the creation of a SimDAG task, to define the
 653 category of that task. The first parameter \c task must contain a task that was
 654 created with the function \c MSG_task_create. The second parameter
 655 \c category must contain a category that was previously defined by the function
 656 \c TRACE_category.
 657
 658 \li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
 659 Declare a user variable that will be associated to host/link. A variable can
 660 be used to trace user variables such as the number of tasks in a server,
 661 the number of clients in an application (for hosts), and so on.
 662
 663 \li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
 664 Set the value of a given user variable for a given host/link. The value
 665 of this variable is always associated to the host/link. The host/link
 666 parameters should be its name as the one listed in the platform file.
 667
 668 \li <b>\c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value)</b>:
 669 Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
 670 the time used to trace it. Users can specify a time that is not the
 671 simulated clock time as defined by the core simulator. This allows
 672 a fine-grain control of time definition, but should be used with
 673 caution since the trace can be inconsistent if resource utilization
 674 traces are also traced.
 675
 676 \li <b>\c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value)</b>:
 677 Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
 678 destination hosts (as the names from the platform file). The tracing library
 679 will get the corresponding route that connects those two hosts (src and dst) and
 680 [set|add|sub] the value's variable for all the links of the route.
 681
 682 \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>:
 683 Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
 684
 685 \subsection tracing_tracing_options Tracing configuration Options
 686
 687 These are the options accepted by the tracing system of SimGrid:
 688
 689 \li <b>\c
 690 tracing
 691 </b>:
 692   Safe switch. It activates (or deactivates) the tracing system.
 693   No other tracing options take effect if this one is not activated.
 694
 695 \li <b>\c
 696 tracing/platform
 697 </b>:
 698   Register the simulation platform in the trace file.
 699
 700 \li <b>\c
 701 tracing/onelink_only
 702 </b>:
 703   By default, the tracing system uses all routes in the platform file
 704   to re-create a "graph" of the platform and register it in the trace file.
 705   This option let the user tell the tracing system to use only the routes
 706   that are composed with just one link.
 707
 708 \li <b>\c
 709 tracing/categorized
 710 </b>:
 711   It activates the categorized resource utilization tracing. It should
 712   be enabled if tracing categories are used by this simulator.
 713
 714 \li <b>\c
 715 tracing/uncategorized
 716 </b>:
 717   It activates the uncategorized resource utilization tracing. Use it if
 718   this simulator do not use tracing categories and resource use have to be
 719   traced.
 720
 721 \li <b>\c
 722 tracing/filename
 723 </b>:
 724   A file with this name will be created to register the simulation. The file
 725   is in the Paje format and can be analyzed using Triva or Paje visualization
 726   tools. More information can be found in these webpages:
 727      <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
 728      <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
 729
 730 \li <b>\c
 731 tracing/smpi
 732 </b>:
 733   This option only has effect if this simulator is SMPI-based. Traces the MPI
 734   interface and generates a trace that can be analyzed using Gantt-like
 735   visualizations. Every MPI function (implemented by SMPI) is transformed in a
 736   state, and point-to-point communications can be analyzed with arrows.
 737
 738 \li <b>\c
 739 tracing/smpi/group
 740 </b>:
 741   This option only has effect if this simulator is SMPI-based. The processes
 742   are grouped by the hosts where they were executed.
 743
 744 \li <b>\c
 745 tracing/msg/task
 746 </b>:
 747   This option only has effect if this simulator is MSG-based. It traces the
 748   behavior of all categorized MSG tasks, grouping them by hosts.
 749
 750 \li <b>\c
 751 tracing/msg/process
 752 </b>:
 753   This option only has effect if this simulator is MSG-based. It traces the
 754   behavior of all categorized MSG processes, grouping them by hosts. This option
 755   can be used to track process location if this simulator has process migration.
 756
 757
 758 \li <b>\c
 759 triva/categorized:graph_categorized.plist
 760 </b>:
 761   This option generates a graph configuration file for Triva considering
 762   categorized resource utilization.
 763
 764 \li <b>\c
 765 triva/uncategorized:graph_uncategorized.plist
 766 </b>:
 767   This option generates a graph configuration file for Triva considering
 768   uncategorized resource utilization.
 769
 770 \subsection tracing_tracing_example Example of Instrumentation
 771
 772 A simplified example using the tracing mandatory functions.
 773
 774 \verbatim
 775 int main (int argc, char **argv)
 776 {
 777   MSG_global_init (&argc, &argv);
 778
 779   //(... after deployment ...)
 780
 781   //note that category declaration must be called after MSG_create_environment
 782   TRACE_category_with_color ("request", "1 0 0");
 783   TRACE_category_with_color ("computation", "0.3 1 0.4");
 784   TRACE_category ("finalize");
 785
 786   m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
 787   m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
 788   m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
 789   m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
 790   TRACE_msg_set_task_category (req1, "request");
 791   TRACE_msg_set_task_category (req2, "request");
 792   TRACE_msg_set_task_category (req3, "request");
 793   TRACE_msg_set_task_category (req4, "request");
 794
 795   m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
 796   TRACE_msg_set_task_category (comp, "computation");
 797
 798   m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
 799   TRACE_msg_set_task_category (finalize, "finalize");
 800
 801   //(...)
 802
 803   MSG_clean();
 804   return 0;
 805 }
 806 \endverbatim
 807
 808 \subsection tracing_tracing_analyzing Analyzing the SimGrid Traces
 809
 810 The SimGrid library, during an instrumented simulation, creates a trace file in
 811 the Paje file format that contains the platform utilization for the simulation
 812 that was executed. The visualization analysis of this file is performed with the
 813 visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
 814 special configurations tunned to SimGrid needs. This part of the documentation
 815 explains how to configure and use Triva to analyse a SimGrid trace file.
 816
 817 - <b>Installing Triva</b>: the tool is available in the INRIAGforge,
 818 at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
 819 Use the following command to get the sources, and then check the file
 820 <i>INSTALL</i>. This file contains instructions to install
 821 the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
 822 be compiled in MacOSes natively, check <i>INSTALL.mac</i> file.
 823 \verbatim
 824 $ svn checkout svn://scm.gforge.inria.fr/svn/triva
 825 $ cd triva
 826 $ cat INSTALL
 827 \endverbatim
 828
 829 - <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
 830   installation (you can execute it passing <em>--help</em> to check its
 831 options). If the triva binary is not available after following the
 832 installation instructions, you may want to execute the following command to
 833 initialize the GNUstep environment variables. We strongly recommend that you
 834 use the latest GNUstep packages, and not the packages available through apt-get
 835 in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
 836 available packages, you can execute this command:
 837 \verbatim
 838 $ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
 839 \endverbatim
 840 You should be able to see this output after the installation of triva:
 841 \verbatim
 842 $ ./Triva.app/Triva --help
 843 Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
 844 Trace Analysis through Visualization
 845
 846 TimeInterval
 847     --ti_frequency {double}    Animation: frequency of updates
 848     --ti_hide                  Hide the TimeInterval window
 849     --ti_forward {double}      Animation: value to move time-slice
 850     --ti_apply                 Apply the configuration
 851     --ti_update                Update on slider change
 852     --ti_animate               Start animation
 853     --ti_start {double}        Start of time slice
 854     --ti_size {double}         Size of time slice
 855 Triva
 856     --comparison               Compare Trace Files (Experimental)
 857     --graph                    Configurable Graph
 858     --list                     Print Trace Type Hierarchy
 859     --hierarchy                Export Trace Type Hierarchy (dot)
 860     --stat                     Trace Statistics and Memory Utilization
 861     --instances                List All Trace Entities
 862     --linkview                 Link View (Experimental)
 863     --treemap                  Squarified Treemap
 864     --merge                    Merge Trace Files (Experimental)
 865     --check                    Check Trace File Integrity
 866 GraphConfiguration
 867     --gc_conf {file}           Graph Configuration in Property List Format
 868     --gc_apply                 Apply the configuration
 869     --gc_hide                  Hide the GraphConfiguration window
 870 \endverbatim
 871 Triva expects that the user choose one of the available options
 872 (currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
 873 and the trace file from the simulation.
 874
 875 - <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
 876   the tool always takes into account the concept of the <em>time-slice</em>.
 877 This concept means that what is being visualized in the screen is always
 878 calculated considering a specific time frame, with its beggining and end
 879 timestamp. The time-slice is configured by the user and can be changed
 880 dynamically through the window called <em>Time Interval</em> that is opened
 881 whenever a trace file is being analyzed. The next figure depicts the time-slice
 882 configuration window.
 883 In the top of the window, in the space named <i>Trace Time</i>,
 884 the two fields show the beggining of the trace (which usually starts in 0) and
 885 the end (that depends on the time simulated by SimGrid). The middle of the
 886 window, in the square named <i>Time Slice Configuration</i>, contains the
 887 aspects related to the time-slice, including its <i>start</i> and its
 888 <i>size</i>. The gray rectangle in the bottom of this part indicates the
 889 <i>current time-slice</i> that is considered for the drawings. If the checkbox
 890 <i>Update Drawings on Sliders Change</i> is not selected, the button
 891 <i>Apply</i> must be clicked in order to inform triva that the
 892 new time-slice must be considered. The bottom part of the window, in the space
 893 indicated by the square <i>Time Slice Animation</i> can be used to advance
 894 the time-frame automatically. The user configures the amount of time that the
 895 time-frame will forward and how frequent this update will happen. Once this is
 896 configured, the user clicks the <i>Play</i> button in order to see the dynamic
 897 changes on the drawings.
 898 <center>
 899 \htmlonly
 900 <a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
 901 \endhtmlonly
 902 </center>
 903 <b>Remarks:</b> when the trace has too many hosts or links, the computation to
 904 take into account a new time-slice can be expensive. When this happens, the
 905 <i>Frequency</i> parameter, but also updates caused by change on configurations
 906 when the checkbox <i>Update Drawings on Sliders
 907 Change</i> is selected will not be followed.
 908
 909 - <b>Understanding Triva - graph</b>: this part of the documention explains how
 910   to analyze the traces using the graph view of Triva, when the user executes
 911 the tool passing <em>--graph</em> as parameter. Triva opens three windows when
 912 this parameter is used: the <i>Time Interval</i> window (previously described),
 913 the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
 914 window. The Graph Representation is the window where drawings take place.
 915 Initially, it is completely white waiting for a proper graph configuration input
 916 by the user. We start the description of this type of analysis by describing the
 917 <i>Graph Configuration</i> window (depicted below). By using a particular
 918 configuration, triva
 919 can be used to customize the graph drawing according to
 920 the SimGrid trace that was created with user-specific categories. Before delving
 921 into the details of this customization, let us first explain the major parts of
 922 the graph configuration window. The buttons located in the top-right corner can
 923 be used to delete, copy and create a new configuration. The checkbox in the
 924 top-middle part of the window indicates if the configuration typed in the
 925 textfield is syntactically correct (we are using the non-XML
 926 <a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
 927 describe the configuration). The pop-up button located on the top-left corner
 928 indicates the selected configuration (the user can have multiple graph
 929 configurations). The bottom-left text field contains the name of the current
 930 configuration (updates on this field must be followed by typing enter on the
 931 keyboard to take into account the name change). The bottom-right <em>Apply</em>
 932 button activates the current configuration, resulting on an update on the graph
 933 drawings.
 934 <center>
 935 \htmlonly
 936 <a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
 937 \endhtmlonly
 938 </center>
 939 <b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
 940 basic configuration that should be used during the analysis of a SimGrid trace
 941 file. The basic logic of the configuration is as follows:
 942 \verbatim
 943 {
 944   node = (HOST);
 945   edge = (LINK);
 946 \endverbatim
 947 The nodes of the graph will be created based on the <i>node</i> parameter, which
 948 in this case is the different <em>"HOST"</em>s of the platform
 949 used to simulate. The <i>edge</i> parameter indicates that the edges of the
 950 graph will be created based on the <em>"LINK"</em>s of the platform. After the
 951 definition of these two parameters, the configuration must detail how
 952 <em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
 953 must have an entry for each of the types used. For <em>HOST</em>, as basic
 954 configuration, we have:
 955 \verbatim
 956   HOST = {
 957     size = power;
 958     scale = global;
 959   };
 960 \endverbatim
 961 The parameter <em>size</em> indicates which variable from the trace file will be
 962 used to define the size of the node HOST in the visualization. If the simulation
 963 was executed with availability traces, the size of the nodes will be changed
 964 according to these traces. The parameter <em>scale</em> indicates if the value
 965 of the variable is <em>global</em> or <em>local</em>. If it is global, the value
 966 will be relative to the power of all other hosts, if it is local, the value will
 967 be relative locally.
 968 For <em>LINK</em> we have:
 969 \verbatim
 970   LINK = {
 971     src = source;
 972     dst = destination;
 973
 974     size = bandwidth;
 975     scale = global;
 976   };
 977 \endverbatim
 978 For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
 979 the configuration must contain two additional parameters: <em>src</em> and
 980 <em>dst</em> that are used to properly identify which nodes this edge is
 981 connecting. The values <em>source</em> and <em>destination</em> are always present
 982 in the SimGrid trace file and should not be changed in the configuration. The
 983 parameter <em>size</em> for the LINK, in this case, is configured as the
 984 variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
 985 here is exactly the same used for nodes. The last parameter is the GraphViz
 986 algorithm used to calculate the position of the nodes in the graph
 987 representation.
 988 \verbatim
 989   graphviz-algorithm = neato;
 990 }
 991 \endverbatim
 992 <b>Customizing the Graph Representation</b>: triva is capable to handle
 993 a customized graph representation based on the variables present in the trace
 994 file. In the case of SimGrid, every time a category is created for tasks, two
 995 variables in the trace file are defined: one to indicate node utilization (how
 996 much power was used by that task category), and another to indicate link
 997 utilization (how much bandwidth was used by that category). For instance, if the
 998 user declares a category named <i>request</i>, there will be variables named
 999 <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
1000 <b>b</b> for bandwidth). It is important to notice that the variable
1001 <i>prequest</i> in this case is only available for HOST, and
1002 <i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
1003 two categories for tasks: request and compute. To create a customized graph
1004 representation with a proportional separation of host and link utilization, use
1005 as configuration for HOST and LINK this:
1006 \verbatim
1007   HOST = {
1008     size = power;
1009     scale = global;
1010
1011     sep_host = {
1012       type = separation;
1013       size = power;
1014       values = (prequest, pcomputation);
1015     };
1016   };
1017
1018   LINK = {
1019     src = source;
1020     dst = destination;
1021     size = bandwidth;
1022     scale = global;
1023
1024     sep_link = {
1025       type = separation;
1026       size = bandwidth;
1027       values = (brequest, bcomputation);
1028     };
1029   };
1030 \endverbatim
1031 Where <i>sep_host</i> contains a composition of type <i>separation</i> where
1032 its max size is the <i>power</i> of the host and the variables <i>prequest</i>
1033 and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
1034 <i>sep_link</i> is also a separation where max is defined as the
1035 <i>bandwidth</i> of the link, and the variables <i>brequest</i> and
1036 <i>bcomputation</i> are drawn proportionally within a LINK.
1037 <i>This configuration enables the analysis of resource utilization by MSG tasks,
1038 and the identification of load-balancing issues, network bottlenecks, for
1039 instance.</i> \n
1040 <b>Other compositions</b>: besides <i>separation</i>, it is possible to use
1041 other types of compositions, such as gradients, and colors, like this:
1042 \verbatim
1043     gra_host = {
1044       type = gradient;
1045       scale = global;
1046       values = (numberOfTasks);
1047     };
1048     color_host = {
1049       type = color;
1050       values = (is_server);
1051     };
1052 \endverbatim
1053 Where <i>gra_host</i> creates a gradient within a node of the graph, using a
1054 global scale and using as value a variable called <i>numberOfTasks</i>, that
1055 could be declared by the user using the optional tracing functions of SimGrid.
1056 If scale is global, the max and min value for the gradient will be equal to the
1057 max and min numberOfTasks among all hosts, and if scale is local, the max and
1058 min value based on the value of numberOfTasks locally in each host.
1059 And <i>color_host</i> composition draws a square based on a positive value of
1060 the variable <i>is_server</i>, that could also be defined by the user using the
1061 SimGrid tracing functions. \n
1062 <b>The Graph Visualization</b>: The next figure shows a graph visualization of a
1063 given time-slice of the masterslave_forwarder example (present in the SimGrid
1064 sources). The red color indicates tasks from the <i>compute</i> category. This
1065 visualization was generated with the following configuration:
1066 \verbatim
1067 {
1068   node = (HOST);
1069   edge = (LINK);
1070
1071   HOST = {
1072     size = power;
1073     scale = global;
1074
1075     sep_host = {
1076       type = separation;
1077       size = power;
1078       values = (pcompute, pfinalize);
1079     };
1080   };
1081   LINK = {
1082     src = source;
1083     dst = destination;
1084     size = bandwidth;
1085     scale = global;
1086
1087     sep_link = {
1088       type = separation;
1089       size = bandwidth;
1090       values = (bcompute, bfinalize);
1091     };
1092   };
1093   graphviz-algorithm = neato;
1094 }
1095 \endverbatim
1096 <center>
1097 \htmlonly
1098 <a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
1099 \endhtmlonly
1100 </center>
1101
1102 - <b>Understading Triva - colors</b>: An important issue when using Triva is how
1103   to define colors. To do that, we have to know which variables are defined in
1104 the trace file generated by the SimGrid library. The parameter <em>--list</em>
1105 lists the variables for a given trace file:
1106 \verbatim
1107 $ Triva -l masterslave_forwarder.trace
1108 iFile
1109 c  platform
1110 c    HOST
1111 v     power
1112 v     is_slave
1113 v     is_master
1114 v     task_creation
1115 v     task_computation
1116 v     pcompute
1117 v     pfinalize
1118 c    LINK
1119 v     bandwidth
1120 v     latency
1121 v     bcompute
1122 v     bfinalize
1123 c  user_type
1124 \endverbatim
1125 We can see that HOST has seven variables (from power to pfinalize) and LINK has
1126 four (from bandwidth to bfinalize). To define a red color for the
1127 <i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
1128 <i>compute</i>), execute:
1129 \verbatim
1130 $ defaults write Triva 'pcompute Color' '1 0 0'
1131 $ defaults write Triva 'bcompute Color' '1 0 0'
1132 \endverbatim
1133 Where the three numbers in each line are the RGB color with values from 0 to 1.
1134 \verbatim
1135     scale = global;
1136
1137     sep_link = {
1138       type = separation;
1139       size = bandwidth;
1140       values = (bcompute, bfinalize);
1141     };
1142   };
1143   graphviz-algorithm = neato;
1144 }
1145 \endverbatim
1146 <center>
1147 \htmlonly
1148 <a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
1149 \endhtmlonly
1150 </center>
1151
1152 - <b>Understading Triva - colors</b>: An important issue when using Triva is how
1153   to define colors. To do that, we have to know which variables are defined in
1154 the trace file generated by the SimGrid library. The parameter <em>--list</em>
1155 lists the variables for a given trace file:
1156 \verbatim
1157 $ Triva -l masterslave_forwarder.trace
1158 iFile
1159 c  platform
1160 c    HOST
1161 v     power
1162 v     is_slave
1163 v     is_master
1164 v     task_creation
1165 v     task_computation
1166 v     pcompute
1167 v     pfinalize
1168 c    LINK
1169 v     bandwidth
1170 v     latency
1171 v     bcompute
1172 v     bfinalize
1173 c  user_type
1174 \endverbatim
1175 We can see that HOST has seven variables (from power to pfinalize) and LINK has
1176 four (from bandwidth to bfinalize). To define a red color for the
1177 <i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
1178 <i>compute</i>), execute:
1179 \verbatim
1180 $ defaults write Triva 'pcompute Color' '1 0 0'
1181 $ defaults write Triva 'bcompute Color' '1 0 0'
1182 \endverbatim
1183 Where the three numbers in each line are the RGB color with values from 0 to 1.
1184
1185 */