Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
start to simplify options descriptions in instr
[simgrid.git] / src / instr / instr_config.cpp
1 /* Copyright (c) 2010-2018. The SimGrid Team. All rights reserved.          */
2
3 /* This program is free software; you can redistribute it and/or modify it
4  * under the terms of the license (GNU LGPL) which comes with this package. */
5
6 #include "include/xbt/config.hpp"
7 #include "simgrid/s4u/Engine.hpp"
8 #include "src/instr/instr_private.hpp"
9 #include "surf/surf.hpp"
10 #include "xbt/virtu.h" /* sg_cmdline */
11 #include <fstream>
12 #include <string>
13 #include <vector>
14
15 XBT_LOG_NEW_CATEGORY(instr, "Logging the behavior of the tracing system (used for Visualization/Analysis of simulations)");
16 XBT_LOG_NEW_DEFAULT_SUBCATEGORY (instr_config, instr, "Configuration");
17
18 std::ofstream tracing_file;
19
20 #define OPT_TRACING_BASIC                "tracing/basic"
21 #define OPT_TRACING_BUFFER               "tracing/buffer"
22 #define OPT_TRACING_CATEGORIZED          "tracing/categorized"
23 #define OPT_TRACING_COMMENT_FILE         "tracing/comment-file"
24 #define OPT_TRACING_COMMENT              "tracing/comment"
25 #define OPT_TRACING_DISABLE_DESTROY      "tracing/disable-destroy"
26 #define OPT_TRACING_DISABLE_LINK         "tracing/disable-link"
27 #define OPT_TRACING_DISABLE_POWER        "tracing/disable-power"
28 #define OPT_TRACING_DISPLAY_SIZES        "tracing/smpi/display-sizes"
29 #define OPT_TRACING_FORMAT_TI_ONEFILE    "tracing/smpi/format/ti-one-file"
30 #define OPT_TRACING_PLATFORM             "tracing/platform"
31 #define OPT_TRACING_SMPI_COMPUTING       "tracing/smpi/computing"
32 #define OPT_TRACING_SMPI_GROUP           "tracing/smpi/group"
33 #define OPT_TRACING_SMPI_INTERNALS       "tracing/smpi/internals"
34 #define OPT_TRACING_SMPI_SLEEPING        "tracing/smpi/sleeping"
35 #define OPT_TRACING_SMPI                 "tracing/smpi"
36 #define OPT_TRACING_TOPOLOGY             "tracing/platform/topology"
37 #define OPT_TRACING_UNCATEGORIZED        "tracing/uncategorized"
38
39 static simgrid::config::Flag<bool> trace_enabled{
40     "tracing", "Enable the tracing system. You have to enable this option to use other tracing options.", false};
41
42 static simgrid::config::Flag<bool> trace_actor_enabled{
43     "tracing/msg/process", // FIXME rename this flag
44     "Trace the behavior of all categorized actors, grouping them by host.\n"
45     "Can be used to track actor location if the simulator does actor migration.",
46     false};
47
48 static simgrid::config::Flag<bool> trace_vm_enabled{"tracing/vm", "Trace the behavior of all virtual machines.", false};
49
50 static simgrid::config::Flag<bool> trace_platform{OPT_TRACING_PLATFORM,
51                                                   "Register the platform in the trace as a hierarchy.", false};
52 static simgrid::config::Flag<bool> trace_platform_topology{
53     OPT_TRACING_TOPOLOGY, "Register the platform topology in the trace as a graph.", true};
54 static simgrid::config::Flag<bool> trace_smpi_enabled{OPT_TRACING_SMPI, "Tracing of the SMPI interface.", false};
55 static simgrid::config::Flag<bool> trace_smpi_grouped{OPT_TRACING_SMPI_GROUP, "Group MPI processes by host.", false};
56 static simgrid::config::Flag<bool> trace_smpi_computing{
57     OPT_TRACING_SMPI_COMPUTING, "Generate states for timing out of SMPI parts of the application", false};
58 static simgrid::config::Flag<bool> trace_smpi_sleeping{
59     OPT_TRACING_SMPI_SLEEPING, "Generate states for timing out of SMPI parts of the application", false};
60 static simgrid::config::Flag<bool> trace_view_internals{
61     OPT_TRACING_SMPI_INTERNALS, "View internal messages sent by Collective communications in SMPI", false};
62 static simgrid::config::Flag<bool> trace_categorized{
63     OPT_TRACING_CATEGORIZED, "Tracing categorized resource utilization of hosts and links.", false};
64 static simgrid::config::Flag<bool> trace_uncategorized{
65     OPT_TRACING_UNCATEGORIZED, "Tracing uncategorized resource utilization of hosts and links.", false};
66 static simgrid::config::Flag<bool> trace_buffer{OPT_TRACING_BUFFER,
67                                                 "Buffer trace events to put them in temporal order.", true};
68 static simgrid::config::Flag<bool> trace_disable_destroy{
69     OPT_TRACING_DISABLE_DESTROY, {"tracing/disable_destroy"}, "Disable platform containers destruction.", false};
70 static simgrid::config::Flag<bool> trace_basic{OPT_TRACING_BASIC, "Avoid extended events (impoverished trace file).",
71                                                false};
72 static simgrid::config::Flag<bool> trace_display_sizes{OPT_TRACING_DISPLAY_SIZES,
73                                                        {"tracing/smpi/display_sizes"},
74                                                        "(smpi only) Extended events with message size information",
75                                                        false};
76 static simgrid::config::Flag<bool> trace_disable_link{
77     OPT_TRACING_DISABLE_LINK, {"tracing/disable_link"}, "Do not trace link bandwidth and latency.", false};
78 static simgrid::config::Flag<bool> trace_disable_power{
79     OPT_TRACING_DISABLE_POWER, {"tracing/disable_power"}, "Do not trace host power.", false};
80
81 static bool trace_active     = false;
82
83 simgrid::instr::TraceFormat simgrid::instr::trace_format = simgrid::instr::TraceFormat::Paje;
84
85 static void TRACE_start()
86 {
87   if (trace_active)
88     return;
89
90   // tracing system must be:
91   //    - enabled (with --cfg=tracing:yes)
92   //    - already configured (TRACE_global_init already called)
93   if (TRACE_is_enabled()) {
94     instr_define_callbacks();
95
96     XBT_DEBUG("Tracing starts");
97     /* init the tracing module to generate the right output */
98     std::string format = simgrid::config::get_value<std::string>("tracing/smpi/format");
99     XBT_DEBUG("Tracing format %s", format.c_str());
100
101     /* open the trace file(s) */
102     std::string filename = TRACE_get_filename();
103     tracing_file.open(filename.c_str(), std::ofstream::out);
104     if (tracing_file.fail()) {
105       THROWF(system_error, 1, "Tracefile %s could not be opened for writing.", filename.c_str());
106     }
107
108     XBT_DEBUG("Filename %s is open for writing", filename.c_str());
109
110     if (format == "Paje") {
111       /* output generator version */
112       tracing_file << "#This file was generated using SimGrid-" << SIMGRID_VERSION_MAJOR << "." << SIMGRID_VERSION_MINOR
113                    << "." << SIMGRID_VERSION_PATCH << std::endl;
114       tracing_file << "#[";
115       unsigned int cpt;
116       char* str;
117       xbt_dynar_foreach (xbt_cmdline, cpt, str) {
118         tracing_file << str << " ";
119       }
120       tracing_file << "]" << std::endl;
121     }
122
123     /* output one line comment */
124     dump_comment(simgrid::config::get_value<std::string>(OPT_TRACING_COMMENT));
125
126     /* output comment file */
127     dump_comment_file(simgrid::config::get_value<std::string>(OPT_TRACING_COMMENT_FILE));
128
129     if (format == "Paje") {
130       /* output Paj√© header */
131       TRACE_header(TRACE_basic(), TRACE_display_sizes());
132     } else
133       simgrid::instr::trace_format = simgrid::instr::TraceFormat::Ti;
134
135     trace_active = true;
136     XBT_DEBUG("Tracing is on");
137   }
138 }
139
140 static void TRACE_end()
141 {
142   if (not trace_active)
143     return;
144
145   /* dump trace buffer */
146   TRACE_last_timestamp_to_dump = surf_get_clock();
147   TRACE_paje_dump_buffer(true);
148
149   simgrid::instr::Type* root_type = simgrid::instr::Container::get_root()->type_;
150   /* destroy all data structures of tracing (and free) */
151   delete simgrid::instr::Container::get_root();
152   delete root_type;
153
154   /* close the trace files */
155   tracing_file.close();
156   XBT_DEBUG("Filename %s is closed", TRACE_get_filename().c_str());
157
158   /* de-activate trace */
159   trace_active = false;
160   XBT_DEBUG("Tracing is off");
161   XBT_DEBUG("Tracing system is shutdown");
162 }
163
164 bool TRACE_needs_platform ()
165 {
166   return TRACE_actor_is_enabled() || TRACE_vm_is_enabled() || TRACE_categorized() || TRACE_uncategorized() ||
167          TRACE_platform() || (TRACE_smpi_is_enabled() && TRACE_smpi_is_grouped());
168 }
169
170 bool TRACE_is_enabled()
171 {
172   return trace_enabled;
173 }
174
175 bool TRACE_platform()
176 {
177   return trace_platform;
178 }
179
180 bool TRACE_platform_topology()
181 {
182   return trace_platform_topology;
183 }
184
185 bool TRACE_smpi_is_enabled()
186 {
187   return (trace_smpi_enabled || TRACE_smpi_is_grouped()) && TRACE_is_enabled();
188 }
189
190 bool TRACE_smpi_is_grouped()
191 {
192   return trace_smpi_grouped;
193 }
194
195 bool TRACE_smpi_is_computing()
196 {
197   return trace_smpi_computing;
198 }
199
200 bool TRACE_smpi_is_sleeping()
201 {
202   return trace_smpi_sleeping;
203 }
204
205 bool TRACE_smpi_view_internals()
206 {
207   return trace_view_internals;
208 }
209
210 bool TRACE_categorized ()
211 {
212   return trace_categorized;
213 }
214
215 bool TRACE_uncategorized ()
216 {
217   return trace_uncategorized;
218 }
219
220 bool TRACE_actor_is_enabled()
221 {
222   return trace_actor_enabled && trace_enabled;
223 }
224
225 bool TRACE_vm_is_enabled()
226 {
227   return trace_vm_enabled && trace_enabled;
228 }
229
230 bool TRACE_disable_link()
231 {
232   return trace_disable_link && trace_enabled;
233 }
234
235 bool TRACE_disable_speed()
236 {
237   return trace_disable_power && trace_enabled;
238 }
239
240 bool TRACE_buffer ()
241 {
242   return trace_buffer && trace_enabled;
243 }
244
245 bool TRACE_disable_destroy ()
246 {
247   return trace_disable_destroy && trace_enabled;
248 }
249
250 bool TRACE_basic ()
251 {
252   return trace_basic && trace_enabled;
253 }
254
255 bool TRACE_display_sizes ()
256 {
257   return trace_display_sizes && trace_smpi_enabled && trace_enabled;
258 }
259
260 int TRACE_precision ()
261 {
262   return simgrid::config::get_value<int>("tracing/precision");
263 }
264
265 std::string TRACE_get_filename()
266 {
267   return simgrid::config::get_value<std::string>("tracing/filename");
268 }
269
270 void TRACE_global_init()
271 {
272   static bool is_initialised = false;
273   if (is_initialised)
274     return;
275
276   is_initialised = true;
277
278   /* name of the tracefile */
279   simgrid::config::declare_flag<std::string>("tracing/filename", "Trace file created by the instrumented SimGrid.",
280                                              "simgrid.trace");
281   simgrid::config::declare_flag<std::string>(
282       "tracing/smpi/format", "Select trace output format used by SMPI. The default is the 'Paje' format.\n"
283                              "The 'TI' (Time-Independent) format allows for trace replay.",
284       "Paje");
285
286   simgrid::config::declare_flag<bool>(OPT_TRACING_FORMAT_TI_ONEFILE,
287                                       "(smpi only) For replay format only : output to one file only", false);
288   simgrid::config::alias(OPT_TRACING_FORMAT_TI_ONEFILE, {"tracing/smpi/format/ti_one_file"});
289   simgrid::config::declare_flag<std::string>(OPT_TRACING_COMMENT, "Comment to be added on the top of the trace file.",
290                                              "");
291   simgrid::config::declare_flag<std::string>(
292       OPT_TRACING_COMMENT_FILE, "The contents of the file are added to the top of the trace file as comment.", "");
293   simgrid::config::alias(OPT_TRACING_COMMENT_FILE, {"tracing/comment_file"});
294   simgrid::config::declare_flag<int>("tracing/precision", "Numerical precision used when timestamping events "
295                                                           "(expressed in number of digits after decimal point)",
296                                      6);
297
298   /* Connect callbacks */
299   simgrid::s4u::on_platform_creation.connect(TRACE_start);
300   simgrid::s4u::on_deadlock.connect(TRACE_end);
301   simgrid::s4u::on_simulation_end.connect(TRACE_end);
302 }
303
304 static void print_line (const char *option, const char *desc, const char *longdesc, int detailed)
305 {
306   std::string str = std::string("--cfg=") + option + " ";
307
308   int len = str.size();
309   printf("%s%*.*s %s\n", str.c_str(), 30 - len, 30 - len, "", desc);
310   if (longdesc != nullptr && detailed){
311     printf ("%s\n\n", longdesc);
312   }
313 }
314
315 void TRACE_help (int detailed)
316 {
317   printf("Description of the tracing options accepted by this simulator:\n\n");
318   print_line (OPT_TRACING_CATEGORIZED, "Trace categorized resource utilization",
319       "  It activates the categorized resource utilization tracing. It should\n"
320       "  be enabled if tracing categories are used by this simulator.", detailed);
321   print_line (OPT_TRACING_UNCATEGORIZED, "Trace uncategorized resource utilization",
322       "  It activates the uncategorized resource utilization tracing. Use it if\n"
323       "  this simulator do not use tracing categories and resource use have to be\n"
324       "  traced.", detailed);
325   print_line (OPT_TRACING_SMPI, "Trace the MPI Interface (SMPI)",
326       "  This option only has effect if this simulator is SMPI-based. Traces the MPI\n"
327       "  interface and generates a trace that can be analyzed using Gantt-like\n"
328       "  visualizations. Every MPI function (implemented by SMPI) is transformed in a\n"
329       "  state, and point-to-point communications can be analyzed with arrows.", detailed);
330   print_line (OPT_TRACING_SMPI_GROUP, "Group MPI processes by host (SMPI)",
331       "  This option only has effect if this simulator is SMPI-based. The processes\n"
332       "  are grouped by the hosts where they were executed.", detailed);
333   print_line (OPT_TRACING_SMPI_COMPUTING, "Generates a \" Computing \" State",
334       "  This option aims at tracing computations in the application, outside SMPI\n"
335       "  to allow further study of simulated or real computation time", detailed);
336    print_line (OPT_TRACING_SMPI_SLEEPING, "Generates a \" Sleeping \" State",
337       "  This option aims at tracing sleeps in the application, outside SMPI\n"
338       "  to allow further study of simulated or real sleep time", detailed);
339   print_line (OPT_TRACING_SMPI_INTERNALS, "Generates tracing events corresponding",
340       "  to point-to-point messages sent by collective communications", detailed);
341   print_line (OPT_TRACING_BUFFER, "Buffer events to put them in temporal order",
342       "  This option put some events in a time-ordered buffer using the insertion\n"
343       "  sort algorithm. The process of acquiring and releasing locks to access this\n"
344       "  buffer and the cost of the sorting algorithm make this process slow. The\n"
345       "  simulator performance can be severely impacted if this option is activated,\n"
346       "  but you are sure to get a trace file with events sorted.", detailed);
347   print_line (OPT_TRACING_DISABLE_DESTROY, "Disable platform containers destruction",
348       "  Disable the destruction of containers at the end of simulation. This can be\n"
349       "  used with simulators that have a different notion of time (different from\n"
350       "  the simulated time).", detailed);
351   print_line (OPT_TRACING_BASIC, "Avoid extended events (impoverished trace file).",
352       "  Some visualization tools are not able to parse correctly the Paje file format.\n"
353       "  Use this option if you are using one of these tools to visualize the simulation\n"
354       "  trace. Keep in mind that the trace might be incomplete, without all the\n"
355       "  information that would be registered otherwise.", detailed);
356   print_line (OPT_TRACING_DISPLAY_SIZES, "Only works for SMPI now. Add message size information",
357       "  Message size (in bytes) is added to links, and to states. For collectives,\n"
358       "  the displayed value is the more relevant to the collective (total sent by\n"
359       "  the process, usually)", detailed);
360   print_line (OPT_TRACING_FORMAT_TI_ONEFILE, "Only works for SMPI now, and TI output format",
361       "  By default, each process outputs to a separate file, inside a filename_files folder\n"
362       "  By setting this option to yes, all processes will output to only one file\n"
363       "  This is meant to avoid opening thousands of files with large simulations", detailed);
364   print_line (OPT_TRACING_COMMENT, "Comment to be added on the top of the trace file.",
365       "  Use this to add a comment line to the top of the trace file.", detailed);
366   print_line (OPT_TRACING_COMMENT_FILE, "File contents added to trace file as comment.",
367       "  Use this to add the contents of a file to the top of the trace file as comment.", detailed);
368   print_line (OPT_TRACING_TOPOLOGY, "Register the platform topology as a graph",
369         "  This option (enabled by default) can be used to disable the tracing of\n"
370         "  the platform topology in the trace file. Sometimes, such task is really\n"
371         "  time consuming, since it must get the route from each host to other hosts\n"
372         "  within the same Autonomous System (AS).", detailed);
373 }