From: Frederic Suter Date: Fri, 15 Apr 2016 20:56:23 +0000 (+0200) Subject: revise documentation of tracing examples X-Git-Tag: v3_13~99 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/d0392de9a3c0fbe9065924ca323d78c99ed03c7c?hp=63f4cba590c1f4074f4891408b3a6cd6d8440eda revise documentation of tracing examples --- diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index c5e27c76cf..5800be45ea 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -706,13 +706,13 @@ INPUT += @CMAKE_HOME_DIRECTORY@/examples/msg/app-pingpong/app-pi @CMAKE_HOME_DIRECTORY@/examples/msg/process-migration/process-migration.c \ @CMAKE_HOME_DIRECTORY@/examples/msg/process-startkilltime/process-startkilltime.c \ @CMAKE_HOME_DIRECTORY@/examples/msg/trace-simple/trace-simple.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/tracing/ms.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/tracing/categories.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/tracing/procmig.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/tracing/trace_platform.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/tracing/user_variables.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/tracing/link_user_variables.c \ - @CMAKE_HOME_DIRECTORY@/examples/msg/tracing/link_srcdst_user_variables.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/trace-platform/trace-platform.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/trace-categories/trace-categories.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/trace-masterworker/trace-masterworker.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/trace-process-migration/trace-process-migration.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/trace-user-variables/trace-user-variables.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/trace-link-user-variables/trace-link-user-variables.c \ + @CMAKE_HOME_DIRECTORY@/examples/msg/trace-link-srcdst-user-variables/trace-link-srcdst-user-variables.c \ @CMAKE_HOME_DIRECTORY@/examples/msg/ns3 \ @CMAKE_HOME_DIRECTORY@/examples/msg/io \ @CMAKE_HOME_DIRECTORY@/examples/msg/gpu \ diff --git a/examples/msg/trace-categories/trace-categories.c b/examples/msg/trace-categories/trace-categories.c index 704ddc14ab..7f639f2a02 100644 --- a/examples/msg/trace-categories/trace-categories.c +++ b/examples/msg/trace-categories/trace-categories.c @@ -6,17 +6,11 @@ /** @addtogroup MSG_examples * - * - tracing/categories.c This is a master/worker program. The master creates tasks and send them to workers. - * For each task received, the worker executes it and then destroys it. This program declares several tracing categories + * - Setting Categories: trace-categories/trace-categories.c. This example declares several tracing categories * that are used to classify tasks. When the program is executed, the tracing mechanism registers the resource * utilization of hosts and links according to these categories. You might want to run this program with the following - * parameters: - * --cfg=tracing:yes - * --cfg=tracing/categorized:yes - * --cfg=tracing/uncategorized:yes - * --cfg=viva/categorized:viva_cat.plist - * --cfg=viva/uncategorized:viva_uncat.plist - * (See \ref tracing_tracing_options for details) + * options: --cfg=tracing:yes, --cfg=tracing/categorized:yes, --cfg=tracing/uncategorized:yes, + * --cfg=viva/categorized:viva_cat.plist, and --cfg=viva/uncategorized:viva_uncat.plist. */ #include "simgrid/msg.h" diff --git a/examples/msg/trace-link-srcdst-user-variables/trace-link-srcdst-user-variables.c b/examples/msg/trace-link-srcdst-user-variables/trace-link-srcdst-user-variables.c index c9c45038da..198f1533c5 100644 --- a/examples/msg/trace-link-srcdst-user-variables/trace-link-srcdst-user-variables.c +++ b/examples/msg/trace-link-srcdst-user-variables/trace-link-srcdst-user-variables.c @@ -8,15 +8,10 @@ /** @addtogroup MSG_examples * - * - tracing/link_srcdst_user_variables.c: This program demonstrates how to trace user variables associated to - * the links of the platform file. Instead of providing the name of the link to update one of its variable, this - * example shows how to provide two hosts as parameter (source and destination, use their names as defined in the - * platform file). The tracing mechanism will get the route between these two hosts, if there is one defined in the - * platform file, and update the variable of all the links of that route to the value provided. - * You might want to run this program with the following parameters: - * --cfg=tracing:yes - * --cfg=tracing/platform:yes - * (See \ref tracing_tracing_options for details) + * - Routes: trace-link-srcdst-user-variables/trace-link-srcdst-user-variables.c. Instead of providing the name + * of the link to update one of its variable, this example shows how to provide two hosts as parameter (source and + * destination, as defined in the platform file). The tracing mechanism will get the route between these two hosts, if + * it is defined in the platform file, and update the variable of all the links of that route to the value provided. */ //dump function to create and execute a task diff --git a/examples/msg/trace-link-user-variables/trace-link-user-variables.c b/examples/msg/trace-link-user-variables/trace-link-user-variables.c index 5c97ac6cb0..90d43b693b 100644 --- a/examples/msg/trace-link-user-variables/trace-link-user-variables.c +++ b/examples/msg/trace-link-user-variables/trace-link-user-variables.c @@ -8,12 +8,8 @@ /** @addtogroup MSG_examples * - * - tracing/link_user_variables.c: This program demonstrates how to trace user variables associated to the - * links of the platform file. You need to provide the name of the link to update the value of the variable associated - * to that link. You might want to run this program with the following parameters: - * --cfg=tracing:yes - * --cfg=tracing/platform:yes - * (See \ref tracing_tracing_options for details) + * - Links: trace-link-user-variables/trace-link-user-variables.c. You need to provide the name of the link to + * update the value of the variable associated to that link. */ //dump function to create and execute a task diff --git a/examples/msg/trace-masterworker/trace-masterworker.c b/examples/msg/trace-masterworker/trace-masterworker.c index 335dd095e0..ee5ffca02d 100644 --- a/examples/msg/trace-masterworker/trace-masterworker.c +++ b/examples/msg/trace-masterworker/trace-masterworker.c @@ -6,20 +6,17 @@ /** @addtogroup MSG_examples * - * - tracing/ms.c This is a master/worker program where the master creates tasks, send them to the workers. For - * each task received, the worker executes it and then destroys it. This program uses several tracing functions that - * enable the tracing of categorized resource utilization, the use of trace marks, and user variables associated to the - * hosts of the platform file. You might want to run this program with the following parameters: - * --cfg=tracing/categorized:yes - * --cfg=tracing/uncategorized:yes - * --cfg=viva/categorized:viva_cat.plist - * --cfg=viva/uncategorized:viva_uncat.plist - * (See \ref tracing_tracing_options for details) + * - Master/Worker: trace-masterworker/trace-masterworker.c This is an augmented version of our basic + * master/worker example. It uses several tracing functions that enable the tracing of categorized resource + * utilization, the use of trace marks, and user variables associated to the hosts of the platform file. You might + * want to run this program with the following configuration options: + * --cfg=tracing/categorized:yes, --cfg=tracing/uncategorized:yes, + * --cfg=viva/categorized:viva_cat.plist, and --cfg=viva/uncategorized:viva_uncat.plist. */ #include "simgrid/msg.h" -XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test, "Messages specific for this msg example"); +XBT_LOG_NEW_DEFAULT_CATEGORY(msg_trace_masterworker, "Messages specific for this msg example"); static int master(int argc, char *argv[]) { diff --git a/examples/msg/trace-masterworker/trace-masterworker.tesh b/examples/msg/trace-masterworker/trace-masterworker.tesh index f5cc1673e0..5e639c62c7 100644 --- a/examples/msg/trace-masterworker/trace-masterworker.tesh +++ b/examples/msg/trace-masterworker/trace-masterworker.tesh @@ -9,13 +9,13 @@ $ $SG_TEST_EXENV ${bindir:=.}/trace-masterworker$EXEEXT --cfg=tracing:yes --cfg= > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'tracing/uncategorized' to 'yes' > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'viva/categorized' to 'trace-masterworker.cat.plist' > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'viva/uncategorized' to 'trace-masterworker.uncat.plist' -> [4.214821] [msg_test/INFO] Declared tracing categories: -> [4.214821] [msg_test/INFO] request -> [4.214821] [msg_test/INFO] finalize -> [4.214821] [msg_test/INFO] report -> [4.214821] [msg_test/INFO] compute -> [4.214821] [msg_test/INFO] Declared marks: -> [4.214821] [msg_test/INFO] msmark +> [4.214821] [msg_trace_masterworker/INFO] Declared tracing categories: +> [4.214821] [msg_trace_masterworker/INFO] request +> [4.214821] [msg_trace_masterworker/INFO] finalize +> [4.214821] [msg_trace_masterworker/INFO] report +> [4.214821] [msg_trace_masterworker/INFO] compute +> [4.214821] [msg_trace_masterworker/INFO] Declared marks: +> [4.214821] [msg_trace_masterworker/INFO] msmark p Tracing master/worker application with xml config $ $SG_TEST_EXENV ${bindir:=.}/trace-masterworker$EXEEXT ${srcdir:=.}/config_tracing.xml ${srcdir:=.}/../msg/app-masterworker/app-masterworker_d.xml @@ -26,13 +26,13 @@ $ $SG_TEST_EXENV ${bindir:=.}/trace-masterworker$EXEEXT ${srcdir:=.}/config_trac > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'tracing/filename' to 'trace-masterworker.trace' > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'viva/uncategorized' to 'trace-masterworker.uncat.plist' > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'tracing/categorized' to 'yes' -> [4.214821] [msg_test/INFO] Declared tracing categories: -> [4.214821] [msg_test/INFO] request -> [4.214821] [msg_test/INFO] finalize -> [4.214821] [msg_test/INFO] report -> [4.214821] [msg_test/INFO] compute -> [4.214821] [msg_test/INFO] Declared marks: -> [4.214821] [msg_test/INFO] msmark +> [4.214821] [msg_trace_masterworker/INFO] Declared tracing categories: +> [4.214821] [msg_trace_masterworker/INFO] request +> [4.214821] [msg_trace_masterworker/INFO] finalize +> [4.214821] [msg_trace_masterworker/INFO] report +> [4.214821] [msg_trace_masterworker/INFO] compute +> [4.214821] [msg_trace_masterworker/INFO] Declared marks: +> [4.214821] [msg_trace_masterworker/INFO] msmark p Not tracing master/worker application $ $SG_TEST_EXENV ${bindir:=.}/trace-masterworker$EXEEXT ${srcdir:=.}/small_platform.xml ${srcdir:=.}/../msg/app-masterworker/app-masterworker_d.xml @@ -47,13 +47,13 @@ $ $SG_TEST_EXENV ${bindir:=.}/trace-masterworker$EXEEXT --cfg=tracing:yes --cfg= > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'tracing/uncategorized' to 'yes' > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'viva/categorized' to 'trace-masterworker.cat.plist' > [0.000000] [xbt_cfg/INFO] Configuration change: Set 'viva/uncategorized' to 'trace-masterworker.uncat.plist' -> [4.214821] [msg_test/INFO] Declared tracing categories: -> [4.214821] [msg_test/INFO] request -> [4.214821] [msg_test/INFO] finalize -> [4.214821] [msg_test/INFO] report -> [4.214821] [msg_test/INFO] compute -> [4.214821] [msg_test/INFO] Declared marks: -> [4.214821] [msg_test/INFO] msmark +> [4.214821] [msg_trace_masterworker/INFO] Declared tracing categories: +> [4.214821] [msg_trace_masterworker/INFO] request +> [4.214821] [msg_trace_masterworker/INFO] finalize +> [4.214821] [msg_trace_masterworker/INFO] report +> [4.214821] [msg_trace_masterworker/INFO] compute +> [4.214821] [msg_trace_masterworker/INFO] Declared marks: +> [4.214821] [msg_trace_masterworker/INFO] msmark $ $SG_TEST_EXENV cat trace-masterworker.uncat.plist > node = ("HOST","LINK"); diff --git a/examples/msg/trace-platform/trace-platform.c b/examples/msg/trace-platform/trace-platform.c index 6cb9d80f7f..0ca692d511 100644 --- a/examples/msg/trace-platform/trace-platform.c +++ b/examples/msg/trace-platform/trace-platform.c @@ -6,11 +6,9 @@ /** @addtogroup MSG_examples * - * - tracing/trace_platform.c: This program demonstrates how a platform file is traced to a Paje trace file - * format using the tracing mechanism of Simgrid. You might want to run this program with the following parameters: - * --cfg=tracing:yes - * --cfg=tracing/categorized:yes - * (See \ref tracing_tracing_options for details) + * - Tracing the platform: trace-platform/trace-platform.c. This example just loads a platform file to + * demonstrate how it can be traced into the Paje trace file format. You might want to run this program with the + * following options: --cfg=tracing:yes and --cfg=tracing/categorized:yes. */ #include "simgrid/msg.h" diff --git a/examples/msg/trace-process-migration/trace-process-migration.c b/examples/msg/trace-process-migration/trace-process-migration.c index 13f3955550..bcf83c2b19 100644 --- a/examples/msg/trace-process-migration/trace-process-migration.c +++ b/examples/msg/trace-process-migration/trace-process-migration.c @@ -6,12 +6,10 @@ /** @addtogroup MSG_examples * - * - tracing/procmig.c This program shows a process migration. Tracing this program with the options below - * enables a gantt-chart visualization of where the process has been during its execution. Migrations are represented by - * arrows from the origin to the destination host. You might want to run this program with the following parameters: - * --cfg=tracing:yes - * --cfg=tracing/msg/process:yes - * (See \ref tracing_tracing_options for details) + * - Process migration: trace-process-migration/trace-process-migration.c. Running this program with the + * --cfg=tracing:yes and --cfg=tracing/msg/process:yes options enables a Gantt-chart visualization of + * where the process has been hosted during its execution. Migrations are represented by arrows from the origin to + * the destination host. */ #include "simgrid/msg.h" diff --git a/examples/msg/trace-simple/trace-simple.c b/examples/msg/trace-simple/trace-simple.c index 27a08aa548..20b1395c30 100644 --- a/examples/msg/trace-simple/trace-simple.c +++ b/examples/msg/trace-simple/trace-simple.c @@ -8,12 +8,11 @@ /** @addtogroup MSG_examples * - * @section MSG_ex_tracing Tracing and vizualisation features - * - * - tracing/simple.c very simple program where each process creates, executes and destroy a task. You might want - * to run this program with the following parameters: - * --cfg=tracing/uncategorized:yes - * (See \ref tracing_tracing_options for details) + * @section MSG_ex_tracing Tracing and visualization features + * Tracing can be activated by various configuration options which are illustrated in these example. + * See \ref tracing_tracing_options for details. + * - Basic example: trace-simple/trace-simple.c. In this very simple program, each process creates, executes, + * and destroy a task. You might want to run it with the --cfg=tracing/uncategorized:yes option. */ static int simple_func(int argc, char *argv[]) diff --git a/examples/msg/trace-user-variables/trace-user-variables.c b/examples/msg/trace-user-variables/trace-user-variables.c index 35100475f2..31b32a60c3 100644 --- a/examples/msg/trace-user-variables/trace-user-variables.c +++ b/examples/msg/trace-user-variables/trace-user-variables.c @@ -5,12 +5,14 @@ * under the terms of the license (GNU LGPL) which comes with this package. */ /** @addtogroup MSG_examples + * + * @section MSG_ex_tracing_user_variables Tracing user variables + * The tracing mechanism of SimGrid also allows to associate user variables to resources described in the platform file. + * The following examples illustrate this feature. They have to be run with the --cfg=tracing:yes and + * --cfg=tracing/platform:yes options. * - * - tracing/user_variables.c: This program demonstrates how to trace user variables associated to the hosts of - * the platform file. You might want to run this program with the following parameters: - * --cfg=tracing:yes - * --cfg=tracing/platform:yes - * (See \ref tracing_tracing_options for details) + * - Hosts: trace-user-variables/trace-user-variables.c. This example shows how user defined variables can be + * associated to an host and how to manage the tracing of their evolution. */ #include #include "simgrid/msg.h"