X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/2be0e4648c5b7055580df1c265b7c43ee6763a46..05db1dcff50b437219a10237de09ec792e40a840:/doc/tracing.doc diff --git a/doc/tracing.doc b/doc/tracing.doc index c67ff5118b..6b61e35da6 100644 --- a/doc/tracing.doc +++ b/doc/tracing.doc @@ -46,28 +46,11 @@ $ 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. +\subsection instr_category_functions Tracing categories functions +\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(m_task_t task, const char *category) +\li \c MSG_task_get_category(m_task_t task) \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 @@ -76,53 +59,42 @@ 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_declare_mark(const char *mark_type): This function -declares a new Paje event type in the trace file that can be used by -simulators to declare application-level marks. This function is -independent of which API is used in SimGrid. - -\li \c TRACE_mark(const char *mark_type, const char *mark_value): -This function creates a mark in the trace file. The first parameter -had to be previously declared using \c TRACE_declare_mark, the second -is the identifier for this mark instance. We recommend that the \c -mark_value (the second parameter) is a unique value for the whole -trace file (the whole simulation). Nevertheless, this is not a strong -requirement: the trace will be valid if there are multiple mark -identifiers for the same trace. - -\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_declare_with_color (const char -*var, const char *color): Same as \c -TRACE_[host|link]_variable_declare, but user decides which color will -be assigned to the variable. The color needs to be a string with three -numbers separated by spaces in the range [0,1]. A light-gray color can -be specified using "0.7 0.7 0.7" as color. - -\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 instr_mark_functions Tracing marks functions +\li \c TRACE_declare_mark(const char *mark_type) +\li \c TRACE_mark(const char *mark_type, const char *mark_value) + +\subsection instr_uservariables_functions Tracing user variables functions + +For hosts: + +\li \c TRACE_host_variable_declare(const char *variable) +\li \c TRACE_host_variable_declare_with_color(const char *variable, const char *color) +\li \c TRACE_host_variable_set(const char *host, const char *variable, double value) +\li \c TRACE_host_variable_add(const char *host, const char *variable, double value) +\li \c TRACE_host_variable_sub(const char *host, const char *variable, double value) +\li \c TRACE_host_variable_set_with_time(double time, const char *host, const char *variable, double value) +\li \c TRACE_host_variable_add_with_time(double time, const char *host, const char *variable, double value) +\li \c TRACE_host_variable_sub_with_time(double time, const char *host, const char *variable, double value) + +For links: + +\li \c TRACE_link_variable_declare(const char *variable) +\li \c TRACE_link_variable_declare_with_color(const char *variable, const char *color) +\li \c TRACE_link_variable_set(const char *link, const char *variable, double value) +\li \c TRACE_link_variable_add(const char *link, const char *variable, double value) +\li \c TRACE_link_variable_sub(const char *link, const char *variable, double value) +\li \c TRACE_link_variable_set_with_time(double time, const char *link, const char *variable, double value) +\li \c TRACE_link_variable_add_with_time(double time, const char *link, const char *variable, double value) +\li \c TRACE_link_variable_sub_with_time(double time, const char *link, const char *variable, double value) + +For links, but use source and destination to get route: + +\li \c TRACE_link_srcdst_variable_set(const char *src, const char *dst, const char *variable, double value) +\li \c TRACE_link_srcdst_variable_add(const char *src, const char *dst, const char *variable, double value) +\li \c TRACE_link_srcdst_variable_sub(const char *src, const char *dst, const char *variable, double value) +\li \c TRACE_link_srcdst_variable_set_with_time(double time, const char *src, const char *dst, const char *variable, double value) +\li \c TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value) +\li \c TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value) \subsection tracing_tracing_options Tracing configuration Options @@ -203,15 +175,6 @@ tracing/smpi/group --cfg=tracing/smpi/group:1 \endverbatim -\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. -\verbatim ---cfg=tracing/msg/task:1 -\endverbatim - \li \c tracing/msg/process : @@ -579,4 +542,4 @@ visualization was generated with the following configuration: trace files. See the tracing API to how to define them for your simulator. -*/ \ No newline at end of file +*/