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