- sep_link = {
- type = separation;
- size = bandwidth;
- values = (brequest, bcomputation);
- };
- };
-\endverbatim
-Where <i>sep_host</i> contains a composition of type <i>separation</i> where
-its max size is the <i>power</i> of the host and the variables <i>prequest</i>
-and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
-<i>sep_link</i> is also a separation where max is defined as the
-<i>bandwidth</i> of the link, and the variables <i>brequest</i> and
-<i>bcomputation</i> are drawn proportionally within a LINK.
-<i>This configuration enables the analysis of resource utilization by MSG tasks,
-and the identification of load-balancing issues, network bottlenecks, for
-instance.</i> \n
-<b>Other compositions</b>: besides <i>separation</i>, 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 <i>gra_host</i> creates a gradient within a node of the graph, using a
-global scale and using as value a variable called <i>numberOfTasks</i>, 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 <i>color_host</i> composition draws a square based on a positive value of
-the variable <i>is_server</i>, that could also be defined by the user using the
-SimGrid tracing functions. \n
-<b>The Graph Visualization</b>: 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 <i>compute</i> 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 <b>platform
-utilization</b> 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. <em>The tasks that are not
-classified according to a category are not traced</em>. 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 <b>-Denable_tracing=ON</b> 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 <b>\c TRACE_category (const char *category)</b>: 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 <b>\c TRACE_category_with_color (const char *category, const char *color)</b>: 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 <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
-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 <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
-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 <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
-Declare a user variable that will be associated to host/link. A variable can
-be used to trace user variables such as the number of tasks in a server,
-the number of clients in an application (for hosts), and so on.
-
-\li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
-Set the value of a given user variable for a given host/link. The value
-of this variable is always associated to the host/link. The host/link
-parameters should be its name as the one listed in the platform file.
-
-\li <b>\c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value)</b>:
-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 <b>\c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value)</b>:
-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 <b>\c TRACE_link_srcdst_variable_[set|add|sub]_with_time (double time, const char *src, const char *dst, const char *variable, double value)</b>:
-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 <b>\c
-tracing
-</b>:
- Safe switch. It activates (or deactivates) the tracing system.
- No other tracing options take effect if this one is not activated.
-
-\li <b>\c
-tracing/platform
-</b>:
- Register the simulation platform in the trace file.
-
-\li <b>\c
-tracing/onelink_only
-</b>:
- By default, the tracing system uses all routes in the platform file
- to re-create a "graph" of the platform and register it in the trace file.
- This option let the user tell the tracing system to use only the routes
- that are composed with just one link.
-
-\li <b>\c
-tracing/categorized
-</b>:
- It activates the categorized resource utilization tracing. It should
- be enabled if tracing categories are used by this simulator.
-
-\li <b>\c
-tracing/uncategorized
-</b>:
- 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 <b>\c
-tracing/filename
-</b>:
- 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:
- <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
- <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
-
-\li <b>\c
-tracing/smpi
-</b>:
- 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 <b>\c
-tracing/smpi/group
-</b>:
- This option only has effect if this simulator is SMPI-based. The processes
- are grouped by the hosts where they were executed.
-
-\li <b>\c
-tracing/msg/task
-</b>:
- This option only has effect if this simulator is MSG-based. It traces the
- behavior of all categorized MSG tasks, grouping them by hosts.
-
-\li <b>\c
-tracing/msg/process
-</b>:
- 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 <b>\c
-triva/categorized:graph_categorized.plist
-</b>:
- This option generates a graph configuration file for Triva considering
- categorized resource utilization.
-
-\li <b>\c
-triva/uncategorized:graph_uncategorized.plist
-</b>:
- This option generates a graph configuration file for Triva considering
- uncategorized resource utilization.