From 1fcc8dd3e67dc3f7c1e789459028a361a1c86b5f Mon Sep 17 00:00:00 2001 From: Navarrop Date: Mon, 12 Sep 2011 10:20:05 +0200 Subject: [PATCH] Add tracing.doc and generate it. --- buildtools/Cmake/DefinePackages.cmake | 1 + buildtools/Cmake/GenerateDoc.cmake | 2 +- doc/Doxyfile.in | 1 + doc/options.doc | 551 ------------ doc/tracing.doc | 1106 ++++++++++++++++++++++++ tools/doxygen/doxygen_postprocesser.pl | 6 +- 6 files changed, 1113 insertions(+), 554 deletions(-) create mode 100644 doc/tracing.doc diff --git a/buildtools/Cmake/DefinePackages.cmake b/buildtools/Cmake/DefinePackages.cmake index 0bdbe8e07b..814e0f242b 100644 --- a/buildtools/Cmake/DefinePackages.cmake +++ b/buildtools/Cmake/DefinePackages.cmake @@ -571,6 +571,7 @@ set(DOC_SOURCES doc/bindings.doc doc/options.doc doc/use.doc + doc/tracing.doc doc/gtnets.doc doc/ns3.doc doc/gtut-howto-design.doc diff --git a/buildtools/Cmake/GenerateDoc.cmake b/buildtools/Cmake/GenerateDoc.cmake index 8ab90a6cf1..288f2ef251 100644 --- a/buildtools/Cmake/GenerateDoc.cmake +++ b/buildtools/Cmake/GenerateDoc.cmake @@ -88,7 +88,7 @@ if(DOXYGEN_PATH AND FIG2DEV_PATH AND BIBTOOL_PATH AND BIBTEX2HTML_PATH AND ICONV COMMAND ${CMAKE_COMMAND} -E echo "XX First Doxygen pass" COMMAND ${DOXYGEN_PATH}/doxygen Doxyfile COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/index_create.pl simgrid.tag index-API.doc - COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/toc_create.pl index.doc gtut-introduction.doc installSimgrid.doc bindings.doc options.doc + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/toc_create.pl index.doc gtut-introduction.doc installSimgrid.doc bindings.doc options.doc tracing.doc COMMAND ${CMAKE_COMMAND} -E echo "XX Second Doxygen pass" COMMAND ${DOXYGEN_PATH}/doxygen Doxyfile diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 38f6d9478a..4932bb5aa1 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -617,6 +617,7 @@ INPUT = index.doc \ installSimgrid.doc \ bindings.doc \ options.doc \ + tracing.doc \ use.doc \ gtnets.doc \ ns3.doc \ diff --git a/doc/options.doc b/doc/options.doc index 086012d3b5..8badcdc5d2 100644 --- a/doc/options.doc +++ b/doc/options.doc @@ -65,557 +65,6 @@ Long description of the network models accepted by this simulator: Vegas: Model using lagrange_solve instead of lmm_solve (experts only) \endverbatim -\section options_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 options_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 options_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 options_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 options_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 options_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 options_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 options_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. - \section options_modelchecking Model-Checking \subsection options_modelchecking_howto How to use it To enable the experimental SimGrid model-checking support the program should diff --git a/doc/tracing.doc b/doc/tracing.doc new file mode 100644 index 0000000000..6c30f7b8c2 --- /dev/null +++ b/doc/tracing.doc @@ -0,0 +1,1106 @@ +/*! \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 + +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;\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. + +*/ \ No newline at end of file diff --git a/tools/doxygen/doxygen_postprocesser.pl b/tools/doxygen/doxygen_postprocesser.pl index 026d291ff9..5ba927c692 100755 --- a/tools/doxygen/doxygen_postprocesser.pl +++ b/tools/doxygen/doxygen_postprocesser.pl @@ -5,7 +5,7 @@ use strict; # Add here the pages of the documentation generated by a @page doxygen macro my @extra_files = qw(html/index.html html/pages.html html/modules.html html/annotated.html html/functions.html html/functions_vars.html index.php - html/GRAS_tut.html html/installSimgrid.html html/bindings.html html/options.html html/use.html html/gtnets.html + html/GRAS_tut.html html/tracing.html html/installSimgrid.html html/bindings.html html/options.html html/use.html html/gtnets.html html/ns3.html); # GRAS tutorial @@ -392,7 +392,8 @@ foreach my $file (@allfiles) { # Fix the current "button" of buggy Doxygen tabs if($file =~ /^html\/use.*/ || $file =~ /^html\/installSimgrid.*/ - || $file =~ /^html\/options.*/ + || $file =~ /^html\/options.*/ + || $file =~ /^html\/tracing.*/ || $file =~ /^html\/bindings.*/ || $file =~ /^html\/gtnets.*/ || $file =~ /^html\/ns3.*/ @@ -405,6 +406,7 @@ foreach my $file (@allfiles) { $tmp_buff .= '
  • Modules API
    • '."\n"; $tmp_buff .= '
  • Data Structures
    • '."\n"; $tmp_buff .= '
  • Options & configurations
    • '."\n"; + $tmp_buff .= '
  • Tracing Simulations
    • '."\n"; $tmp_buff .= '
  • Bindings
    • '."\n"; $tmp_buff .= '
  • GTNets
    • '."\n"; $tmp_buff .= '
  • NS3
    • '."\n"; -- 2.20.1