/*! \page tracing Tracing Simulations for Visualization
-\section tracing_tracing Tracing Simulations for Visualization
The trace visualization is widely used to observe and understand the behavior
of parallel applications and distributed algorithms. Usually, this is done in a
user manual explains how the tracing-related features can be enabled and used
during the development of simulators using the SimGrid library.
-\subsection tracing_tracing_howitworks How it works
+\section tracing_tracing_howitworks How it works
For now, the SimGrid library is instrumented so users can trace the <b>platform
utilization</b> using the MSG, SimDAG and SMPI interface. This means that the tracing will
does not specify any category, the simulations can still be traced in terms
of resource utilization by using a special parameter that is detailed below.
-\subsection tracing_tracing_enabling Enabling using CMake
+\section tracing_tracing_enabling Enabling using CMake
With the sources of SimGrid, it is possible to enable the tracing
using the parameter <b>-Denable_tracing=ON</b> when the cmake is
$ make
\endverbatim
-\subsection instr_category_functions Tracing categories functions
+\section instr_category_functions Tracing categories functions
\li \c TRACE_category(const char *category)
\li \c TRACE_category_with_color(const char *category, const char *color)
-\li \c MSG_task_set_category(m_task_t task, const char *category)
-\li \c MSG_task_get_category(m_task_t task)
+\li \c MSG_task_set_category(msg_task_t task, const char *category)
+\li \c MSG_task_get_category(msg_task_t task)
\li \c SD_task_set_category(SD_task_t task, const char *category)
\li \c SD_task_get_category(SD_task_t task)
-\subsection instr_mark_functions Tracing marks functions
+\section instr_mark_functions Tracing marks functions
\li \c TRACE_declare_mark(const char *mark_type)
\li \c TRACE_mark(const char *mark_type, const char *mark_value)
-\subsection instr_uservariables_functions Tracing user variables functions
+\section instr_uservariables_functions Tracing user variables functions
For hosts:
\li \c TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value)
\li \c TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value)
-\subsection tracing_tracing_options Tracing configuration Options
+\section tracing_tracing_options Tracing configuration Options
To check which tracing options are available for your simulator, you
can just run it with the option <b>--help-tracing</b>. These are the
--cfg=tracing/disable_destroy:1
\endverbatim
+\li <b>\c
+tracing/basic
+</b>:
+Some visualization tools are not able to parse correctly the Paje file format.
+Use this option if you are using one of these tools to visualize the simulation
+trace. Keep in mind that the trace might be incomplete, without all the
+information that would be registered otherwise.
+\verbatim
+--cfg=tracing/basic:1
+\endverbatim
+
+\li <b>\c
+tracing/comment
+</b>:
+Use this to add a comment line to the top of the trace file.
+\verbatim
+--cfg=tracing/comment:my_string
+\endverbatim
+
+\li <b>\c
+tracing/comment_file
+</b>:
+Use this to add the contents of a file to the top of the trace file as comment.
+\verbatim
+--cfg=tracing/comment_file:textual_file.txt
+\endverbatim
+
\li <b>\c
triva/categorized
</b>:
--cfg=triva/uncategorized:graph_uncategorized.plist
\endverbatim
-\subsection tracing_tracing_example_parameters Case studies
+\section tracing_tracing_example_parameters Case studies
Some scenarios that might help you decide which tracing options
you should use to analyze your simulator.
\endverbatim
-\subsection tracing_tracing_example Example of Instrumentation
+\section tracing_tracing_example Example of Instrumentation
A simplified example using the tracing mandatory functions.
\verbatim
int main (int argc, char **argv)
{
- MSG_global_init (&argc, &argv);
+ MSG_init (&argc, &argv);
//(... after deployment ...)
TRACE_category_with_color ("computation", "0.3 1 0.4");
TRACE_category ("finalize");
- m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
- m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
- m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
- m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
+ msg_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
+ msg_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
+ msg_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
+ msg_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
MSG_task_set_category (req1, "request");
MSG_task_set_category (req2, "request");
MSG_task_set_category (req3, "request");
MSG_task_set_category (req4, "request");
- m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
+ msg_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
MSG_task_set_category (comp, "computation");
- m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
+ msg_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
MSG_task_set_category (finalize, "finalize");
//(...)
}
\endverbatim
-\subsection tracing_tracing_analyzing Analyzing the SimGrid Traces
+\section tracing_tracing_analyzing Analyzing the SimGrid Traces
The SimGrid library, during an instrumented simulation, creates a trace file in
the Paje file format that contains the platform utilization for the simulation
