README.tracing

   1 ==========================================================
   2 ATTENTION
   3 This file is no longer updated (kept for a while for historical reasons).
   4 Check the FAQ on the SimGrid website for updated information about the
   5 tracing of simulations.
   6 ==========================================================
   7
   8              =======
   9 instrumented SimGrid
  10              =======
  11
  12 In order to trace the simulators created with the SimGrid toolkit and based on
  13 the MSG interface, you have to enable the instrumentation mechanisms with this
  14 option to the configure command (in addition to other options you may be already
  15 using):
  16
  17 $ ./configure --enable-tracing
  18
  19 By doing that, you will have access to a set of tracing functions that are
  20 described below. You can keep the calls for these functions in your code even if
  21 SimGrid was compiled without this configuration option.
  22
  23 Mandatory functions:
  24 =========
  25
  26 int TRACE_start(const char *filename);
  27
  28         This is the first function to be called. It receives a single argument
  29         as parameter that contains the name of the file that will hold the trace
  30         in the end of the simulation. It returns 1 if everything was properly
  31         initialized, 0 otherwise. All trace functions called before TRACE_start
  32         do nothing. By default, the instrumentation will trace the platform
  33         behavior (host and link utilization).
  34
  35 int TRACE_end (void);
  36
  37         This is the last function to be called. It closes the trace file and
  38         disable the tracing of the simulation. All trace functions called after
  39         TRACE_end do nothing.
  40
  41 void TRACE_category (const char *category);
  42
  43         This function should be used to define a user category. The category can
  44         be used to differentiate the tasks that are created during the
  45         simulation (for example, tasks from server1, server2, ...). All resource
  46         utilization (host power and link bandwidth) will be classified according
  47         to the task category. Tasks that do not belong to a category are not
  48         traced.
  49
  50 void TRACE_msg_set_task_category (m_task_t task, const char *category);
  51
  52         This function should be called after the creation of a task, to define
  53         the category of that task. Only tasks with a category are traced when
  54         TRACE_TASK is used as mask.
  55
  56
  57 Optional functions (that can be used if necessary):
  58 ========
  59
  60 void TRACE_set_mask (int mask);
  61
  62         This function can be used to control what is traced during the
  63         simulation. The user has four masks that can be used:
  64                 - TRACE_PLATFORM - trace resource (host,link) utilization
  65                 - TRACE_PROCESS - trace process behavior (suspend, execute)
  66                 - TRACE_TASK - trace task behavior (created, execute, comm)
  67                 - NO_TRACE - can be used to disable the traces for a moment
  68         The platform mask must be present in order to trace processes or tasks.
  69
  70 void TRACE_start_with_mask (const char *filename, int mask);
  71
  72         This function can be used to start the tracing with a different mask
  73         and replaces the use of TRACE_start. The initial mask defined with this
  74         function cannot be "extended" later with the TRACE_set_mask function.
  75         This means that if TRACE_start_with_mask is called with the mask
  76         (TRACE_PLATFORM|TRACE_TASK), the user cannot set the mask later to
  77         (TRACE_PLATFORM|TRACE_PROCESS), for instance. The best combinations of
  78         mask for tracing the current instrumentation are:
  79                 - (TRACE_PLATFORM|TRACE_TASK) or
  80                         Tasks are grouped by hosts.
  81                 - (TRACE_PLATFORM|TRACE_PROCESS) or
  82                         Processes are grouped by hosts.
  83                 - (TRACE_PLATFORM|TRACE_PROCESS|TRACE_TASK)
  84                         Processes are grouped by hosts, tasks by processes.
  85         Only tasks and processes belonging to a category are traced.
  86
  87 void TRACE_host_variable_declare (const char *variable);
  88
  89         Declare a user variable that will be associated to the host.
  90
  91 void TRACE_host_variable_set (const char *variable, double value);
  92 void TRACE_host_variable_add (const char *variable, double value);
  93 void TRACE_host_variable_sub (const char *variable, double value);
  94
  95         Set the value of a given user variable. It is important to remind that
  96         the value of this variable is always associated to the host. The host
  97         that will be used when these functions are called is the one returned by
  98         the function MSG_host_self().
  99
 100 void TRACE_define_type (const char *type,
 101                                 const char *parent_type,
 102                                 int final);
 103
 104         This function allows the definition of a type hierarchy that can be used
 105         to create different categories. This root of the type hierarchy is
 106         defined as "0", so the first level of type must be child of the type
 107         "0". The boolean parameter final (1 or 0) indicates if the categories
 108         of a given type will be used to mark MSG tasks or not. This is used to
 109         differentiate types that are defined only to group other types.
 110
 111 void TRACE_create_category (const char *category,
 112                                         const char *type,
 113                                         const char *parent_category);
 114
 115         This functions allows the creation of categories and a hierarchy of
 116         categories. Each category created with this function (first parameter)
 117         must belong to a given type previously defined with the
 118         TRACE_define_type. It has to be also a child of a previously created
 119         category, which is indicated by the parent_category. The user can
 120         created categories that are child of "0" if the type of this newly
 121         created category is also child of the type "0" (as defined by
 122         TRACE_define_type).
 123
 124 void TRACE_msg_set_process_category (m_process_t process, const char *category);
 125
 126         This function can be used to define the category of a process. The same
 127         categories declared for tasks can be used here. After setting the
 128         category of a process and enabling the mask TRACE_PROCESS, the
 129         instrumentation will trace the process behavior, such as the states for
 130         execution, suspend, and so on. Only processes with categories are traced
 131         when TRACE_PROCESS is enabled.