Merge branch 'master' into MC_LTL

[simgrid.git] / doc / tracing.doc

diff --git a/doc/tracing.doc b/doc/tracing.doc
index dbf0a31..4a7fe28 100644 (file)
--- a/doc/tracing.doc
+++ b/doc/tracing.doc
@@ -105,27 +105,28 @@ Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time differ
 
 \subsection tracing_tracing_options Tracing configuration Options
 
 
 \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 <b>--help-tracing</b>. These are the
+options accepted by the tracing system of SimGrid as of today, you
+can use them by running your simulator with the <b>--cfg=</b> switch:

 
 \li <b>\c 
 tracing
 </b>:
   Safe switch. It activates (or deactivates) the tracing system.
   No other tracing options take effect if this one is not activated.
 
 \li <b>\c 
 tracing
 </b>:
   Safe switch. It activates (or deactivates) the tracing system.
   No other tracing options take effect if this one is not activated.

-
-\li <b>\c
-tracing/onelink_only
-</b>:
-  By default, the tracing system uses all routes in the platform file
-  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:1
+\endverbatim

 
 \li <b>\c 
 tracing/categorized
 </b>:
   It activates the categorized resource utilization tracing. It should
   be enabled if tracing categories are used by this simulator.
 
 \li <b>\c 
 tracing/categorized
 </b>:
   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 <b>\c 
 tracing/uncategorized
 
 \li <b>\c 
 tracing/uncategorized


@@ -133,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.
   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 <b>\c 
 tracing/filename
 
 \li <b>\c 
 tracing/filename


@@ -142,6 +146,21 @@ tracing/filename
   tools. More information can be found in these webpages:
      <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
      <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
   tools. More information can be found in these webpages:
      <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
      <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>

+\verbatim
+--cfg=tracing/filename:mytracefile.trace
+\endverbatim
+  If you do not provide this parameter, the trace file will be named simgrid.trace.
+
+\li <b>\c
+tracing/onelink_only
+</b>:
+  By default, the tracing system uses all routes in the platform file
+  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 <b>\c 
 tracing/smpi
 
 \li <b>\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.
   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 <b>\c 
 tracing/smpi/group
 </b>:
   This option only has effect if this simulator is SMPI-based. The processes
   are grouped by the hosts where they were executed.
 
 \li <b>\c 
 tracing/smpi/group
 </b>:
   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 <b>\c 
 tracing/msg/task
 </b>:
   This option only has effect if this simulator is MSG-based. It traces the
   behavior of all categorized MSG tasks, grouping them by hosts.
 
 \li <b>\c 
 tracing/msg/task
 </b>:
   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 <b>\c 
 tracing/msg/process
 
 \li <b>\c 
 tracing/msg/process


@@ -169,19 +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.
   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 <b>\c 
 
 \li <b>\c 

-triva/categorized:graph_categorized.plist
+triva/categorized

 </b>:
   This option generates a graph configuration file for Triva considering
   categorized resource utilization.
 </b>:
   This option generates a graph configuration file for Triva considering
   categorized resource utilization.

+\verbatim
+--cfg=triva/categorized:graph_categorized.plist
+\endverbatim

 
 \li <b>\c 
 
 \li <b>\c 

-triva/uncategorized:graph_uncategorized.plist
+triva/uncategorized

 </b>:
   This option generates a graph configuration file for Triva considering
   uncategorized resource utilization.
 </b>:
   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 <b>does not</b> use
+the tracing API. For that, you can run a uncategorized trace
+with the following parameters (it will work with <b>any</b> 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
+<b>TRACE_category (...)</b> function (as explained above),
+and then classify your tasks to a previously declared category
+using the <b>TRACE_msg_set_task_category (...)</b>
+(or <b>TRACE_sd_set_task_category (...)</b> 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
 
 
 \subsection tracing_tracing_example Example of Instrumentation