X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/c629f33988e0739f0dc28291601c48cdaaca16f9..2f810149832a2d855c33d0df5b02d736c2081e41:/doc/tracing.doc
diff --git a/doc/tracing.doc b/doc/tracing.doc
index 3b3b56d0c2..4a7fe288c0 100644
--- a/doc/tracing.doc
+++ b/doc/tracing.doc
@@ -105,19 +105,28 @@ Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time differ
\subsection tracing_tracing_options Tracing configuration Options
-These are the options accepted by the tracing system of SimGrid:
+To check which tracing options are available for your simulator, you
+can just run it with the option --help-tracing. These are the
+options accepted by the tracing system of SimGrid as of today, you
+can use them by running your simulator with the --cfg= switch:
\li \c
tracing
:
Safe switch. It activates (or deactivates) the tracing system.
No other tracing options take effect if this one is not activated.
+\verbatim
+--cfg=tracing:1
+\endverbatim
\li \c
tracing/categorized
:
It activates the categorized resource utilization tracing. It should
be enabled if tracing categories are used by this simulator.
+\verbatim
+--cfg=tracing/categorized:1
+\endverbatim
\li \c
tracing/uncategorized
@@ -125,6 +134,9 @@ tracing/uncategorized
It activates the uncategorized resource utilization tracing. Use it if
this simulator do not use tracing categories and resource use have to be
traced.
+\verbatim
+--cfg=tracing/uncategorized:1
+\endverbatim
\li \c
tracing/filename
@@ -134,6 +146,10 @@ tracing/filename
tools. More information can be found in these webpages:
http://triva.gforge.inria.fr/
http://paje.sourceforge.net/
+\verbatim
+--cfg=tracing/filename:mytracefile.trace
+\endverbatim
+ If you do not provide this parameter, the trace file will be named simgrid.trace.
\li \c
tracing/onelink_only
@@ -142,6 +158,9 @@ tracing/onelink_only
to re-create a "graph" of the platform and register it in the trace file.
This option let the user tell the tracing system to use only the routes
that are composed with just one link.
+\verbatim
+--cfg=tracing/onelink_only:1
+\endverbatim
\li \c
tracing/smpi
@@ -150,18 +169,27 @@ tracing/smpi
interface and generates a trace that can be analyzed using Gantt-like
visualizations. Every MPI function (implemented by SMPI) is transformed in a
state, and point-to-point communications can be analyzed with arrows.
+\verbatim
+--cfg=tracing/smpi:1
+\endverbatim
\li \c
tracing/smpi/group
:
This option only has effect if this simulator is SMPI-based. The processes
are grouped by the hosts where they were executed.
+\verbatim
+--cfg=tracing/smpi/group:1
+\endverbatim
\li \c
tracing/msg/task
:
This option only has effect if this simulator is MSG-based. It traces the
behavior of all categorized MSG tasks, grouping them by hosts.
+\verbatim
+--cfg=tracing/msg/task:1
+\endverbatim
\li \c
tracing/msg/process
@@ -169,18 +197,61 @@ tracing/msg/process
This option only has effect if this simulator is MSG-based. It traces the
behavior of all categorized MSG processes, grouping them by hosts. This option
can be used to track process location if this simulator has process migration.
+\verbatim
+--cfg=tracing/msg/process:1
+\endverbatim
\li \c
-triva/categorized:graph_categorized.plist
+triva/categorized
:
This option generates a graph configuration file for Triva considering
categorized resource utilization.
+\verbatim
+--cfg=triva/categorized:graph_categorized.plist
+\endverbatim
\li \c
-triva/uncategorized:graph_uncategorized.plist
+triva/uncategorized
:
This option generates a graph configuration file for Triva considering
uncategorized resource utilization.
+\verbatim
+--cfg=triva/categorized:graph_uncategorized.plist
+\endverbatim
+
+\subsection tracing_tracing_example_parameters Case studies
+
+Some scenarios that might help you decide which tracing options
+you should use to analyze your simulator.
+
+\li I want to trace the resource utilization of all hosts
+and links of the platform, and my simulator does not use
+the tracing API. For that, you can run a uncategorized trace
+with the following parameters (it will work with any Simgrid
+simulator):
+\verbatim
+./your_simulator \
+ --cfg=tracing:1 \
+ --cfg=tracing/uncategorized:1 \
+ --cfg=tracing/filename:mytracefile.trace \
+ --cfg=triva/uncategorized:uncat.plist
+\endverbatim
+
+\li I want to trace only a subset of my MSG (or SimDAG) tasks.
+For that, you will need to create tracing categories using the
+TRACE_category (...) function (as explained above),
+and then classify your tasks to a previously declared category
+using the TRACE_msg_set_task_category (...)
+(or TRACE_sd_set_task_category (...) for SimDAG tasks). After
+recompiling, run your simulator with the following parameters:
+\verbatim
+./your_simulator \
+ --cfg=tracing:1 \
+ --cfg=tracing/categorized:1 \
+ --cfg=tracing/filename:mytracefile.trace \
+ --cfg=triva/categorized:cat.plist
+\endverbatim
+
\subsection tracing_tracing_example Example of Instrumentation