\c category must contain a category that was previously defined by the function
\c TRACE_category.
+\li <b>\c TRACE_declare_mark(const char *mark_type)</b>: This function
+declares a new Paje event type in the trace file that can be used by
+simulators to declare application-level marks. This function is
+independent of which API is used in SimGrid.
+
+\li <b>\c TRACE_mark(const char *mark_type, const char *mark_value)</b>:
+This function creates a mark in the trace file. The first parameter
+had to be previously declared using \c TRACE_declare_mark, the second
+is the identifier for this mark instance. We recommend that the \c
+mark_value (the second parameter) is a unique value for the whole
+trace file (the whole simulation). Nevertheless, this is not a strong
+requirement: the trace will be valid if there are multiple mark
+identifiers for the same trace.
+
\li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
Declare a user variable that will be associated to host/link. A variable can
be used to trace user variables such as the number of tasks in a server,
the number of clients in an application (for hosts), and so on.
+\li <b>\c TRACE_[host|link]_variable_declare_with_color (const char
+*var, const char *color)</b>: Same as \c
+TRACE_[host|link]_variable_declare, but user decides which color will
+be assigned to the variable. The color needs to be a string with three
+numbers separated by spaces in the range [0,1]. A light-gray color can
+be specified using "0.7 0.7 0.7" as color.
+
\li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
Set the value of a given user variable for a given host/link. The value
of this variable is always associated to the host/link. The host/link
\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/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.
+\verbatim
+--cfg=tracing/categorized:1
+\endverbatim
\li <b>\c
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 <b>\c
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>
+\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
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.
+\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.
+\verbatim
+--cfg=tracing/msg/task:1
+\endverbatim
\li <b>\c
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 <b>\c
+tracing/buffer
+</b>:
+ This option put some events in a time-ordered buffer using the
+ insertion sort algorithm. The process of acquiring and releasing
+ locks to access this buffer and the cost of the sorting algorithm
+ make this process slow. The simulator performance can be severely
+ impacted if this option is activated, but you are sure to get a trace
+ file with events sorted.
+\verbatim
+--cfg=tracing/buffer:1
+\endverbatim
+
+\li <b>\c
+tracing/onelink_only
+</b>:
+This option changes the way SimGrid register its platform on the trace
+file. Normally, the tracing considers all routes (no matter their
+size) on the platform file to re-create the resource topology. If this
+option is activated, only the routes with one link are used to
+register the topology within an AS. Routes among AS continue to be
+traced as usual.
+\verbatim
+--cfg=tracing/onelink_only:1
+\endverbatim
+
+\li <b>\c
+tracing/disable_destroy
+</b>:
+Disable the destruction of containers at the end of simulation. This
+can be used with simulators that have a different notion of time
+(different from the simulated time).
+\verbatim
+--cfg=tracing/disable_destroy:1
+\endverbatim
\li <b>\c
-triva/categorized:graph_categorized.plist
+triva/categorized
</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
-triva/uncategorized:graph_uncategorized.plist
+triva/uncategorized
</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
