doc/doxygen/tracing.doc

   1 /*! \page tracing Tracing Simulations
   2
   3
   4 Tracing is widely used to observe and understand the behavior of
   5 parallel applications and distributed algorithms. Usually, this is
   6 done in a two-step fashion: the user instruments the application and
   7 the traces are analyzed after the end of the execution. The analysis
   8 can highlights unexpected behaviors, bottlenecks and sometimes can be
   9 used to correct distributed algorithms. The SimGrid team has
  10 instrumented the library in order to let users trace their simulations
  11 and analyze them. This part of the user manual explains how the
  12 tracing-related features can be enabled and used during the
  13 development of simulators using the SimGrid library.
  14
  15 \section tracing_tracing_enabling Enabling using CMake
  16
  17 With the sources of SimGrid, it is possible to enable the tracing
  18 using the parameter <b>-Denable_tracing=ON</b> when the cmake is
  19 executed.  The sections \ref instr_category_functions, \ref
  20 instr_mark_functions, and \ref instr_uservariables_functions describe
  21 all the functions available when this Cmake options is
  22 activated. These functions will have no effect if SimGrid is
  23 configured without this option (they are wiped-out by the
  24 C-preprocessor).
  25
  26 \verbatim
  27 $ cmake -Denable_tracing=ON .
  28 $ make
  29 \endverbatim
  30
  31 \section instr_category_functions Tracing categories functions
  32
  33 The SimGrid library is instrumented so users can trace the platform
  34 utilization using MSG, SimDAG and SMPI interfaces. It registers how
  35 much power is used for each host and how much bandwidth is used for
  36 each link of the platform. The idea with this type of tracing is to
  37 observe the overall view of resources utilization in the first place,
  38 especially the identification of bottlenecks, load-balancing among
  39 hosts, and so on.
  40
  41 Another possibility is to trace resource utilization by
  42 categories. Categorized resource utilization tracing gives SimGrid
  43 users to possibility to classify MSG and SimDAG tasks by category,
  44 tracing resource utilization for each of the categories. The functions
  45 below let the user declare a category and apply it to tasks. <em>The
  46 tasks that are not classified according to a category are not
  47 traced</em>. Even if the user does not specify any category, the
  48 simulations can still be traced in terms of resource utilization by
  49 using a special parameter that is detailed below (see section \ref
  50 tracing_tracing_options).
  51
  52 \li \c TRACE_category(const char *category)
  53 \li \c TRACE_category_with_color(const char *category, const char *color)
  54 \li \c MSG_task_set_category(msg_task_t task, const char *category)
  55 \li \c MSG_task_get_category(msg_task_t task)
  56 \li \c SD_task_set_category(SD_task_t task, const char *category)
  57 \li \c SD_task_get_category(SD_task_t task)
  58
  59 \section instr_mark_functions Tracing marks functions
  60 \li \c TRACE_declare_mark(const char *mark_type)
  61 \li \c TRACE_mark(const char *mark_type, const char *mark_value)
  62
  63 \section instr_uservariables_functions Tracing user variables functions
  64
  65 For hosts:
  66
  67 \li \c TRACE_host_variable_declare(const char *variable)
  68 \li \c TRACE_host_variable_declare_with_color(const char *variable, const char *color)
  69 \li \c TRACE_host_variable_set(const char *host, const char *variable, double value)
  70 \li \c TRACE_host_variable_add(const char *host, const char *variable, double value)
  71 \li \c TRACE_host_variable_sub(const char *host, const char *variable, double value)
  72 \li \c TRACE_host_variable_set_with_time(double time, const char *host, const char *variable, double value)
  73 \li \c TRACE_host_variable_add_with_time(double time, const char *host, const char *variable, double value)
  74 \li \c TRACE_host_variable_sub_with_time(double time, const char *host, const char *variable, double value)
  75
  76 For links:
  77
  78 \li \c TRACE_link_variable_declare(const char *variable)
  79 \li \c TRACE_link_variable_declare_with_color(const char *variable, const char *color)
  80 \li \c TRACE_link_variable_set(const char *link, const char *variable, double value)
  81 \li \c TRACE_link_variable_add(const char *link, const char *variable, double value)
  82 \li \c TRACE_link_variable_sub(const char *link, const char *variable, double value)
  83 \li \c TRACE_link_variable_set_with_time(double time, const char *link, const char *variable, double value)
  84 \li \c TRACE_link_variable_add_with_time(double time, const char *link, const char *variable, double value)
  85 \li \c TRACE_link_variable_sub_with_time(double time, const char *link, const char *variable, double value)
  86
  87 For links, but use source and destination to get route:
  88
  89 \li \c TRACE_link_srcdst_variable_set(const char *src, const char *dst, const char *variable, double value)
  90 \li \c TRACE_link_srcdst_variable_add(const char *src, const char *dst, const char *variable, double value)
  91 \li \c TRACE_link_srcdst_variable_sub(const char *src, const char *dst, const char *variable, double value)
  92 \li \c TRACE_link_srcdst_variable_set_with_time(double time, const char *src, const char *dst, const char *variable, double value)
  93 \li \c TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value)
  94 \li \c TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value)
  95
  96 \section tracing_tracing_options Tracing configuration Options
  97
  98 To check which tracing options are available for your simulator, you
  99 can just run it with the option \verbatim --help-tracing \endverbatim
 100 to get a very detailed and updated explanation of each tracing
 101 parameter. These are some of the options accepted by the tracing
 102 system of SimGrid, you can use them by running your simulator with the
 103 <b>--cfg=</b> switch:
 104
 105 \li <b>\c
 106 tracing
 107 </b>:
 108   Safe switch. It activates (or deactivates) the tracing system.
 109   No other tracing options take effect if this one is not activated.
 110 \verbatim
 111 --cfg=tracing:yes
 112 \endverbatim
 113
 114 \li <b>\c
 115 tracing/categorized
 116 </b>:
 117   It activates the categorized resource utilization tracing. It should
 118   be enabled if tracing categories are used by this simulator.
 119 \verbatim
 120 --cfg=tracing/categorized:yes
 121 \endverbatim
 122
 123 \li <b>\c
 124 tracing/uncategorized
 125 </b>:
 126   It activates the uncategorized resource utilization tracing. Use it if
 127   this simulator do not use tracing categories and resource use have to be
 128   traced.
 129 \verbatim
 130 --cfg=tracing/uncategorized:yes
 131 \endverbatim
 132
 133 \li <b>\c
 134 tracing/filename
 135 </b>:
 136   A file with this name will be created to register the simulation. The file
 137   is in the Paje format and can be analyzed using Viva or Paje visualization
 138   tools. More information can be found in these webpages:
 139      <a href="http://github.com/schnorr/viva/">http://github.com/schnorr/viva/</a>
 140      <a href="http://github.com/schnorr/pajeng/">http://github.com/schnorr/pajeng/</a>
 141 \verbatim
 142 --cfg=tracing/filename:mytracefile.trace
 143 \endverbatim
 144   If you do not provide this parameter, the trace file will be named simgrid.trace.
 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 \verbatim
 154 --cfg=tracing/smpi:yes
 155 \endverbatim
 156
 157 \li <b>\c
 158 tracing/smpi/group
 159 </b>:
 160   This option only has effect if this simulator is SMPI-based. The processes
 161   are grouped by the hosts where they were executed.
 162 \verbatim
 163 --cfg=tracing/smpi/group:yes
 164 \endverbatim
 165
 166 \li <b>\c
 167 tracing/smpi/computing
 168 </b>:
 169   This option only has effect if this simulator is SMPI-based. The parts external
 170 to SMPI are also outputted to the trace. Provides better way to analyze the data automatically.
 171 \verbatim
 172 --cfg=tracing/smpi/computing:yes
 173 \endverbatim
 174
 175 \li <b>\c
 176 tracing/smpi/internals
 177 </b>:
 178   This option only has effect if this simulator is SMPI-based. Display internal communications
 179 happening during a collective MPI call.
 180 \verbatim
 181 --cfg=tracing/smpi/internals:yes
 182 \endverbatim
 183
 184 \li <b>\c
 185 tracing/smpi/display_sizes
 186 </b>:
 187   This option only has effect if this simulator is SMPI-based. Display the sizes of the messages
 188 exchanged in the trace, both in the links and on the states. For collective, size means the global size of data sent by the process in general.
 189 \verbatim
 190 --cfg=tracing/smpi/display_sizes:yes
 191 \endverbatim
 192
 193 \li <b>\c
 194 tracing/smpi/sleeping
 195 </b>:
 196 TODO
 197 \verbatim
 198 TODO
 199 \endverbatim
 200
 201 \li <b>\c
 202 tracing/smpi/format
 203 </b>:
 204 TODO
 205 \verbatim
 206 TODO
 207 \endverbatim
 208
 209 \li <b>\c
 210 tracing/smpi/format/ti_one_file
 211 </b>:
 212 TODO
 213 \verbatim
 214 TODO
 215 \endverbatim
 216
 217 \li <b>\c
 218 tracing/msg/vm
 219 </b>:
 220 TODO
 221 \verbatim
 222 TODO
 223 \endverbatim
 224
 225 \li <b>\c
 226 tracing/msg/process
 227 </b>:
 228   This option only has effect if this simulator is MSG-based. It traces the
 229   behavior of all categorized MSG processes, grouping them by hosts. This option
 230   can be used to track process location if this simulator has process migration.
 231 \verbatim
 232 --cfg=tracing/msg/process:yes
 233 \endverbatim
 234
 235 \li <b>\c
 236 tracing/buffer
 237 </b>:
 238  This option put some events in a time-ordered buffer using the
 239  insertion sort algorithm. The process of acquiring and releasing
 240  locks to access this buffer and the cost of the sorting algorithm
 241  make this process slow. The simulator performance can be severely
 242  impacted if this option is activated, but you are sure to get a trace
 243  file with events sorted.
 244 \verbatim
 245 --cfg=tracing/buffer:yes
 246 \endverbatim
 247
 248 \li <b>\c
 249 tracing/onelink_only
 250 </b>:
 251 This option changes the way SimGrid register its platform on the trace
 252 file. Normally, the tracing considers all routes (no matter their
 253 size) on the platform file to re-create the resource topology. If this
 254 option is activated, only the routes with one link are used to
 255 register the topology within an AS.  Routes among AS continue to be
 256 traced as usual.
 257 \verbatim
 258 --cfg=tracing/onelink_only:yes
 259 \endverbatim
 260
 261 \li <b>\c
 262 tracing/disable_link
 263 </b>:
 264 TODO
 265 \verbatim
 266 TODO
 267 \endverbatim
 268
 269 \li <b>\c
 270 tracing/disable_power
 271 </b>:
 272 TODO
 273 \verbatim
 274 TODO
 275 \endverbatim
 276
 277 \li <b>\c
 278 tracing/disable_destroy
 279 </b>:
 280 Disable the destruction of containers at the end of simulation. This
 281 can be used with simulators that have a different notion of time
 282 (different from the simulated time).
 283 \verbatim
 284 --cfg=tracing/disable_destroy:yes
 285 \endverbatim
 286
 287 \li <b>\c
 288 tracing/basic
 289 </b>:
 290 Some visualization tools are not able to parse correctly the Paje file format.
 291 Use this option if you are using one of these tools to visualize the simulation
 292 trace. Keep in mind that the trace might be incomplete, without all the
 293 information that would be registered otherwise.
 294 \verbatim
 295 --cfg=tracing/basic:yes
 296 \endverbatim
 297
 298 \li <b>\c
 299 tracing/comment
 300 </b>:
 301 Use this to add a comment line to the top of the trace file.
 302 \verbatim
 303 --cfg=tracing/comment:my_string
 304 \endverbatim
 305
 306 \li <b>\c
 307 tracing/comment_file
 308 </b>:
 309 Use this to add the contents of a file to the top of the trace file as comment.
 310 \verbatim
 311 --cfg=tracing/comment_file:textual_file.txt
 312 \endverbatim
 313
 314 \li <b>\c
 315 tracing/precision
 316 </b>:
 317 TODO
 318 \verbatim
 319 TODO
 320 \endverbatim
 321
 322 \li <b>\c
 323 tracing/platform
 324 </b>:
 325 TODO
 326 \verbatim
 327 TODO
 328 \endverbatim
 329
 330 \li <b>\c
 331 tracing/platform/topology
 332 </b>:
 333 TODO
 334 \verbatim
 335 TODO
 336 \endverbatim
 337
 338 \li <b>\c
 339 viva/categorized
 340 </b>:
 341   This option generates a graph configuration file for Viva considering
 342   categorized resource utilization.
 343 \verbatim
 344 --cfg=viva/categorized:graph_categorized.plist
 345 \endverbatim
 346
 347 \li <b>\c
 348 viva/uncategorized
 349 </b>:
 350   This option generates a graph configuration file for Viva considering
 351   uncategorized resource utilization.
 352 \verbatim
 353 --cfg=viva/uncategorized:graph_uncategorized.plist
 354 \endverbatim
 355
 356 Please pass \verbatim --help-tracing \endverbatim to your simulator
 357 for the updated list of tracing options.
 358
 359 \section tracing_tracing_example_parameters Case studies
 360
 361 Some scenarios that might help you decide which tracing options
 362 you should use to analyze your simulator.
 363
 364 \li I want to trace the resource utilization of all hosts
 365 and links of the platform, and my simulator <b>does not</b> use
 366 the tracing API. For that, you can run a uncategorized trace
 367 with the following parameters (it will work with <b>any</b> Simgrid
 368 simulator):
 369 \verbatim
 370 ./your_simulator \
 371           --cfg=tracing:yes \
 372           --cfg=tracing/uncategorized:yes \
 373           --cfg=tracing/filename:mytracefile.trace \
 374           --cfg=viva/uncategorized:uncat.plist
 375 \endverbatim
 376
 377 \li I want to trace only a subset of my MSG (or SimDAG) tasks.
 378 For that, you will need to create tracing categories using the
 379 <b>TRACE_category (...)</b> function (as explained above),
 380 and then classify your tasks to a previously declared category
 381 using the <b>MSG_task_set_category (...)</b>
 382 (or <b>SD_task_set_category (...)</b> for SimDAG tasks). After
 383 recompiling, run your simulator with the following parameters:
 384 \verbatim
 385 ./your_simulator \
 386           --cfg=tracing:yes \
 387           --cfg=tracing/categorized:yes \
 388           --cfg=tracing/filename:mytracefile.trace \
 389           --cfg=viva/categorized:cat.plist
 390 \endverbatim
 391
 392
 393 \section tracing_tracing_example Example of Instrumentation
 394
 395 A simplified example using the tracing mandatory functions.
 396
 397 \verbatim
 398 int main (int argc, char **argv)
 399 {
 400   MSG_init (&argc, &argv);
 401
 402   //(... after deployment ...)
 403
 404   //note that category declaration must be called after MSG_create_environment
 405   TRACE_category_with_color ("request", "1 0 0");
 406   TRACE_category_with_color ("computation", "0.3 1 0.4");
 407   TRACE_category ("finalize");
 408
 409   msg_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
 410   msg_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
 411   msg_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
 412   msg_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
 413   MSG_task_set_category (req1, "request");
 414   MSG_task_set_category (req2, "request");
 415   MSG_task_set_category (req3, "request");
 416   MSG_task_set_category (req4, "request");
 417
 418   msg_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
 419   MSG_task_set_category (comp, "computation");
 420
 421   msg_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
 422   MSG_task_set_category (finalize, "finalize");
 423
 424   //(...)
 425
 426   MSG_clean();
 427   return 0;
 428 }
 429 \endverbatim
 430
 431 \section tracing_tracing_analyzing Analyzing SimGrid Simulation Traces
 432
 433 A SimGrid-based simulator, when executed with the correct parameters
 434 (see above) creates a trace file in the Paje file format holding the
 435 simulated behavior of the application or the platform. You have
 436 several options to analyze this trace file:
 437
 438 - Dump its contents to a CSV-like format using `pj_dump` (see <a
 439   href="https://github.com/schnorr/pajeng/wiki/pj_dump">PajeNG's wiki
 440   on pj_dump</a> and more generally the <a
 441   href="https://github.com/schnorr/pajeng/">PajeNG suite</a>) and use
 442   gnuplot to plot resource usage, time spent on blocking/executing
 443   functions, and so on. Filtering capabilities are at your hand by
 444   doing `grep`, with the best regular expression you can provide, to
 445   get only parts of the trace (for instance, only a subset of
 446   resources or processes).
 447
 448 - Derive statistics from trace metrics (the ones built-in with any
 449   SimGrid simulation, but also those metrics you injected in the trace
 450   using the TRACE module) using the <a
 451   href="http://www.r-project.org/">R project</a> and all its
 452   modules. You can also combine R with <a
 453   href="http://ggplot2.org/">ggplot2</a> to get a number of high
 454   quality plots from your simulation metrics. You need to `pj_dump`
 455   the contents of the SimGrid trace file to use R.
 456
 457 - Visualize the behavior of your simulation using classic space/time
 458   views (gantt-charts) provided by the <a
 459   href="https://github.com/schnorr/pajeng/">PajeNG suite</a> and any
 460   other tool that supports the <a
 461   href="http://paje.sourceforge.net/download/publication/lang-paje.pdf">Paje
 462   file format</a>. Consider this option if you need to understand the
 463   causality of your distributed simulation.
 464
 465 - Visualize the behavior of your simulation with treemaps (specially
 466   if your simulation has a platform with several thousand resources),
 467   provided by the <a href="http://github.com/schnorr/viva/">Viva</a>
 468   visualization tool. See <a
 469   href="https://github.com/schnorr/viva/wiki">Viva's wiki</a> for
 470   further details on what is a treemap and how to use it.
 471
 472 - Correlate the behavior of your simulator with the platform topology
 473   with an interactive, force-directed, and hierarchical graph
 474   visualization, provided by <a
 475   href="http://github.com/schnorr/viva/">Viva</a>.  Check <a
 476   href="https://github.com/schnorr/viva/wiki">Viva's wiki</a> for
 477   further details. This <a
 478   href="http://hal.inria.fr/hal-00738321/">research report</a>,
 479   published at ISPASS 2013, has a detailed description of this
 480   visualization technique.
 481
 482 - You can also check our online <a
 483   href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial
 484   section</a> that contains a dedicated tutorial with several
 485   suggestions on how to use the tracing infrastructure. Look for the
 486   SimGrid User::Visualization 101 tutorial.
 487
 488 - Ask for help on the <a
 489   href="mailto:simgrid-user@lists.gforge.inria.fr">simgrid-user@lists.gforge.inria.fr</a>
 490   mailing list, giving us a detailed explanation on what your
 491   simulator does and what kind of information you want to trace. You
 492   can also check the <a
 493   href="http://lists.gforge.inria.fr/pipermail/simgrid-user/">mailing
 494   list archive</a> for old messages regarding tracing and analysis.
 495
 496 \subsection tracing_viva_analysis Viva Visualization Tool
 497
 498 This subsection describe some of the concepts regarding the <a
 499 href="http://github.com/schnorr/viva/">Viva Visualization Tool</a> and
 500 its relation with SimGrid traces. You should refer to Viva's website
 501 for further details on all its visualization techniques.
 502
 503 \subsubsection tracing_viva_time_slice Time Slice
 504
 505 The analysis of a trace file using the tool always takes into account
 506 the concept of the <em>time-slice</em>.  This concept means that what
 507 is being visualized in the screen is always calculated considering a
 508 specific time frame, with its beggining and end timestamp. The
 509 time-slice is configured by the user and can be changed dynamically
 510 through the window called <em>Time Interval</em> that is opened
 511 whenever a trace file is being analyzed. Users are capable to select
 512 the beggining and size of the time slice.
 513
 514 \subsubsection tracing_viva_graph Hierarchical Graph View
 515
 516 %As stated above (see section \ref tracing_tracing_analyzing), one
 517 possibility to analyze SimGrid traces is to use Viva's graph view with
 518 a graph configuration to customize the graph according to the
 519 traces. A valid graph configuration (we are using the non-XML <a
 520 href="http://en.wikipedia.org/wiki/Property_list">Property List
 521 Format</a> to describe the configuration) can be created for any
 522 SimGrid-based simulator using the
 523 <em>--cfg=viva/uncategorized:graph_uncategorized.plist</em> or
 524 <em>--cfg=viva/categorized:graph_categorized.plist</em> (if the
 525 simulator defines resource utilization categories) when executing the
 526 simulation.
 527
 528 \subsubsection basic_conf Basic Graph Configuration
 529
 530 The basic description of the configuration is as follows:
 531 \verbatim
 532 {
 533   node = (LINK, HOST, );
 534   edge = (HOST-LINK, LINK-HOST, LINK-LINK, );
 535 \endverbatim
 536
 537 The nodes of the graph will be created based on the <i>node</i>
 538 parameter, which in this case is the different <em>"HOST"</em>s and
 539 <em>"LINK"</em>s of the platform used to simulate. The <i>edge</i>
 540 parameter indicates that the edges of the graph will be created based
 541 on the <em>"HOST-LINK"</em>s, <em>"LINK-HOST"</em>s, and
 542 <em>"LINK-LINK"</em>s of the platform.  After the definition of these
 543 two parameters, the configuration must detail how the nodes
 544 (<em>HOST</em>s and <em>LINK</em>s) should be drawn.
 545
 546 For that, the configuration must have an entry for each of
 547 the types used. For <em>HOST</em>, as basic configuration, we have:
 548
 549 \verbatim
 550   HOST = {
 551     type = square;
 552     size = power;
 553     values = (power_used);
 554   };
 555 \endverbatim
 556
 557 The parameter <em>size</em> indicates which variable from the trace
 558 file will be used to define the size of the node HOST in the
 559 visualization. If the simulation was executed with availability
 560 traces, the size of the nodes will be changed according to these
 561 traces. The parameter <em>type</em> indicates which geometrical shape
 562 will be used to represent HOST, and the <em>values</em> parameter
 563 indicates which values from the trace will be used to fill the shape.
 564
 565 For <em>LINK</em> we have:
 566
 567 \verbatim
 568   LINK = {
 569     type = rhombus;
 570     size = bandwidth;
 571     values = (bandwidth_used);
 572   };
 573 }
 574 \endverbatim
 575
 576 The same configuration parameters are used here: <em>type</em> (with a
 577 rhombus), the <em>size</em> (whose value is from trace's bandwidth
 578 variable) and the <em>values</em>.
 579
 580 \subsubsection custom_graph Customizing the Graph Representation
 581
 582 Viva is capable to handle a customized graph representation based on
 583 the variables present in the trace file. In the case of SimGrid, every
 584 time a category is created for tasks, two variables in the trace file
 585 are defined: one to indicate node utilization (how much power was used
 586 by that task category), and another to indicate link utilization (how
 587 much bandwidth was used by that category). For instance, if the user
 588 declares a category named <i>request</i>, there will be variables
 589 named <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b>
 590 for power and <b>b</b> for bandwidth). It is important to notice that
 591 the variable <i>prequest</i> in this case is only available for HOST,
 592 and <i>brequest</i> is only available for LINK. <b>Example</b>:
 593 suppose there are two categories for tasks: request and compute. To
 594 create a customized graph representation with a proportional
 595 separation of host and link utilization, use as configuration for HOST
 596 and LINK this:
 597
 598 \verbatim
 599   HOST = {
 600     type = square;
 601     size = power;
 602     values = (prequest, pcomputation);
 603   };
 604   LINK = {
 605     type = rhombus;
 606     size = bandwidth;
 607     values = (brequest, bcomputation);
 608   };
 609 \endverbatim
 610
 611 This configuration enables the analysis of resource utilization by MSG
 612 tasks through the identification of load-balancing issues and network
 613 bottlenecks, for instance.
 614
 615 */