Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
d8a7ad32673a7d5acd8a5f4b49a7a33270420afb
[simgrid.git] / 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 Viva or Paje visualization
125   tools. More information can be found in these webpages:
126      <a href="http://github.com/schnorr/viva/">http://github.com/schnorr/viva/</a>
127      <a href="http://github.com/schnorr/pajeng/">http://github.com/schnorr/pajeng/</a>
128 \verbatim
129 --cfg=tracing/filename:mytracefile.trace
130 \endverbatim
131   If you do not provide this parameter, the trace file will be named simgrid.trace.
132
133 \li <b>\c
134 tracing/smpi
135 </b>:
136   This option only has effect if this simulator is SMPI-based. Traces the MPI
137   interface and generates a trace that can be analyzed using Gantt-like
138   visualizations. Every MPI function (implemented by SMPI) is transformed in a
139   state, and point-to-point communications can be analyzed with arrows.
140 \verbatim
141 --cfg=tracing/smpi:yes
142 \endverbatim
143
144 \li <b>\c
145 tracing/smpi/group
146 </b>:
147   This option only has effect if this simulator is SMPI-based. The processes
148   are grouped by the hosts where they were executed.
149 \verbatim
150 --cfg=tracing/smpi/group:yes
151 \endverbatim
152
153 \li <b>\c
154 tracing/smpi/computing
155 </b>:
156   This option only has effect if this simulator is SMPI-based. The parts external
157 to SMPI are also outputted to the trace. Provides better way to analyze the data automatically.
158 \verbatim
159 --cfg=tracing/smpi/computing:yes
160 \endverbatim
161
162 \li <b>\c
163 tracing/smpi/internals
164 </b>:
165   This option only has effect if this simulator is SMPI-based. Display internal communications
166 happening during a collective MPI call.
167 \verbatim
168 --cfg=tracing/smpi/internals:yes
169 \endverbatim
170
171 \li <b>\c
172 tracing/smpi/display-sizes
173 </b>:
174   This option only has effect if this simulator is SMPI-based. Display the sizes of the messages
175 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.
176 \verbatim
177 --cfg=tracing/smpi/display-sizes:yes
178 \endverbatim
179
180 \li <b>\c
181 tracing/smpi/sleeping
182 </b>:
183 TODO
184 \verbatim
185 TODO
186 \endverbatim
187
188 \li <b>\c
189 tracing/smpi/format
190 </b>:
191 TODO
192 \verbatim
193 TODO
194 \endverbatim
195
196 \li <b>\c
197 tracing/smpi/format/ti-one-file
198 </b>:
199 TODO
200 \verbatim
201 TODO
202 \endverbatim
203
204 \li <b>\c
205 tracing/msg/vm
206 </b>:
207 TODO
208 \verbatim
209 TODO
210 \endverbatim
211
212 \li <b>\c
213 tracing/msg/process
214 </b>:
215   This option only has effect if this simulator is MSG-based. It traces the
216   behavior of all categorized MSG processes, grouping them by hosts. This option
217   can be used to track process location if this simulator has process migration.
218 \verbatim
219 --cfg=tracing/msg/process:yes
220 \endverbatim
221
222 \li <b>\c
223 tracing/buffer
224 </b>:
225  This option put some events in a time-ordered buffer using the
226  insertion sort algorithm. The process of acquiring and releasing
227  locks to access this buffer and the cost of the sorting algorithm
228  make this process slow. The simulator performance can be severely
229  impacted if this option is activated, but you are sure to get a trace
230  file with events sorted.
231 \verbatim
232 --cfg=tracing/buffer:yes
233 \endverbatim
234
235 \li <b>\c
236 tracing/onelink-only
237 </b>:
238 This option changes the way SimGrid register its platform on the trace
239 file. Normally, the tracing considers all routes (no matter their
240 size) on the platform file to re-create the resource topology. If this
241 option is activated, only the routes with one link are used to
242 register the topology within a netzone. Routes among netzones continue to be
243 traced as usual.
244 \verbatim
245 --cfg=tracing/onelink-only:yes
246 \endverbatim
247
248 \li <b>\c
249 tracing/disable-link
250 </b>:
251 TODO
252 \verbatim
253 TODO
254 \endverbatim
255
256 \li <b>\c
257 tracing/disable-power
258 </b>:
259 TODO
260 \verbatim
261 TODO
262 \endverbatim
263
264 \li <b>\c
265 tracing/disable-destroy
266 </b>:
267 Disable the destruction of containers at the end of simulation. This
268 can be used with simulators that have a different notion of time
269 (different from the simulated time).
270 \verbatim
271 --cfg=tracing/disable-destroy:yes
272 \endverbatim
273
274 \li <b>\c
275 tracing/basic
276 </b>:
277 Some visualization tools are not able to parse correctly the Paje file format.
278 Use this option if you are using one of these tools to visualize the simulation
279 trace. Keep in mind that the trace might be incomplete, without all the
280 information that would be registered otherwise.
281 \verbatim
282 --cfg=tracing/basic:yes
283 \endverbatim
284
285 \li <b>\c
286 tracing/comment
287 </b>:
288 Use this to add a comment line to the top of the trace file.
289 \verbatim
290 --cfg=tracing/comment:my_string
291 \endverbatim
292
293 \li <b>\c
294 tracing/comment-file
295 </b>:
296 Use this to add the contents of a file to the top of the trace file as comment.
297 \verbatim
298 --cfg=tracing/comment-file:textual_file.txt
299 \endverbatim
300
301 \li <b>\c
302 tracing/precision
303 </b>:
304 This option determines the precision of timings stored in the trace file. Make sure
305 you set \ref options_model_precision to at least the same value as this option! (Traces
306 cannot be more accurate than the simulation; they can be less accurate, though.)
307
308 The following example will give you a precision of E-10 in the trace file:
309 \verbatim
310 --cfg=tracing/precision:10
311 \endverbatim
312
313 \li <b>\c
314 tracing/platform
315 </b>:
316 TODO
317 \verbatim
318 TODO
319 \endverbatim
320
321 \li <b>\c
322 tracing/platform/topology
323 </b>:
324 TODO
325 \verbatim
326 TODO
327 \endverbatim
328
329 \li <b>\c
330 viva/categorized
331 </b>:
332   This option generates a graph configuration file for Viva considering
333   categorized resource utilization.
334 \verbatim
335 --cfg=viva/categorized:graph_categorized.plist
336 \endverbatim
337
338 \li <b>\c
339 viva/uncategorized
340 </b>:
341   This option generates a graph configuration file for Viva considering
342   uncategorized resource utilization.
343 \verbatim
344 --cfg=viva/uncategorized:graph_uncategorized.plist
345 \endverbatim
346
347 Please pass \verbatim --help-tracing \endverbatim to your simulator
348 for the updated list of tracing options.
349
350 \section tracing_tracing_example_parameters Case studies
351
352 Some scenarios that might help you decide which tracing options
353 you should use to analyze your simulator.
354
355 \li I want to trace the resource utilization of all hosts
356 and links of the platform, and my simulator <b>does not</b> use
357 the tracing API. For that, you can run a uncategorized trace
358 with the following parameters (it will work with <b>any</b> Simgrid
359 simulator):
360 \verbatim
361 ./your_simulator \
362           --cfg=tracing:yes \
363           --cfg=tracing/uncategorized:yes \
364           --cfg=tracing/filename:mytracefile.trace \
365           --cfg=viva/uncategorized:uncat.plist
366 \endverbatim
367
368 \li I want to trace only a subset of my MSG (or SimDAG) tasks.
369 For that, you will need to create tracing categories using the
370 <b>TRACE_category (...)</b> function (as explained above),
371 and then classify your tasks to a previously declared category
372 using the <b>MSG_task_set_category (...)</b>
373 (or <b>SD_task_set_category (...)</b> for SimDAG tasks). After
374 recompiling, run your simulator with the following parameters:
375 \verbatim
376 ./your_simulator \
377           --cfg=tracing:yes \
378           --cfg=tracing/categorized:yes \
379           --cfg=tracing/filename:mytracefile.trace \
380           --cfg=viva/categorized:cat.plist
381 \endverbatim
382
383
384 \section tracing_tracing_example Example of Instrumentation
385
386 A simplified example using the tracing mandatory functions.
387
388 \verbatim
389 int main (int argc, char **argv)
390 {
391   MSG_init (&argc, &argv);
392
393   //(... after deployment ...)
394
395   //note that category declaration must be called after MSG_create_environment
396   TRACE_category_with_color ("request", "1 0 0");
397   TRACE_category_with_color ("computation", "0.3 1 0.4");
398   TRACE_category ("finalize");
399
400   msg_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
401   msg_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
402   msg_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
403   msg_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
404   MSG_task_set_category (req1, "request");
405   MSG_task_set_category (req2, "request");
406   MSG_task_set_category (req3, "request");
407   MSG_task_set_category (req4, "request");
408
409   msg_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
410   MSG_task_set_category (comp, "computation");
411
412   msg_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
413   MSG_task_set_category (finalize, "finalize");
414
415   //(...)
416
417   MSG_clean();
418   return 0;
419 }
420 \endverbatim
421
422 \section tracing_tracing_analyzing Analyzing SimGrid Simulation Traces
423
424 A SimGrid-based simulator, when executed with the correct parameters
425 (see above) creates a trace file in the Paje file format holding the
426 simulated behavior of the application or the platform. You have
427 several options to analyze this trace file:
428
429 - Dump its contents to a CSV-like format using `pj_dump` (see <a
430   href="https://github.com/schnorr/pajeng/wiki/pj_dump">PajeNG's wiki
431   on pj_dump</a> and more generally the <a
432   href="https://github.com/schnorr/pajeng/">PajeNG suite</a>) and use
433   gnuplot to plot resource usage, time spent on blocking/executing
434   functions, and so on. Filtering capabilities are at your hand by
435   doing `grep`, with the best regular expression you can provide, to
436   get only parts of the trace (for instance, only a subset of
437   resources or processes).
438
439 - Derive statistics from trace metrics (the ones built-in with any
440   SimGrid simulation, but also those metrics you injected in the trace
441   using the TRACE module) using the <a
442   href="http://www.r-project.org/">R project</a> and all its
443   modules. You can also combine R with <a
444   href="http://ggplot2.org/">ggplot2</a> to get a number of high
445   quality plots from your simulation metrics. You need to `pj_dump`
446   the contents of the SimGrid trace file to use R.
447
448 - Visualize the behavior of your simulation using classic space/time
449   views (gantt-charts) provided by the <a
450   href="https://github.com/schnorr/pajeng/">PajeNG suite</a> and any
451   other tool that supports the <a
452   href="http://paje.sourceforge.net/download/publication/lang-paje.pdf">Paje
453   file format</a>. Consider this option if you need to understand the
454   causality of your distributed simulation.
455
456 - Visualize the behavior of your simulation with treemaps (specially
457   if your simulation has a platform with several thousand resources),
458   provided by the <a href="http://github.com/schnorr/viva/">Viva</a>
459   visualization tool. See <a
460   href="https://github.com/schnorr/viva/wiki">Viva's wiki</a> for
461   further details on what is a treemap and how to use it.
462
463 - Correlate the behavior of your simulator with the platform topology
464   with an interactive, force-directed, and hierarchical graph
465   visualization, provided by <a
466   href="http://github.com/schnorr/viva/">Viva</a>.  Check <a
467   href="https://github.com/schnorr/viva/wiki">Viva's wiki</a> for
468   further details. This <a
469   href="http://hal.inria.fr/hal-00738321/">research report</a>,
470   published at ISPASS 2013, has a detailed description of this
471   visualization technique.
472
473 - You can also check our online <a
474   href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial
475   section</a> that contains a dedicated tutorial with several
476   suggestions on how to use the tracing infrastructure. Look for the
477   SimGrid User::Visualization 101 tutorial.
478
479 - Ask for help on the <a
480   href="mailto:simgrid-user@lists.gforge.inria.fr">simgrid-user@lists.gforge.inria.fr</a>
481   mailing list, giving us a detailed explanation on what your
482   simulator does and what kind of information you want to trace. You
483   can also check the <a
484   href="http://lists.gforge.inria.fr/pipermail/simgrid-user/">mailing
485   list archive</a> for old messages regarding tracing and analysis.
486
487 \subsection tracing_viva_analysis Viva Visualization Tool
488
489 This subsection describe some of the concepts regarding the <a
490 href="http://github.com/schnorr/viva/">Viva Visualization Tool</a> and
491 its relation with SimGrid traces. You should refer to Viva's website
492 for further details on all its visualization techniques.
493
494 \subsubsection tracing_viva_time_slice Time Slice
495
496 The analysis of a trace file using the tool always takes into account
497 the concept of the <em>time-slice</em>.  This concept means that what
498 is being visualized in the screen is always calculated considering a
499 specific time frame, with its beggining and end timestamp. The
500 time-slice is configured by the user and can be changed dynamically
501 through the window called <em>Time Interval</em> that is opened
502 whenever a trace file is being analyzed. Users are capable to select
503 the beggining and size of the time slice.
504
505 \subsubsection tracing_viva_graph Hierarchical Graph View
506
507 As stated above (see section \ref tracing_tracing_analyzing), one
508 possibility to analyze SimGrid traces is to use Viva's graph view with
509 a graph configuration to customize the graph according to the
510 traces. A valid graph configuration (we are using the non-XML <a
511 href="http://en.wikipedia.org/wiki/Property_list">Property List
512 Format</a> to describe the configuration) can be created for any
513 SimGrid-based simulator using the
514 <em>--cfg=viva/uncategorized:graph_uncategorized.plist</em> or
515 <em>--cfg=viva/categorized:graph_categorized.plist</em> (if the
516 simulator defines resource utilization categories) when executing the
517 simulation.
518
519 \subsubsection basic_conf Basic Graph Configuration
520
521 The basic description of the configuration is as follows:
522 \verbatim
523 {
524   node = (LINK, HOST, );
525   edge = (HOST-LINK, LINK-HOST, LINK-LINK, );
526 \endverbatim
527
528 The nodes of the graph will be created based on the <i>node</i>
529 parameter, which in this case is the different <em>"HOST"</em>s and
530 <em>"LINK"</em>s of the platform used to simulate. The <i>edge</i>
531 parameter indicates that the edges of the graph will be created based
532 on the <em>"HOST-LINK"</em>s, <em>"LINK-HOST"</em>s, and
533 <em>"LINK-LINK"</em>s of the platform.  After the definition of these
534 two parameters, the configuration must detail how the nodes
535 (<em>HOST</em>s and <em>LINK</em>s) should be drawn.
536
537 For that, the configuration must have an entry for each of
538 the types used. For <em>HOST</em>, as basic configuration, we have:
539
540 \verbatim
541   HOST = {
542     type = square;
543     size = power;
544     values = (power_used);
545   };
546 \endverbatim
547
548 The parameter <em>size</em> indicates which variable from the trace
549 file will be used to define the size of the node HOST in the
550 visualization. If the simulation was executed with availability
551 traces, the size of the nodes will be changed according to these
552 traces. The parameter <em>type</em> indicates which geometrical shape
553 will be used to represent HOST, and the <em>values</em> parameter
554 indicates which values from the trace will be used to fill the shape.
555
556 For <em>LINK</em> we have:
557
558 \verbatim
559   LINK = {
560     type = rhombus;
561     size = bandwidth;
562     values = (bandwidth_used);
563   };
564 }
565 \endverbatim
566
567 The same configuration parameters are used here: <em>type</em> (with a
568 rhombus), the <em>size</em> (whose value is from trace's bandwidth
569 variable) and the <em>values</em>.
570
571 \subsubsection custom_graph Customizing the Graph Representation
572
573 Viva is capable to handle a customized graph representation based on
574 the variables present in the trace file. In the case of SimGrid, every
575 time a category is created for tasks, two variables in the trace file
576 are defined: one to indicate node utilization (how much power was used
577 by that task category), and another to indicate link utilization (how
578 much bandwidth was used by that category). For instance, if the user
579 declares a category named <i>request</i>, there will be variables
580 named <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b>
581 for power and <b>b</b> for bandwidth). It is important to notice that
582 the variable <i>prequest</i> in this case is only available for HOST,
583 and <i>brequest</i> is only available for LINK. <b>Example</b>:
584 suppose there are two categories for tasks: request and compute. To
585 create a customized graph representation with a proportional
586 separation of host and link utilization, use as configuration for HOST
587 and LINK this:
588
589 \verbatim
590   HOST = {
591     type = square;
592     size = power;
593     values = (prequest, pcomputation);
594   };
595   LINK = {
596     type = rhombus;
597     size = bandwidth;
598     values = (brequest, bcomputation);
599   };
600 \endverbatim
601
602 This configuration enables the analysis of resource utilization by MSG
603 tasks through the identification of load-balancing issues and network
604 bottlenecks, for instance.
605
606 */