X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/831e34878ba25882be7666abe43fc101b63eb3b9..7f4e90c90bde9bc53b419e1626c9caeac5ad25fc:/doc/tracing.doc
diff --git a/doc/tracing.doc b/doc/tracing.doc
index dbf0a3191f..2c590eeb83 100644
--- a/doc/tracing.doc
+++ b/doc/tracing.doc
@@ -76,11 +76,32 @@ 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_declare_mark(const char *mark_type): 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 \c TRACE_mark(const char *mark_type, const char *mark_value):
+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 \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_declare_with_color (const char
+*var, const char *color): 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 \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
@@ -105,27 +126,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.
-
-\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: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
@@ -133,6 +155,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
@@ -142,6 +167,21 @@ 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
+:
+ 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
@@ -150,18 +190,18 @@ 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.
-
-\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/smpi/group:1
+\endverbatim
\li \c
tracing/msg/process
@@ -169,519 +209,97 @@ 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;
-}
+--cfg=tracing/msg/process:1
\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.
+\li \c
+tracing/buffer
+:
+ 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
-$ svn checkout svn://scm.gforge.inria.fr/svn/triva
-$ cd triva
-$ cat INSTALL
+--cfg=tracing/buffer:1
\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:
+\li \c
+tracing/onelink_only
+:
+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
-$ ./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
+--cfg=tracing/onelink_only:1
\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:
+\li \c
+tracing/disable_destroy
+:
+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
- LINK = {
- src = source;
- dst = destination;
-
- size = bandwidth;
- scale = global;
- };
+--cfg=tracing/disable_destroy:1
\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.
+
+\li \c
+triva/categorized
+:
+ This option generates a graph configuration file for Triva considering
+ categorized resource utilization.
\verbatim
- graphviz-algorithm = neato;
-}
+--cfg=triva/categorized:graph_categorized.plist
\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:
+\li \c
+triva/uncategorized
+:
+ This option generates a graph configuration file for Triva considering
+ uncategorized resource utilization.
\verbatim
- gra_host = {
- type = gradient;
- scale = global;
- values = (numberOfTasks);
- };
- color_host = {
- type = color;
- values = (is_server);
- };
+--cfg=triva/uncategorized:graph_uncategorized.plist
\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_example_parameters Case studies
-\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).
+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
-$ cmake -Denable_tracing=ON .
-$ make
+./your_simulator \
+ --cfg=tracing:1 \
+ --cfg=tracing/uncategorized:1 \
+ --cfg=tracing/filename:mytracefile.trace \
+ --cfg=triva/uncategorized:uncat.plist
\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 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
-\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
@@ -730,14 +348,14 @@ 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,
+- Installing Triva: the tool is available in the Inria's Forge,
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.
+be compiled in MacOSX natively, check INSTALL.mac file.
\verbatim
-$ svn checkout svn://scm.gforge.inria.fr/svn/triva
+$ git clone git://scm.gforge.inria.fr/triva/triva.git
$ cd triva
$ cat INSTALL
\endverbatim
@@ -822,89 +440,71 @@ take into account a new time-slice can be expensive. When this happens, the
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:
+- Understanding Triva - graph: one possibility to analyze
+ SimGrid traces is to use Triva's graph view, using the
+ --graph parameter to activate this view, and
+ --gc_conf with a graph configuration to customize the graph
+ according to the traces. A valid graph configuration (we are using
+ the non-XML Property List
+ Format to describe the configuration) can be created for any
+ SimGrid-based simulator using the
+ --cfg=triva/uncategorized:graph_uncategorized.plist or
+ --cfg=triva/categorized:graph_categorized.plist (if the
+ simulator defines resource utilization categories) when executing
+ the simulation.
+
+Basic SimGrid Configuration: The basic description of the configuration
+is as follows:
\verbatim
{
- node = (HOST);
- edge = (LINK);
+ node = (LINK, HOST, );
+ edge = (HOST-LINK, LINK-HOST, LINK-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:
+
+The nodes of the graph will be created based on the node
+parameter, which in this case is the different "HOST"s and
+"LINK"s of the platform used to simulate. The edge
+parameter indicates that the edges of the graph will be created based
+on the "HOST-LINK"s, "LINK-HOST"s, and
+"LINK-LINK"s of the platform. After the definition of these
+two parameters, the configuration must detail how the nodes
+(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 = {
+ type = square;
size = power;
- scale = global;
+ values = (power_used);
};
\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.
+
+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 type indicates which geometrical shape
+will be used to represent HOST, and the values parameter
+indicates which values from the trace will be used to fill the shape.
+
For LINK we have:
-\verbatim
+
+\verbatim
LINK = {
- src = source;
- dst = destination;
-
+ type = rhombus;
size = bandwidth;
- scale = global;
+ values = (bandwidth_used);
};
-\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
+
+The same configuration parameters are used here: type (with a
+rhombus), the size (whose value is from trace's bandwidth
+variable) and the values.
+
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
@@ -919,183 +519,55 @@ user declares a category named request, there will be variables named
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 = {
+ type = square;
size = power;
- scale = global;
-
- sep_host = {
- type = separation;
- size = power;
- values = (prequest, pcomputation);
- };
+ values = (prequest, pcomputation);
};
-
LINK = {
- src = source;
- dst = destination;
+ type = rhombus;
size = bandwidth;
- scale = global;
-
- sep_link = {
- type = separation;
- size = bandwidth;
- values = (brequest, bcomputation);
- };
+ 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,
+
+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
+instance. \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);
+ node = (LINK, HOST, );
+ edge = (HOST-LINK, LINK-HOST, LINK-LINK, );
- HOST = {
+ host = {
+ type = square;
size = power;
- scale = global;
-
- sep_host = {
- type = separation;
- size = power;
- values = (pcompute, pfinalize);
- };
+ values = (pcompute, pfinalize);
};
- LINK = {
- src = source;
- dst = destination;
+ link = {
+ type = rhombus;
size = bandwidth;
- scale = global;
-
- sep_link = {
- type = separation;
- size = bandwidth;
- values = (bcompute, bfinalize);
- };
+ 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.
+- Understading Triva - colors: Colors are now registered in
+trace files. See the tracing API to how to define them for your
+simulator.
-*/
\ No newline at end of file
+*/