X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/a5aa425e34dc6eed6b22b99b69e53ecc634ac9b4..b8eff69e6f0fc093a4eafbfd34bcf2e8f083fb80:/doc/tracing.doc
diff --git a/doc/tracing.doc b/doc/tracing.doc
index c2882edb1e..b9bdcc848d 100644
--- a/doc/tracing.doc
+++ b/doc/tracing.doc
@@ -34,11 +34,13 @@ 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
+With the sources of SimGrid, it is possible to enable the tracing
+using the parameter -Denable_tracing=ON when the cmake is
+executed. The sections \ref instr_category_functions, \ref
+instr_mark_functions, and \ref instr_uservariables_functions describe
+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
@@ -46,83 +48,50 @@ $ 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_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
-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 instr_category_functions Tracing categories functions
+\li \c TRACE_category(const char *category)
+\li \c TRACE_category_with_color(const char *category, const char *color)
+\li \c MSG_task_set_category(m_task_t task, const char *category)
+\li \c MSG_task_get_category(m_task_t task)
+\li \c SD_task_set_category(SD_task_t task, const char *category)
+\li \c SD_task_get_category(SD_task_t task)
+
+\subsection instr_mark_functions Tracing marks functions
+\li \c TRACE_declare_mark(const char *mark_type)
+\li \c TRACE_mark(const char *mark_type, const char *mark_value)
+
+\subsection instr_uservariables_functions Tracing user variables functions
+
+For hosts:
+
+\li \c TRACE_host_variable_declare(const char *variable)
+\li \c TRACE_host_variable_declare_with_color(const char *variable, const char *color)
+\li \c TRACE_host_variable_set(const char *host, const char *variable, double value)
+\li \c TRACE_host_variable_add(const char *host, const char *variable, double value)
+\li \c TRACE_host_variable_sub(const char *host, const char *variable, double value)
+\li \c TRACE_host_variable_set_with_time(double time, const char *host, const char *variable, double value)
+\li \c TRACE_host_variable_add_with_time(double time, const char *host, const char *variable, double value)
+\li \c TRACE_host_variable_sub_with_time(double time, const char *host, const char *variable, double value)
+
+For links:
+
+\li \c TRACE_link_variable_declare(const char *variable)
+\li \c TRACE_link_variable_declare_with_color(const char *variable, const char *color)
+\li \c TRACE_link_variable_set(const char *link, const char *variable, double value)
+\li \c TRACE_link_variable_add(const char *link, const char *variable, double value)
+\li \c TRACE_link_variable_sub(const char *link, const char *variable, double value)
+\li \c TRACE_link_variable_set_with_time(double time, const char *link, const char *variable, double value)
+\li \c TRACE_link_variable_add_with_time(double time, const char *link, const char *variable, double value)
+\li \c TRACE_link_variable_sub_with_time(double time, const char *link, const char *variable, double value)
+
+For links, but use source and destination to get route:
+
+\li \c TRACE_link_srcdst_variable_set(const char *src, const char *dst, const char *variable, double value)
+\li \c TRACE_link_srcdst_variable_add(const char *src, const char *dst, const char *variable, double value)
+\li \c TRACE_link_srcdst_variable_sub(const char *src, const char *dst, const char *variable, double value)
+\li \c TRACE_link_srcdst_variable_set_with_time(double time, const char *src, const char *dst, const char *variable, double value)
+\li \c TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value)
+\li \c TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value)
\subsection tracing_tracing_options Tracing configuration Options
@@ -203,15 +172,6 @@ tracing/smpi/group
--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
:
@@ -273,7 +233,7 @@ triva/uncategorized
This option generates a graph configuration file for Triva considering
uncategorized resource utilization.
\verbatim
---cfg=triva/categorized:graph_uncategorized.plist
+--cfg=triva/uncategorized:graph_uncategorized.plist
\endverbatim
\subsection tracing_tracing_example_parameters Case studies
@@ -298,8 +258,8 @@ simulator):
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
+using the MSG_task_set_category (...)
+(or SD_task_set_category (...) for SimDAG tasks). After
recompiling, run your simulator with the following parameters:
\verbatim
./your_simulator \
@@ -330,16 +290,16 @@ int main (int argc, char **argv)
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");
+ MSG_task_set_category (req1, "request");
+ MSG_task_set_category (req2, "request");
+ MSG_task_set_category (req3, "request");
+ MSG_task_set_category (req4, "request");
m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
- TRACE_msg_set_task_category (comp, "computation");
+ MSG_task_set_category (comp, "computation");
m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
- TRACE_msg_set_task_category (finalize, "finalize");
+ MSG_task_set_category (finalize, "finalize");
//(...)
@@ -357,14 +317,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
@@ -449,89 +409,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
@@ -546,133 +488,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.
+- 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
+*/