Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
06fdfd09eed80fc5facea2c448f0b462ed5913f7
[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 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="http://simgrid.gforge.inria.fr/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 */