X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/2cc20f1526f80e1c731e986a50c5b77fa7e223d8..e53420bc5ff10f8df9481033265fc04005b88ebc:/doc/options.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. -