doc/doxygen/outcomes_vizu.doc

   1 /*! @page outcomes_vizu Visualization and Statistical Analysis
   2
   3 SimGrid comes with an extensive support to trace and register what
   4 happens during the simulation, so that it can be either visualized or
   5 statistically analysed after the simulation.
   6
   7 This tracing is widely used to observe and understand the behavior of
   8 parallel applications and distributed algorithms. Usually, this is
   9 done in a two-step fashion: the user instruments the application and
  10 the traces are analyzed after the end of the execution. The analysis
  11 can highlights unexpected behaviors, bottlenecks and sometimes can be
  12 used to correct distributed algorithms. The SimGrid team has
  13 instrumented the library in order to let users trace their simulations
  14 and analyze them. This part of the user manual explains how the
  15 tracing-related features can be enabled and used during the
  16 development of simulators using the SimGrid library.
  17
  18 @section instr_category_functions Tracing categories functions
  19
  20 The SimGrid library is instrumented so users can trace the platform
  21 utilization using MSG, SimDAG and SMPI interfaces. It registers how
  22 much power is used for each host and how much bandwidth is used for
  23 each link of the platform. The idea with this type of tracing is to
  24 observe the overall view of resources utilization in the first place,
  25 especially the identification of bottlenecks, load-balancing among
  26 hosts, and so on.
  27
  28 Another possibility is to trace resource utilization by
  29 categories. Categorized resource utilization tracing gives SimGrid
  30 users to possibility to classify MSG and SimDAG tasks by category,
  31 tracing resource utilization for each of the categories. The functions
  32 below let the user declare a category and apply it to tasks. <em>The
  33 tasks that are not classified according to a category are not
  34 traced</em>. Even if the user does not specify any category, the
  35 simulations can still be traced in terms of resource utilization by
  36 using a special parameter that is detailed below (see section @ref
  37 tracing_tracing_options).
  38
  39 @li @c TRACE_category(const char *category)
  40 @li @c TRACE_category_with_color(const char *category, const char *color)
  41 @li @c MSG_task_set_category(msg_task_t task, const char *category)
  42 @li @c MSG_task_get_category(msg_task_t task)
  43 @li @c SD_task_set_category(SD_task_t task, const char *category)
  44 @li @c SD_task_get_category(SD_task_t task)
  45
  46 @section instr_mark_functions Tracing marks functions
  47 @li @c TRACE_declare_mark(const char *mark_type)
  48 @li @c TRACE_mark(const char *mark_type, const char *mark_value)
  49
  50 @section instr_uservariables_functions Tracing user variables functions
  51
  52 For hosts:
  53
  54 @li @c TRACE_host_variable_declare(const char *variable)
  55 @li @c TRACE_host_variable_declare_with_color(const char *variable, const char *color)
  56 @li @c TRACE_host_variable_set(const char *host, const char *variable, double value)
  57 @li @c TRACE_host_variable_add(const char *host, const char *variable, double value)
  58 @li @c TRACE_host_variable_sub(const char *host, const char *variable, double value)
  59 @li @c TRACE_host_variable_set_with_time(double time, const char *host, const char *variable, double value)
  60 @li @c TRACE_host_variable_add_with_time(double time, const char *host, const char *variable, double value)
  61 @li @c TRACE_host_variable_sub_with_time(double time, const char *host, const char *variable, double value)
  62
  63 For links:
  64
  65 @li @c TRACE_link_variable_declare(const char *variable)
  66 @li @c TRACE_link_variable_declare_with_color(const char *variable, const char *color)
  67 @li @c TRACE_link_variable_set(const char *link, const char *variable, double value)
  68 @li @c TRACE_link_variable_add(const char *link, const char *variable, double value)
  69 @li @c TRACE_link_variable_sub(const char *link, const char *variable, double value)
  70 @li @c TRACE_link_variable_set_with_time(double time, const char *link, const char *variable, double value)
  71 @li @c TRACE_link_variable_add_with_time(double time, const char *link, const char *variable, double value)
  72 @li @c TRACE_link_variable_sub_with_time(double time, const char *link, const char *variable, double value)
  73
  74 For links, but use source and destination to get route:
  75
  76 @li @c TRACE_link_srcdst_variable_set(const char *src, const char *dst, const char *variable, double value)
  77 @li @c TRACE_link_srcdst_variable_add(const char *src, const char *dst, const char *variable, double value)
  78 @li @c TRACE_link_srcdst_variable_sub(const char *src, const char *dst, const char *variable, double value)
  79 @li @c TRACE_link_srcdst_variable_set_with_time(double time, const char *src, const char *dst, const char *variable, double value)
  80 @li @c TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value)
  81 @li @c TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value)
  82
  83 @section tracing_tracing_options Tracing configuration Options
  84
  85 To check which tracing options are available for your simulator, you
  86 can just run it with the option @verbatim --help-tracing @endverbatim
  87 to get a very detailed and updated explanation of each tracing
  88 parameter. These are some of the options accepted by the tracing
  89 system of SimGrid, you can use them by running your simulator with the
  90 <b>--cfg=</b> switch:
  91
  92 @li <b>@c
  93 tracing
  94 </b>:
  95   Safe switch. It activates (or deactivates) the tracing system.
  96   No other tracing options take effect if this one is not activated.
  97 @verbatim
  98 --cfg=tracing:yes
  99 @endverbatim
 100
 101 @li <b>@c
 102 tracing/categorized
 103 </b>:
 104   It activates the categorized resource utilization tracing. It should
 105   be enabled if tracing categories are used by this simulator.
 106 @verbatim
 107 --cfg=tracing/categorized:yes
 108 @endverbatim
 109
 110 @li <b>@c
 111 tracing/uncategorized
 112 </b>:
 113   It activates the uncategorized resource utilization tracing. Use it if
 114   this simulator do not use tracing categories and resource use have to be
 115   traced.
 116 @verbatim
 117 --cfg=tracing/uncategorized:yes
 118 @endverbatim
 119
 120 @li <b>@c
 121 tracing/filename
 122 </b>:
 123   A file with this name will be created to register the simulation. The file
 124   is in the Paje format and can be analyzed using Paje visualization
 125   tools. More information can be found in these webpages:
 126      <a href="http://github.com/schnorr/pajeng/">http://github.com/schnorr/pajeng/</a>
 127 @verbatim
 128 --cfg=tracing/filename:mytracefile.trace
 129 @endverbatim
 130   If you do not provide this parameter, the trace file will be named simgrid.trace.
 131
 132 @li <b>@c
 133 tracing/smpi
 134 </b>:
 135   This option only has effect if this simulator is SMPI-based. Traces the MPI
 136   interface and generates a trace that can be analyzed using Gantt-like
 137   visualizations. Every MPI function (implemented by SMPI) is transformed in a
 138   state, and point-to-point communications can be analyzed with arrows.
 139 @verbatim
 140 --cfg=tracing/smpi:yes
 141 @endverbatim
 142
 143 @li <b>@c
 144 tracing/smpi/group
 145 </b>:
 146   This option only has effect if this simulator is SMPI-based. The processes
 147   are grouped by the hosts where they were executed.
 148 @verbatim
 149 --cfg=tracing/smpi/group:yes
 150 @endverbatim
 151
 152 @li <b>@c
 153 tracing/smpi/computing
 154 </b>:
 155   This option only has effect if this simulator is SMPI-based. The parts external
 156 to SMPI are also outputted to the trace. Provides better way to analyze the data automatically.
 157 @verbatim
 158 --cfg=tracing/smpi/computing:yes
 159 @endverbatim
 160
 161 @li <b>@c
 162 tracing/smpi/internals
 163 </b>:
 164   This option only has effect if this simulator is SMPI-based. Display internal communications
 165 happening during a collective MPI call.
 166 @verbatim
 167 --cfg=tracing/smpi/internals:yes
 168 @endverbatim
 169
 170 @li <b>@c
 171 tracing/smpi/display-sizes
 172 </b>:
 173   This option only has effect if this simulator is SMPI-based. Display the sizes of the messages
 174 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.
 175 @verbatim
 176 --cfg=tracing/smpi/display-sizes:yes
 177 @endverbatim
 178
 179 @li <b>@c
 180 tracing/smpi/sleeping
 181 </b>:
 182 TODO
 183 @verbatim
 184 TODO
 185 @endverbatim
 186
 187 @li <b>@c
 188 tracing/smpi/format
 189 </b>:
 190 TODO
 191 @verbatim
 192 TODO
 193 @endverbatim
 194
 195 @li <b>@c
 196 tracing/smpi/format/ti-one-file
 197 </b>:
 198 TODO
 199 @verbatim
 200 TODO
 201 @endverbatim
 202
 203 @li <b>@c
 204 tracing/vm
 205 </b>:
 206 TODO
 207 @verbatim
 208 TODO
 209 @endverbatim
 210
 211 @li <b>@c
 212 tracing/msg/process
 213 </b>:
 214   This option only has effect if this simulator is MSG-based. It traces the
 215   behavior of all categorized MSG processes, grouping them by hosts. This option
 216   can be used to track process location if this simulator has process migration.
 217 @verbatim
 218 --cfg=tracing/msg/process:yes
 219 @endverbatim
 220
 221 @li <b>@c
 222 tracing/buffer
 223 </b>:
 224  This option put some events in a time-ordered buffer using the
 225  insertion sort algorithm. The process of acquiring and releasing
 226  locks to access this buffer and the cost of the sorting algorithm
 227  make this process slow. The simulator performance can be severely
 228  impacted if this option is activated, but you are sure to get a trace
 229  file with events sorted.
 230 @verbatim
 231 --cfg=tracing/buffer:yes
 232 @endverbatim
 233
 234 @li <b>@c
 235 tracing/onelink-only
 236 </b>:
 237 This option changes the way SimGrid register its platform on the trace
 238 file. Normally, the tracing considers all routes (no matter their
 239 size) on the platform file to re-create the resource topology. If this
 240 option is activated, only the routes with one link are used to
 241 register the topology within a netzone. Routes among netzones continue to be
 242 traced as usual.
 243 @verbatim
 244 --cfg=tracing/onelink-only:yes
 245 @endverbatim
 246
 247 @li <b>@c
 248 tracing/disable-link
 249 </b>:
 250 TODO
 251 @verbatim
 252 TODO
 253 @endverbatim
 254
 255 @li <b>@c
 256 tracing/disable-power
 257 </b>:
 258 TODO
 259 @verbatim
 260 TODO
 261 @endverbatim
 262
 263 @li <b>@c
 264 tracing/disable-destroy
 265 </b>:
 266 Disable the destruction of containers at the end of simulation. This
 267 can be used with simulators that have a different notion of time
 268 (different from the simulated time).
 269 @verbatim
 270 --cfg=tracing/disable-destroy:yes
 271 @endverbatim
 272
 273 @li <b>@c
 274 tracing/basic
 275 </b>:
 276 Some visualization tools are not able to parse correctly the Paje file format.
 277 Use this option if you are using one of these tools to visualize the simulation
 278 trace. Keep in mind that the trace might be incomplete, without all the
 279 information that would be registered otherwise.
 280 @verbatim
 281 --cfg=tracing/basic:yes
 282 @endverbatim
 283
 284 @li <b>@c
 285 tracing/comment
 286 </b>:
 287 Use this to add a comment line to the top of the trace file.
 288 @verbatim
 289 --cfg=tracing/comment:my_string
 290 @endverbatim
 291
 292 @li <b>@c
 293 tracing/comment-file
 294 </b>:
 295 Use this to add the contents of a file to the top of the trace file as comment.
 296 @verbatim
 297 --cfg=tracing/comment-file:textual_file.txt
 298 @endverbatim
 299
 300 @li <b>@c
 301 tracing/precision
 302 </b>:
 303 This option determines the precision of timings stored in the trace file. Make sure
 304 you set @ref options_model_precision to at least the same value as this option! (Traces
 305 cannot be more accurate than the simulation; they can be less accurate, though.)
 306
 307 The following example will give you a precision of E-10 in the trace file:
 308 @verbatim
 309 --cfg=tracing/precision:10
 310 @endverbatim
 311
 312 @li <b>@c
 313 tracing/platform
 314 </b>:
 315 TODO
 316 @verbatim
 317 TODO
 318 @endverbatim
 319
 320 @li <b>@c
 321 tracing/platform/topology
 322 </b>:
 323 TODO
 324 @verbatim
 325 TODO
 326 @endverbatim
 327
 328 Please pass @verbatim --help-tracing @endverbatim to your simulator
 329 for the updated list of tracing options.
 330
 331 @section tracing_tracing_example_parameters Case studies
 332
 333 Some scenarios that might help you decide which tracing options
 334 you should use to analyze your simulator.
 335
 336 @li I want to trace the resource utilization of all hosts
 337 and links of the platform, and my simulator <b>does not</b> use
 338 the tracing API. For that, you can run a uncategorized trace
 339 with the following parameters (it will work with <b>any</b> Simgrid
 340 simulator):
 341 @verbatim
 342 ./your_simulator @
 343           --cfg=tracing:yes @
 344           --cfg=tracing/uncategorized:yes @
 345           --cfg=tracing/filename:mytracefile.trace @
 346 @endverbatim
 347
 348 @li I want to trace only a subset of my MSG (or SimDAG) tasks.
 349 For that, you will need to create tracing categories using the
 350 <b>TRACE_category (...)</b> function (as explained above),
 351 and then classify your tasks to a previously declared category
 352 using the <b>MSG_task_set_category (...)</b>
 353 (or <b>SD_task_set_category (...)</b> for SimDAG tasks). After
 354 recompiling, run your simulator with the following parameters:
 355 @verbatim
 356 ./your_simulator @
 357           --cfg=tracing:yes @
 358           --cfg=tracing/categorized:yes @
 359           --cfg=tracing/filename:mytracefile.trace @
 360 @endverbatim
 361
 362
 363 @section tracing_tracing_example Example of Instrumentation
 364
 365 A simplified example using the tracing mandatory functions.
 366
 367 @verbatim
 368 int main (int argc, char **argv)
 369 {
 370   MSG_init (&argc, &argv);
 371
 372   //(... after deployment ...)
 373
 374   //note that category declaration must be called after MSG_create_environment
 375   TRACE_category_with_color ("request", "1 0 0");
 376   TRACE_category_with_color ("computation", "0.3 1 0.4");
 377   TRACE_category ("finalize");
 378
 379   msg_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
 380   msg_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
 381   msg_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
 382   msg_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
 383   MSG_task_set_category (req1, "request");
 384   MSG_task_set_category (req2, "request");
 385   MSG_task_set_category (req3, "request");
 386   MSG_task_set_category (req4, "request");
 387
 388   msg_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
 389   MSG_task_set_category (comp, "computation");
 390
 391   msg_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
 392   MSG_task_set_category (finalize, "finalize");
 393
 394   //(...)
 395
 396   MSG_clean();
 397   return 0;
 398 }
 399 @endverbatim
 400
 401 @section tracing_tracing_analyzing Analyzing SimGrid Simulation Traces
 402
 403 A SimGrid-based simulator, when executed with the correct parameters
 404 (see above) creates a trace file in the Paje file format holding the
 405 simulated behavior of the application or the platform. You have
 406 several options to analyze this trace file:
 407
 408 - Dump its contents to a CSV-like format using `pj_dump` (see <a
 409   href="https://github.com/schnorr/pajeng/wiki/pj_dump">PajeNG's wiki
 410   on pj_dump</a> and more generally the <a
 411   href="https://github.com/schnorr/pajeng/">PajeNG suite</a>) and use
 412   gnuplot to plot resource usage, time spent on blocking/executing
 413   functions, and so on. Filtering capabilities are at your hand by
 414   doing `grep`, with the best regular expression you can provide, to
 415   get only parts of the trace (for instance, only a subset of
 416   resources or processes).
 417
 418 - Derive statistics from trace metrics (the ones built-in with any
 419   SimGrid simulation, but also those metrics you injected in the trace
 420   using the TRACE module) using the <a
 421   href="http://www.r-project.org/">R project</a> and all its
 422   modules. You can also combine R with <a
 423   href="http://ggplot2.org/">ggplot2</a> to get a number of high
 424   quality plots from your simulation metrics. You need to `pj_dump`
 425   the contents of the SimGrid trace file to use R.
 426
 427 - Visualize the behavior of your simulation using classic space/time
 428   views (gantt-charts) provided by the <a
 429   href="https://github.com/schnorr/pajeng/">PajeNG suite</a> and any
 430   other tool that supports the <a
 431   href="http://paje.sourceforge.net/download/publication/lang-paje.pdf">Paje
 432   file format</a>. Consider this option if you need to understand the
 433   causality of your distributed simulation.
 434
 435 - You can also check our online <a
 436   href="https://simgrid.org/tutorials.html"> tutorial
 437   section</a> that contains a dedicated tutorial with several
 438   suggestions on how to use the tracing infrastructure. Look for the
 439   SimGrid User::Visualization 101 tutorial.
 440
 441 - Ask for help on the <a
 442   href="mailto:simgrid-user@lists.gforge.inria.fr">simgrid-user@lists.gforge.inria.fr</a>
 443   mailing list, giving us a detailed explanation on what your
 444   simulator does and what kind of information you want to trace. You
 445   can also check the <a
 446   href="http://lists.gforge.inria.fr/pipermail/simgrid-user/">mailing
 447   list archive</a> for old messages regarding tracing and analysis.
 448
 449 */