X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/7a8cd62135619ad52e05ae1c929ef07e166e4260..00cd576021269f05e84dd36f3cee7afbfe90cede:/doc/doxygen/tracing.doc diff --git a/doc/doxygen/tracing.doc b/doc/doxygen/tracing.doc index a21a0492e1..418b1037b8 100644 --- a/doc/doxygen/tracing.doc +++ b/doc/doxygen/tracing.doc @@ -1,33 +1,16 @@ -/*! \page 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. - -\section 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. +/*! \page tracing Tracing Simulations + + +Tracing 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 analysis +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. \section tracing_tracing_enabling Enabling using CMake @@ -46,6 +29,26 @@ $ make \endverbatim \section instr_category_functions Tracing categories functions + +The SimGrid library is instrumented so users can trace the platform +utilization using MSG, SimDAG and SMPI interfaces. It registers 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. + +Another possibility is to trace resource utilization by +categories. Categorized resource utilization tracing gives SimGrid +users to possibility to classify MSG and SimDAG tasks by category, +tracing resource utilization for each of the categories. The functions +below let the user declare a category and apply it to tasks. 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 (see section \ref +tracing_tracing_options). + \li \c TRACE_category(const char *category) \li \c TRACE_category_with_color(const char *category, const char *color) \li \c MSG_task_set_category(msg_task_t task, const char *category) @@ -93,9 +96,11 @@ For links, but use source and destination to get route: \section tracing_tracing_options Tracing configuration Options To check which tracing options are available for your simulator, you -can just run it with the option --help-tracing. These are the -options accepted by the tracing system of SimGrid as of today, you -can use them by running your simulator with the --cfg= switch: +can just run it with the option \verbatim --help-tracing \endverbatim +to get a very detailed and updated explanation of each tracing +parameter. These are some of the options accepted by the tracing +system of SimGrid, you can use them by running your simulator with the +--cfg= switch: \li \c tracing @@ -129,10 +134,10 @@ tracing/uncategorized 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 + is in the Paje format and can be analyzed using Viva or Paje visualization tools. More information can be found in these webpages: - http://triva.gforge.inria.fr/ - http://paje.sourceforge.net/ + http://github.com/schnorr/viva/ + http://github.com/schnorr/pajeng/ \verbatim --cfg=tracing/filename:mytracefile.trace \endverbatim @@ -243,23 +248,26 @@ Use this to add the contents of a file to the top of the trace file as comment. \endverbatim \li \c -triva/categorized +viva/categorized : - This option generates a graph configuration file for Triva considering + This option generates a graph configuration file for Viva considering categorized resource utilization. \verbatim ---cfg=triva/categorized:graph_categorized.plist +--cfg=viva/categorized:graph_categorized.plist \endverbatim \li \c -triva/uncategorized +viva/uncategorized : - This option generates a graph configuration file for Triva considering + This option generates a graph configuration file for Viva considering uncategorized resource utilization. \verbatim ---cfg=triva/uncategorized:graph_uncategorized.plist +--cfg=viva/uncategorized:graph_uncategorized.plist \endverbatim +Please pass \verbatim --help-tracing \endverbatim to your simulator +for the updated list of tracing options. + \section tracing_tracing_example_parameters Case studies Some scenarios that might help you decide which tracing options @@ -275,7 +283,7 @@ simulator): --cfg=tracing:1 \ --cfg=tracing/uncategorized:1 \ --cfg=tracing/filename:mytracefile.trace \ - --cfg=triva/uncategorized:uncat.plist + --cfg=viva/uncategorized:uncat.plist \endverbatim \li I want to trace only a subset of my MSG (or SimDAG) tasks. @@ -290,7 +298,7 @@ recompiling, run your simulator with the following parameters: --cfg=tracing:1 \ --cfg=tracing/categorized:1 \ --cfg=tracing/filename:mytracefile.trace \ - --cfg=triva/categorized:cat.plist + --cfg=viva/categorized:cat.plist \endverbatim @@ -332,123 +340,106 @@ int main (int argc, char **argv) } \endverbatim -\section 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 Inria's Forge, -at http://triva.gforge.inria.fr. -Use the following command to get the sources, and then check the file -INSTALL. This file contains instructions to install -the tool's dependencies in a Ubuntu/Debian Linux. The tool can also -be compiled in MacOSX natively, check INSTALL.mac file. -\verbatim -$ git clone git://scm.gforge.inria.fr/triva/triva.git -$ 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. -