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