/*! \page tracing Tracing Simulations for Visualization
\htmlinclude .tracing.doc.toc
\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
two-step fashion: the user instruments the application and the traces are
analyzed after the end of the execution. The visualization itself can highlights
unexpected behaviors, bottlenecks and sometimes can be used to correct
distributed algorithms. The SimGrid team has instrumented the library
in order to let users trace their simulations and analyze them. This part of the
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
For now, the SimGrid library is instrumented so users can trace the platform
utilization using the MSG, SimDAG and SMPI interface. This means that the tracing will
register how much power is used for each host and how much bandwidth is used for
each link of the platform. The idea with this type of tracing is to observe the
overall view of resources utilization in the first place, especially the
identification of bottlenecks, load-balancing among hosts, and so on.
The idea of the tracing facilities is to give SimGrid users to possibility to
classify MSG and SimDAG tasks by category, tracing the platform utilization
(hosts and links) for each of the categories. For that,
the tracing interface enables the declaration of categories and a function to
mark a task with a previously declared category. The tasks that are not
classified according to a category are not traced. Even if the user
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
With the sources of SimGrid, it is possible to enable the tracing
using the parameter -Denable_tracing=ON when the cmake is executed.
The section \ref tracing_tracing_functions describes all the functions available
when this Cmake options is activated. These functions will have no effect
if SimGrid is configured without this option (they are wiped-out by the
C-preprocessor).
\verbatim
$ cmake -Denable_tracing=ON .
$ make
\endverbatim
\subsection tracing_tracing_functions Tracing Functions
\li \c TRACE_category (const char *category): This function should be used
to define a user category. The category can be used to differentiate the tasks
that are created during the simulation (for example, tasks from server1,
server2, or request tasks, computation tasks, communication tasks).
All resource utilization (host power and link bandwidth) will be
classified according to the task category. Tasks that do not belong to a
category are not traced. The color for the category that is being declared
is random (use next function to specify a color).
\li \c TRACE_category_with_color (const char *category, const char *color): Same
as TRACE_category, but let user specify a color encoded as a RGB-like string with
three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
\li \c TRACE_msg_set_task_category (m_task_t task, const char *category):
This function should be called after the creation of a MSG task, to define the
category of that task. The first parameter \c task must contain a task that was
created with the function \c MSG_task_create. The second parameter
\c category must contain a category that was previously defined by the function
\c TRACE_category.
\li \c TRACE_sd_set_task_category (SD_task_t task, const char *category):
This function should be called after the creation of a SimDAG task, to define the
category of that task. The first parameter \c task must contain a task that was
created with the function \c MSG_task_create. The second parameter
\c category must contain a category that was previously defined by the function
\c TRACE_category.
\li \c TRACE_[host|link]_variable_declare (const char *variable):
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 \c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value):
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
parameters should be its name as the one listed in the platform file.
\li \c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value):
Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
the time used to trace it. Users can specify a time that is not the
simulated clock time as defined by the core simulator. This allows
a fine-grain control of time definition, but should be used with
caution since the trace can be inconsistent if resource utilization
traces are also traced.
\li \c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value):
Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
destination hosts (as the names from the platform file). The tracing library
will get the corresponding route that connects those two hosts (src and dst) and
[set|add|sub] the value's variable for all the links of the route.
\li \c TRACE_link_srcdst_variable_[set|add|sub]_with_time (double time, const char *src, const char *dst, const char *variable, double value):
Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
\subsection tracing_tracing_options Tracing configuration Options
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
:
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
:
A file with this name will be created to register the simulation. The file
is in the Paje format and can be analyzed using Triva or Paje visualization
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
:
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 \c
tracing/smpi
:
This option only has effect if this simulator is SMPI-based. Traces the MPI
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
:
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
:
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
:
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
A simplified example using the tracing mandatory functions.
\verbatim
int main (int argc, char **argv)
{
MSG_global_init (&argc, &argv);
//(... after deployment ...)
//note that category declaration must be called after MSG_create_environment
TRACE_category_with_color ("request", "1 0 0");
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);
TRACE_msg_set_task_category (req1, "request");
TRACE_msg_set_task_category (req2, "request");
TRACE_msg_set_task_category (req3, "request");
TRACE_msg_set_task_category (req4, "request");
m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
TRACE_msg_set_task_category (comp, "computation");
m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
TRACE_msg_set_task_category (finalize, "finalize");
//(...)
MSG_clean();
return 0;
}
\endverbatim
\subsection 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
that was executed. The visualization analysis of this file is performed with the
visualization tool Triva, with
special configurations tunned to SimGrid needs. This part of the documentation
explains how to configure and use Triva to analyse a SimGrid trace file.
- Installing Triva: the tool is available in the INRIAGforge,
at http://triva.gforge.inria.fr.
Use the following command to get the sources, and then check the file
INSTALL. This file contains instructions to install
the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
be compiled in MacOSes natively, check INSTALL.mac file.
\verbatim
$ svn checkout svn://scm.gforge.inria.fr/svn/triva
$ cd triva
$ cat INSTALL
\endverbatim
- Executing Triva: a binary called Triva is available after the
installation (you can execute it passing --help to check its
options). If the triva binary is not available after following the
installation instructions, you may want to execute the following command to
initialize the GNUstep environment variables. We strongly recommend that you
use the latest GNUstep packages, and not the packages available through apt-get
in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
available packages, you can execute this command:
\verbatim
$ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
\endverbatim
You should be able to see this output after the installation of triva:
\verbatim
$ ./Triva.app/Triva --help
Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
Trace Analysis through Visualization
TimeInterval
--ti_frequency {double} Animation: frequency of updates
--ti_hide Hide the TimeInterval window
--ti_forward {double} Animation: value to move time-slice
--ti_apply Apply the configuration
--ti_update Update on slider change
--ti_animate Start animation
--ti_start {double} Start of time slice
--ti_size {double} Size of time slice
Triva
--comparison Compare Trace Files (Experimental)
--graph Configurable Graph
--list Print Trace Type Hierarchy
--hierarchy Export Trace Type Hierarchy (dot)
--stat Trace Statistics and Memory Utilization
--instances List All Trace Entities
--linkview Link View (Experimental)
--treemap Squarified Treemap
--merge Merge Trace Files (Experimental)
--check Check Trace File Integrity
GraphConfiguration
--gc_conf {file} Graph Configuration in Property List Format
--gc_apply Apply the configuration
--gc_hide Hide the GraphConfiguration window
\endverbatim
Triva expects that the user choose one of the available options
(currently --graph or --treemap for a visualization analysis)
and the trace file from the simulation.
- Understanding Triva - time-slice: the analysis of a trace file using
the tool always takes into account the concept of the time-slice.
This concept means that what is being visualized in the screen is always
calculated considering a specific time frame, with its beggining and end
timestamp. The time-slice is configured by the user and can be changed
dynamically through the window called Time Interval that is opened
whenever a trace file is being analyzed. The next figure depicts the time-slice
configuration window.
In the top of the window, in the space named Trace Time,
the two fields show the beggining of the trace (which usually starts in 0) and
the end (that depends on the time simulated by SimGrid). The middle of the
window, in the square named Time Slice Configuration, contains the
aspects related to the time-slice, including its start and its
size. The gray rectangle in the bottom of this part indicates the
current time-slice that is considered for the drawings. If the checkbox
Update Drawings on Sliders Change is not selected, the button
Apply must be clicked in order to inform triva that the
new time-slice must be considered. The bottom part of the window, in the space
indicated by the square Time Slice Animation can be used to advance
the time-frame automatically. The user configures the amount of time that the
time-frame will forward and how frequent this update will happen. Once this is
configured, the user clicks the Play button in order to see the dynamic
changes on the drawings.
\htmlonly
\endhtmlonly
Remarks: when the trace has too many hosts or links, the computation to
take into account a new time-slice can be expensive. When this happens, the
Frequency parameter, but also updates caused by change on configurations
when the checkbox Update Drawings on Sliders
Change is selected will not be followed.
- Understanding Triva - graph: this part of the documention explains how
to analyze the traces using the graph view of Triva, when the user executes
the tool passing --graph as parameter. Triva opens three windows when
this parameter is used: the Time Interval window (previously described),
the Graph Representation window, and the Graph Configuration
window. The Graph Representation is the window where drawings take place.
Initially, it is completely white waiting for a proper graph configuration input
by the user. We start the description of this type of analysis by describing the
Graph Configuration window (depicted below). By using a particular
configuration, triva
can be used to customize the graph drawing according to
the SimGrid trace that was created with user-specific categories. Before delving
into the details of this customization, let us first explain the major parts of
the graph configuration window. The buttons located in the top-right corner can
be used to delete, copy and create a new configuration. The checkbox in the
top-middle part of the window indicates if the configuration typed in the
textfield is syntactically correct (we are using the non-XML
Property List Format to
describe the configuration). The pop-up button located on the top-left corner
indicates the selected configuration (the user can have multiple graph
configurations). The bottom-left text field contains the name of the current
configuration (updates on this field must be followed by typing enter on the
keyboard to take into account the name change). The bottom-right Apply
button activates the current configuration, resulting on an update on the graph
drawings.
\htmlonly
\endhtmlonly
Basic SimGrid Configuration: The figure shows in the big textfield the
basic configuration that should be used during the analysis of a SimGrid trace
file. The basic logic of the configuration is as follows:
\verbatim
{
node = (HOST);
edge = (LINK);
\endverbatim
The nodes of the graph will be created based on the node parameter, which
in this case is the different "HOST"s of the platform
used to simulate. The edge parameter indicates that the edges of the
graph will be created based on the "LINK"s of the platform. After the
definition of these two parameters, the configuration must detail how
HOSTs and LINKs should be drawn. For that, the configuration
must have an entry for each of the types used. For HOST, as basic
configuration, we have:
\verbatim
HOST = {
size = power;
scale = global;
};
\endverbatim
The parameter size indicates which variable from the trace file will be
used to define the size of the node HOST in the visualization. If the simulation
was executed with availability traces, the size of the nodes will be changed
according to these traces. The parameter scale indicates if the value
of the variable is global or local. If it is global, the value
will be relative to the power of all other hosts, if it is local, the value will
be relative locally.
For LINK we have:
\verbatim
LINK = {
src = source;
dst = destination;
size = bandwidth;
scale = global;
};
\endverbatim
For the types specified in the edge parameter (such as LINK),
the configuration must contain two additional parameters: src and
dst that are used to properly identify which nodes this edge is
connecting. The values source and destination are always present
in the SimGrid trace file and should not be changed in the configuration. The
parameter size for the LINK, in this case, is configured as the
variable bandwidth, with a global scale. The scale meaning
here is exactly the same used for nodes. The last parameter is the GraphViz
algorithm used to calculate the position of the nodes in the graph
representation.
\verbatim
graphviz-algorithm = neato;
}
\endverbatim
Customizing the Graph Representation: triva is capable to handle
a customized graph representation based on the variables present in the trace
file. In the case of SimGrid, every time a category is created for tasks, two
variables in the trace file are defined: one to indicate node utilization (how
much power was used by that task category), and another to indicate link
utilization (how much bandwidth was used by that category). For instance, if the
user declares a category named request, there will be variables named
prequest and a brequest (p for power and
b for bandwidth). It is important to notice that the variable
prequest in this case is only available for HOST, and
brequest is only available for LINK. Example: suppose there are
two categories for tasks: request and compute. To create a customized graph
representation with a proportional separation of host and link utilization, use
as configuration for HOST and LINK this:
\verbatim
HOST = {
size = power;
scale = global;
sep_host = {
type = separation;
size = power;
values = (prequest, pcomputation);
};
};
LINK = {
src = source;
dst = destination;
size = bandwidth;
scale = global;
sep_link = {
type = separation;
size = bandwidth;
values = (brequest, bcomputation);
};
};
\endverbatim
Where sep_host contains a composition of type separation where
its max size is the power of the host and the variables prequest
and pcomputation are drawn proportionally to the size of the HOST. And
sep_link is also a separation where max is defined as the
bandwidth of the link, and the variables brequest and
bcomputation are drawn proportionally within a LINK.
This configuration enables the analysis of resource utilization by MSG tasks,
and the identification of load-balancing issues, network bottlenecks, for
instance. \n
Other compositions: besides separation, it is possible to use
other types of compositions, such as gradients, and colors, like this:
\verbatim
gra_host = {
type = gradient;
scale = global;
values = (numberOfTasks);
};
color_host = {
type = color;
values = (is_server);
};
\endverbatim
Where gra_host creates a gradient within a node of the graph, using a
global scale and using as value a variable called numberOfTasks, that
could be declared by the user using the optional tracing functions of SimGrid.
If scale is global, the max and min value for the gradient will be equal to the
max and min numberOfTasks among all hosts, and if scale is local, the max and
min value based on the value of numberOfTasks locally in each host.
And color_host composition draws a square based on a positive value of
the variable is_server, that could also be defined by the user using the
SimGrid tracing functions. \n
The Graph Visualization: The next figure shows a graph visualization of a
given time-slice of the masterslave_forwarder example (present in the SimGrid
sources). The red color indicates tasks from the compute category. This
visualization was generated with the following configuration:
\verbatim
{
node = (HOST);
edge = (LINK);
HOST = {
size = power;
scale = global;
sep_host = {
type = separation;
size = power;
values = (pcompute, pfinalize);
};
};
LINK = {
src = source;
dst = destination;
size = bandwidth;\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
two-step fashion: the user instruments the application and the traces are
analyzed after the end of the execution. The visualization itself can highlights
unexpected behaviors, bottlenecks and sometimes can be used to correct
distributed algorithms. The SimGrid team has instrumented the library
in order to let users trace their simulations and analyze them. This part of the
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
For now, the SimGrid library is instrumented so users can trace the platform
utilization using the MSG, SimDAG and SMPI interface. This means that the tracing will
register how much power is used for each host and how much bandwidth is used for
each link of the platform. The idea with this type of tracing is to observe the
overall view of resources utilization in the first place, especially the
identification of bottlenecks, load-balancing among hosts, and so on.
The idea of the tracing facilities is to give SimGrid users to possibility to
classify MSG and SimDAG tasks by category, tracing the platform utilization
(hosts and links) for each of the categories. For that,
the tracing interface enables the declaration of categories and a function to
mark a task with a previously declared category. The tasks that are not
classified according to a category are not traced. Even if the user
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
With the sources of SimGrid, it is possible to enable the tracing
using the parameter -Denable_tracing=ON when the cmake is executed.
The section \ref tracing_tracing_functions describes all the functions available
when this Cmake options is activated. These functions will have no effect
if SimGrid is configured without this option (they are wiped-out by the
C-preprocessor).
\verbatim
$ cmake -Denable_tracing=ON .
$ make
\endverbatim
\subsection tracing_tracing_functions Tracing Functions
\li \c TRACE_category (const char *category): This function should be used
to define a user category. The category can be used to differentiate the tasks
that are created during the simulation (for example, tasks from server1,
server2, or request tasks, computation tasks, communication tasks).
All resource utilization (host power and link bandwidth) will be
classified according to the task category. Tasks that do not belong to a
category are not traced. The color for the category that is being declared
is random (use next function to specify a color).
\li \c TRACE_category_with_color (const char *category, const char *color): Same
as TRACE_category, but let user specify a color encoded as a RGB-like string with
three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
\li \c TRACE_msg_set_task_category (m_task_t task, const char *category):
This function should be called after the creation of a MSG task, to define the
category of that task. The first parameter \c task must contain a task that was
created with the function \c MSG_task_create. The second parameter
\c category must contain a category that was previously defined by the function
\c TRACE_category.
\li \c TRACE_sd_set_task_category (SD_task_t task, const char *category):
This function should be called after the creation of a SimDAG task, to define the
category of that task. The first parameter \c task must contain a task that was
created with the function \c MSG_task_create. The second parameter
\c category must contain a category that was previously defined by the function
\c TRACE_category.
\li \c TRACE_[host|link]_variable_declare (const char *variable):
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 \c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value):
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
parameters should be its name as the one listed in the platform file.
\li \c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value):
Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
the time used to trace it. Users can specify a time that is not the
simulated clock time as defined by the core simulator. This allows
a fine-grain control of time definition, but should be used with
caution since the trace can be inconsistent if resource utilization
traces are also traced.
\li \c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value):
Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
destination hosts (as the names from the platform file). The tracing library
will get the corresponding route that connects those two hosts (src and dst) and
[set|add|sub] the value's variable for all the links of the route.
\li \c TRACE_link_srcdst_variable_[set|add|sub]_with_time (double time, const char *src, const char *dst, const char *variable, double value):
Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
\subsection tracing_tracing_options Tracing configuration Options
These are the options accepted by the tracing system of SimGrid:
\li \c
tracing
:
Safe switch. It activates (or deactivates) the tracing system.
No other tracing options take effect if this one is not activated.
\li \c
tracing/platform
:
Register the simulation platform in the trace file.
\li \c
tracing/onelink_only
:
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.
\li \c
tracing/categorized
:
It activates the categorized resource utilization tracing. It should
be enabled if tracing categories are used by this simulator.
\li \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.
\li \c
tracing/filename
:
A file with this name will be created to register the simulation. The file
is in the Paje format and can be analyzed using Triva or Paje visualization
tools. More information can be found in these webpages:
http://triva.gforge.inria.fr/
http://paje.sourceforge.net/
\li \c
tracing/smpi
:
This option only has effect if this simulator is SMPI-based. Traces the MPI
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.
\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.
\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.
\li \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.
\li \c
triva/categorized:graph_categorized.plist
:
This option generates a graph configuration file for Triva considering
categorized resource utilization.
\li \c
triva/uncategorized:graph_uncategorized.plist
:
This option generates a graph configuration file for Triva considering
uncategorized resource utilization.
\subsection 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);
//(... after deployment ...)
//note that category declaration must be called after MSG_create_environment
TRACE_category_with_color ("request", "1 0 0");
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);
TRACE_msg_set_task_category (req1, "request");
TRACE_msg_set_task_category (req2, "request");
TRACE_msg_set_task_category (req3, "request");
TRACE_msg_set_task_category (req4, "request");
m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
TRACE_msg_set_task_category (comp, "computation");
m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
TRACE_msg_set_task_category (finalize, "finalize");
//(...)
MSG_clean();
return 0;
}
\endverbatim
\subsection 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
that was executed. The visualization analysis of this file is performed with the
visualization tool Triva, with
special configurations tunned to SimGrid needs. This part of the documentation
explains how to configure and use Triva to analyse a SimGrid trace file.
- Installing Triva: the tool is available in the INRIAGforge,
at http://triva.gforge.inria.fr.
Use the following command to get the sources, and then check the file
INSTALL. This file contains instructions to install
the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
be compiled in MacOSes natively, check INSTALL.mac file.
\verbatim
$ svn checkout svn://scm.gforge.inria.fr/svn/triva
$ cd triva
$ cat INSTALL
\endverbatim
- Executing Triva: a binary called Triva is available after the
installation (you can execute it passing --help to check its
options). If the triva binary is not available after following the
installation instructions, you may want to execute the following command to
initialize the GNUstep environment variables. We strongly recommend that you
use the latest GNUstep packages, and not the packages available through apt-get
in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
available packages, you can execute this command:
\verbatim
$ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
\endverbatim
You should be able to see this output after the installation of triva:
\verbatim
$ ./Triva.app/Triva --help
Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
Trace Analysis through Visualization
TimeInterval
--ti_frequency {double} Animation: frequency of updates
--ti_hide Hide the TimeInterval window
--ti_forward {double} Animation: value to move time-slice
--ti_apply Apply the configuration
--ti_update Update on slider change
--ti_animate Start animation
--ti_start {double} Start of time slice
--ti_size {double} Size of time slice
Triva
--comparison Compare Trace Files (Experimental)
--graph Configurable Graph
--list Print Trace Type Hierarchy
--hierarchy Export Trace Type Hierarchy (dot)
--stat Trace Statistics and Memory Utilization
--instances List All Trace Entities
--linkview Link View (Experimental)
--treemap Squarified Treemap
--merge Merge Trace Files (Experimental)
--check Check Trace File Integrity
GraphConfiguration
--gc_conf {file} Graph Configuration in Property List Format
--gc_apply Apply the configuration
--gc_hide Hide the GraphConfiguration window
\endverbatim
Triva expects that the user choose one of the available options
(currently --graph or --treemap for a visualization analysis)
and the trace file from the simulation.
- Understanding Triva - time-slice: the analysis of a trace file using
the tool always takes into account the concept of the time-slice.
This concept means that what is being visualized in the screen is always
calculated considering a specific time frame, with its beggining and end
timestamp. The time-slice is configured by the user and can be changed
dynamically through the window called Time Interval that is opened
whenever a trace file is being analyzed. The next figure depicts the time-slice
configuration window.
In the top of the window, in the space named Trace Time,
the two fields show the beggining of the trace (which usually starts in 0) and
the end (that depends on the time simulated by SimGrid). The middle of the
window, in the square named Time Slice Configuration, contains the
aspects related to the time-slice, including its start and its
size. The gray rectangle in the bottom of this part indicates the
current time-slice that is considered for the drawings. If the checkbox
Update Drawings on Sliders Change is not selected, the button
Apply must be clicked in order to inform triva that the
new time-slice must be considered. The bottom part of the window, in the space
indicated by the square Time Slice Animation can be used to advance
the time-frame automatically. The user configures the amount of time that the
time-frame will forward and how frequent this update will happen. Once this is
configured, the user clicks the Play button in order to see the dynamic
changes on the drawings.
\htmlonly
\endhtmlonly
Remarks: when the trace has too many hosts or links, the computation to
take into account a new time-slice can be expensive. When this happens, the
Frequency parameter, but also updates caused by change on configurations
when the checkbox Update Drawings on Sliders
Change is selected will not be followed.
- Understanding Triva - graph: this part of the documention explains how
to analyze the traces using the graph view of Triva, when the user executes
the tool passing --graph as parameter. Triva opens three windows when
this parameter is used: the Time Interval window (previously described),
the Graph Representation window, and the Graph Configuration
window. The Graph Representation is the window where drawings take place.
Initially, it is completely white waiting for a proper graph configuration input
by the user. We start the description of this type of analysis by describing the
Graph Configuration window (depicted below). By using a particular
configuration, triva
can be used to customize the graph drawing according to
the SimGrid trace that was created with user-specific categories. Before delving
into the details of this customization, let us first explain the major parts of
the graph configuration window. The buttons located in the top-right corner can
be used to delete, copy and create a new configuration. The checkbox in the
top-middle part of the window indicates if the configuration typed in the
textfield is syntactically correct (we are using the non-XML
Property List Format to
describe the configuration). The pop-up button located on the top-left corner
indicates the selected configuration (the user can have multiple graph
configurations). The bottom-left text field contains the name of the current
configuration (updates on this field must be followed by typing enter on the
keyboard to take into account the name change). The bottom-right Apply
button activates the current configuration, resulting on an update on the graph
drawings.
\htmlonly
\endhtmlonly
Basic SimGrid Configuration: The figure shows in the big textfield the
basic configuration that should be used during the analysis of a SimGrid trace
file. The basic logic of the configuration is as follows:
\verbatim
{
node = (HOST);
edge = (LINK);
\endverbatim
The nodes of the graph will be created based on the node parameter, which
in this case is the different "HOST"s of the platform
used to simulate. The edge parameter indicates that the edges of the
graph will be created based on the "LINK"s of the platform. After the
definition of these two parameters, the configuration must detail how
HOSTs and LINKs should be drawn. For that, the configuration
must have an entry for each of the types used. For HOST, as basic
configuration, we have:
\verbatim
HOST = {
size = power;
scale = global;
};
\endverbatim
The parameter size indicates which variable from the trace file will be
used to define the size of the node HOST in the visualization. If the simulation
was executed with availability traces, the size of the nodes will be changed
according to these traces. The parameter scale indicates if the value
of the variable is global or local. If it is global, the value
will be relative to the power of all other hosts, if it is local, the value will
be relative locally.
For LINK we have:
\verbatim
LINK = {
src = source;
dst = destination;
size = bandwidth;
scale = global;
};
\endverbatim
For the types specified in the edge parameter (such as LINK),
the configuration must contain two additional parameters: src and
dst that are used to properly identify which nodes this edge is
connecting. The values source and destination are always present
in the SimGrid trace file and should not be changed in the configuration. The
parameter size for the LINK, in this case, is configured as the
variable bandwidth, with a global scale. The scale meaning
here is exactly the same used for nodes. The last parameter is the GraphViz
algorithm used to calculate the position of the nodes in the graph
representation.
\verbatim
graphviz-algorithm = neato;
}
\endverbatim
Customizing the Graph Representation: triva is capable to handle
a customized graph representation based on the variables present in the trace
file. In the case of SimGrid, every time a category is created for tasks, two
variables in the trace file are defined: one to indicate node utilization (how
much power was used by that task category), and another to indicate link
utilization (how much bandwidth was used by that category). For instance, if the
user declares a category named request, there will be variables named
prequest and a brequest (p for power and
b for bandwidth). It is important to notice that the variable
prequest in this case is only available for HOST, and
brequest is only available for LINK. Example: suppose there are
two categories for tasks: request and compute. To create a customized graph
representation with a proportional separation of host and link utilization, use
as configuration for HOST and LINK this:
\verbatim
HOST = {
size = power;
scale = global;
sep_host = {
type = separation;
size = power;
values = (prequest, pcomputation);
};
};
LINK = {
src = source;
dst = destination;
size = bandwidth;
scale = global;
sep_link = {
type = separation;
size = bandwidth;
values = (brequest, bcomputation);
};
};
\endverbatim
Where sep_host contains a composition of type separation where
its max size is the power of the host and the variables prequest
and pcomputation are drawn proportionally to the size of the HOST. And
sep_link is also a separation where max is defined as the
bandwidth of the link, and the variables brequest and
bcomputation are drawn proportionally within a LINK.
This configuration enables the analysis of resource utilization by MSG tasks,
and the identification of load-balancing issues, network bottlenecks, for
instance. \n
Other compositions: besides separation, it is possible to use
other types of compositions, such as gradients, and colors, like this:
\verbatim
gra_host = {
type = gradient;
scale = global;
values = (numberOfTasks);
};
color_host = {
type = color;
values = (is_server);
};
\endverbatim
Where gra_host creates a gradient within a node of the graph, using a
global scale and using as value a variable called numberOfTasks, that
could be declared by the user using the optional tracing functions of SimGrid.
If scale is global, the max and min value for the gradient will be equal to the
max and min numberOfTasks among all hosts, and if scale is local, the max and
min value based on the value of numberOfTasks locally in each host.
And color_host composition draws a square based on a positive value of
the variable is_server, that could also be defined by the user using the
SimGrid tracing functions. \n
The Graph Visualization: The next figure shows a graph visualization of a
given time-slice of the masterslave_forwarder example (present in the SimGrid
sources). The red color indicates tasks from the compute category. This
visualization was generated with the following configuration:
\verbatim
{
node = (HOST);
edge = (LINK);
HOST = {
size = power;
scale = global;
sep_host = {
type = separation;
size = power;
values = (pcompute, pfinalize);
};
};
LINK = {
src = source;
dst = destination;
size = bandwidth;
scale = global;
sep_link = {
type = separation;
size = bandwidth;
values = (bcompute, bfinalize);
};
};
graphviz-algorithm = neato;
}
\endverbatim
\htmlonly
\endhtmlonly
- Understading Triva - colors: An important issue when using Triva is how
to define colors. To do that, we have to know which variables are defined in
the trace file generated by the SimGrid library. The parameter --list
lists the variables for a given trace file:
\verbatim
$ Triva -l masterslave_forwarder.trace
iFile
c platform
c HOST
v power
v is_slave
v is_master
v task_creation
v task_computation
v pcompute
v pfinalize
c LINK
v bandwidth
v latency
v bcompute
v bfinalize
c user_type
\endverbatim
We can see that HOST has seven variables (from power to pfinalize) and LINK has
four (from bandwidth to bfinalize). To define a red color for the
pcompute and bcompute (which are defined based on user category
compute), execute:
\verbatim
$ defaults write Triva 'pcompute Color' '1 0 0'
$ defaults write Triva 'bcompute Color' '1 0 0'
\endverbatim
Where the three numbers in each line are the RGB color with values from 0 to 1.
\verbatim
scale = global;
sep_link = {
type = separation;
size = bandwidth;
values = (bcompute, bfinalize);
};
};
graphviz-algorithm = neato;
}
\endverbatim
\htmlonly
\endhtmlonly
- Understading Triva - colors: An important issue when using Triva is how
to define colors. To do that, we have to know which variables are defined in
the trace file generated by the SimGrid library. The parameter --list
lists the variables for a given trace file:
\verbatim
$ Triva -l masterslave_forwarder.trace
iFile
c platform
c HOST
v power
v is_slave
v is_master
v task_creation
v task_computation
v pcompute
v pfinalize
c LINK
v bandwidth
v latency
v bcompute
v bfinalize
c user_type
\endverbatim
We can see that HOST has seven variables (from power to pfinalize) and LINK has
four (from bandwidth to bfinalize). To define a red color for the
pcompute and bcompute (which are defined based on user category
compute), execute:
\verbatim
$ defaults write Triva 'pcompute Color' '1 0 0'
$ defaults write Triva 'bcompute Color' '1 0 0'
\endverbatim
Where the three numbers in each line are the RGB color with values from 0 to 1.
*/