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