src/instr/instr_interface.cpp

   1 /* Copyright (c) 2010-2023. The SimGrid Team. All rights reserved.          */
   2
   3 /* This program is free software; you can redistribute it and/or modify it
   4  * under the terms of the license (GNU LGPL) which comes with this package. */
   5
   6 #include <simgrid/Exception.hpp>
   7 #include <simgrid/kernel/routing/NetPoint.hpp>
   8 #include <simgrid/s4u/Engine.hpp>
   9 #include <xbt/random.hpp>
  10
  11 #include "src/instr/instr_private.hpp"
  12 #include "src/kernel/resource/StandardLinkImpl.hpp"
  13 #include <algorithm>
  14 #include <cmath>
  15
  16 enum class InstrUserVariable { DECLARE, SET, ADD, SUB };
  17
  18 XBT_LOG_NEW_DEFAULT_SUBCATEGORY (instr_api, instr, "API");
  19
  20 static std::set<std::string, std::less<>> created_categories;
  21 static std::set<std::string, std::less<>> declared_marks;
  22 static std::set<std::string, std::less<>> user_host_variables;
  23 static std::set<std::string, std::less<>> user_vm_variables;
  24 static std::set<std::string, std::less<>> user_link_variables;
  25
  26 static void instr_user_variable(double time, const std::string& resource, const std::string& variable_name,
  27                                 const std::string& parent_type, double value, InstrUserVariable what,
  28                                 const std::string& color, std::set<std::string, std::less<>>* filter)
  29 {
  30   /* safe switches. tracing has to be activated and if platform is not traced, we don't allow user variables */
  31   if (not TRACE_is_enabled() || not TRACE_needs_platform())
  32     return;
  33
  34   // check if variable is already declared
  35   auto created = filter->find(variable_name);
  36   if (what == InstrUserVariable::DECLARE) {
  37     if (created == filter->end()) { // not declared yet
  38       filter->insert(variable_name);
  39       instr_new_user_variable_type(parent_type, variable_name, color);
  40     }
  41   } else {
  42     if (created != filter->end()) { // declared, let's work
  43       simgrid::instr::VariableType* variable =
  44           simgrid::instr::Container::by_name(resource)->get_variable(variable_name);
  45       switch (what) {
  46         case InstrUserVariable::SET:
  47           variable->set_event(time, value);
  48           break;
  49         case InstrUserVariable::ADD:
  50           variable->add_event(time, value);
  51           break;
  52         case InstrUserVariable::SUB:
  53           variable->sub_event(time, value);
  54           break;
  55         default:
  56           THROW_IMPOSSIBLE;
  57       }
  58     }
  59   }
  60 }
  61
  62 static void instr_user_srcdst_variable(double time, const std::string& src, const std::string& dst,
  63                                        const std::string& variable, double value, InstrUserVariable what)
  64 {
  65   const auto* engine  = simgrid::s4u::Engine::get_instance();
  66   const auto* src_elm = engine->netpoint_by_name_or_null(src);
  67   xbt_assert(src_elm, "Element '%s' not found!", src.c_str());
  68
  69   const auto* dst_elm = engine->netpoint_by_name_or_null(dst);
  70   xbt_assert(dst_elm, "Element '%s' not found!", dst.c_str());
  71
  72   std::vector<simgrid::kernel::resource::StandardLinkImpl*> route;
  73   simgrid::kernel::routing::NetZoneImpl::get_global_route(src_elm, dst_elm, route, nullptr);
  74   for (auto const& link : route)
  75     instr_user_variable(time, link->get_cname(), variable, "LINK", value, what, "", &user_link_variables);
  76 }
  77
  78 namespace simgrid::instr {
  79 /* for host variables */
  80 /** @brief Declare a new user variable associated to hosts.
  81  *
  82  *  Declare a user variable that will be associated to hosts.
  83  *  A user host variable can be used to trace user variables such as the number of tasks in a server, the number of
  84  *  clients in an application (for hosts), and so on. The color associated to this new variable will be random if
  85  *  not given as parameter.
  86  */
  87 void declare_host_variable(const std::string& variable, const std::string& color)
  88 {
  89   instr_user_variable(0, "", variable, "HOST", 0, InstrUserVariable::DECLARE, color, &user_host_variables);
  90 }
  91
  92 void set_host_variable(const std::string& host, const std::string& variable, double value, double time)
  93 {
  94   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SET, "", &user_host_variables);
  95 }
  96
  97 /** @brief Add a value to a variable of a host */
  98 void add_host_variable(const std::string& host, const std::string& variable, double value, double time)
  99 {
 100   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::ADD, "", &user_host_variables);
 101 }
 102
 103 /** @brief Subtract a value to a variable of a host */
 104 void sub_host_variable(const std::string& host, const std::string& variable, double value, double time)
 105 {
 106   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SUB, "", &user_host_variables);
 107 }
 108
 109 /** @brief Get host variables that were already declared with #declare_host_variable. */
 110 const std::set<std::string, std::less<>>& get_host_variables()
 111 {
 112   return user_host_variables;
 113 }
 114
 115 /* for link variables */
 116 /** @brief Declare a new user variable associated to links.
 117  *
 118  *  Declare a user variable that will be associated to links.
 119  *  A user link variable can be used, for example, to trace user variables such as the number of messages being
 120  *  transferred through network links. The color associated to this new variable will be random if not given as
 121  *  parameter.
 122  */
 123 void declare_link_variable(const std::string& variable, const std::string& color)
 124 {
 125   instr_user_variable(0, "", variable, "LINK", 0, InstrUserVariable::DECLARE, color, &user_link_variables);
 126 }
 127
 128 /** @brief Set the value of a variable of a link */
 129 void set_link_variable(const std::string& link, const std::string& variable, double value, double time)
 130 {
 131   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SET, "", &user_link_variables);
 132 }
 133
 134 void set_link_variable(const std::string& src, const std::string& dst, const std::string& variable, double value,
 135                        double time)
 136 {
 137   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::SET);
 138 }
 139
 140 /** @brief Add a value to a variable of a link */
 141 void add_link_variable(const std::string& link, const std::string& variable, double value, double time)
 142 {
 143   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::ADD, "", &user_link_variables);
 144 }
 145
 146 /** @brief Add a value to a variable of a link */
 147 void add_link_variable(const std::string& src, const std::string& dst, const std::string& variable, double value,
 148                        double time)
 149 {
 150   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::ADD);
 151 }
 152
 153 /** @brief Subtract a value to a variable of a link */
 154 void sub_link_variable(const std::string& link, const std::string& variable, double value, double time)
 155 {
 156   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SUB, "", &user_link_variables);
 157 }
 158
 159 /** @brief Subtract a value to a variable of a link */
 160 void sub_link_variable(const std::string& src, const std::string& dst, const std::string& variable, double value,
 161                        double time)
 162 {
 163   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::SUB);
 164 }
 165
 166 /** @brief Get link variables that were already declared with #declare_link_variable. */
 167 const std::set<std::string, std::less<>>& get_link_variables()
 168 {
 169   return user_link_variables;
 170 }
 171
 172 /* for VM variables */
 173 /** @brief Declare a new user variable associated to VMs.
 174  *
 175  *  Declare a user variable that will be associated to VMs. A user host variable can be used to trace user variables
 176  *  such as the number of tasks in a VM, the number of clients in an application (for hosts), and so on. The color
 177  *  associated to this new variable will be random if not given as parameter.
 178  */
 179 void declare_vm_variable(const std::string& variable, const std::string& color)
 180 {
 181   instr_user_variable(0, "", variable, "VM", 0, InstrUserVariable::DECLARE, color, &user_vm_variables);
 182 }
 183
 184 /** @brief Set the value of a variable of a vm */
 185 void set_vm_variable(const std::string& vm, const std::string& variable, double value, double time)
 186 {
 187   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SET, "", &user_vm_variables);
 188 }
 189
 190 /** @brief Add a value to a variable of a VM */
 191 void add_vm_variable(const std::string& vm, const std::string& variable, double value, double time)
 192 {
 193   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::ADD, "", &user_vm_variables);
 194 }
 195
 196 /** @brief Subtract a value from a variable of a VM */
 197 void sub_vm_variable(const std::string& vm, const std::string& variable, double value, double time)
 198 {
 199   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SUB, "", &user_vm_variables);
 200 }
 201
 202 /** @brief Get VM variables that were already declared with #declare_vm_variable. */
 203 const std::set<std::string, std::less<>>& get_vm_variables()
 204 {
 205   return user_vm_variables;
 206 }
 207
 208 /**@brief Declare a new type for tracing mark.
 209  *
 210  * This function declares a new Paje event type in the trace file that can be used by simulators to declare
 211  * application-level marks. This function is independent of which API is used in SimGrid.
 212  */
 213 void declare_mark(const std::string& mark_type)
 214 {
 215   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
 216   if (not TRACE_is_enabled() || not TRACE_needs_platform())
 217     return;
 218
 219   // check if mark_type is already declared
 220   if (declared_marks.find(mark_type) != declared_marks.end()) {
 221     throw TracingError(XBT_THROW_POINT,
 222                        xbt::string_printf("mark_type with name (%s) is already declared", mark_type.c_str()));
 223   }
 224
 225   XBT_DEBUG("MARK,declare %s", mark_type.c_str());
 226   Container::get_root()->get_type()->by_name_or_create<EventType>(mark_type);
 227   declared_marks.emplace(mark_type);
 228 }
 229
 230 /** @brief Declare a new colored value for a previously declared mark type.
 231  *
 232  * This function declares a new colored value for a Paje event type in the trace file that can be used by simulators to
 233  * declare application-level marks. This function is independent of which API is used in SimGrid. The color needs to be
 234  * a string with three numbers separated by spaces in the range [0,1].
 235  * A light-gray color can be specified using "0.7 0.7 0.7" as color. If no color is provided, the default color used
 236  * will be white ("1 1 1").
 237  */
 238 void declare_mark_value(const std::string& mark_type, const std::string& mark_value, const std::string& mark_color)
 239 {
 240   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
 241   if (not TRACE_is_enabled() || not TRACE_needs_platform())
 242     return;
 243
 244   auto* type = static_cast<EventType*>(Container::get_root()->get_type()->by_name(mark_type));
 245   if (not type) {
 246     throw TracingError(XBT_THROW_POINT,
 247                        xbt::string_printf("mark_type with name (%s) is not declared", mark_type.c_str()));
 248   } else {
 249     XBT_DEBUG("MARK, declare_value %s %s %s", mark_type.c_str(), mark_value.c_str(), mark_color.c_str());
 250     type->add_entity_value(mark_value, mark_color);
 251   }
 252 }
 253
 254 /** @brief Create a new instance of a tracing mark type.
 255  *
 256  * This function creates a mark in the trace file. The first parameter had to be previously declared using
 257  * #declare_mark, the second is the identifier for this mark instance. We recommend that the mark_value is a
 258  * unique value for the whole simulation. Nevertheless, this is not a strong requirement: the trace will be valid even
 259  * if there are multiple mark identifiers for the same trace.
 260  */
 261 void mark(const std::string& mark_type, const std::string& mark_value)
 262 {
 263   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
 264   if (not TRACE_is_enabled() || not TRACE_needs_platform())
 265     return;
 266
 267   // check if mark_type is already declared
 268   auto* type = static_cast<EventType*>(Container::get_root()->get_type()->by_name(mark_type));
 269   if (not type) {
 270     throw TracingError(XBT_THROW_POINT,
 271                        xbt::string_printf("mark_type with name (%s) is not declared", mark_type.c_str()));
 272   } else {
 273     XBT_DEBUG("MARK %s %s", mark_type.c_str(), mark_value.c_str());
 274     new NewEvent(simgrid_get_clock(), Container::get_root(), type, type->get_entity_value(mark_value));
 275   }
 276 }
 277
 278 /** @brief Get marks that were already declared with #declare_mark. */
 279 const std::set<std::string, std::less<>>& get_marks()
 280 {
 281   return declared_marks;
 282 }
 283
 284 /** @brief Declare a new category.
 285  *
 286  *  This function should be used to define a user category. The category can be used to differentiate the tasks that
 287  *  are created during the simulation (for example, tasks from server1, server2, or request tasks, computation tasks,
 288  *  communication tasks). All resource utilization (host power and link bandwidth) will be classified according to the
 289  *  task category. Tasks that do not belong to a category are not traced. The color for the category that is being
 290  *  declared is random. This function has no effect if a category with the same name has been already declared.
 291  *
 292  * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
 293  */
 294 void declare_tracing_category(const std::string& name, const std::string& color)
 295 {
 296   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with categories */
 297   if (not TRACE_is_enabled() || not TRACE_needs_platform() || not TRACE_categorized())
 298     return;
 299
 300   // check if category is already created
 301   if (created_categories.find(name) != created_categories.end())
 302     return;
 303
 304   created_categories.emplace(name);
 305
 306   // define final_color
 307   std::string final_color;
 308   if (color.empty()) {
 309     // generate a random color
 310     double red   = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
 311     double green = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
 312     double blue  = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
 313     final_color  = std::to_string(red) + " " + std::to_string(green) + " " + std::to_string(blue);
 314   } else {
 315     final_color = color;
 316   }
 317
 318   XBT_DEBUG("CAT,declare %s, \"%s\" \"%s\"", name.c_str(), color.c_str(), final_color.c_str());
 319
 320   // define the type of this category on top of hosts and links
 321   instr_new_variable_type(name, final_color);
 322 }
 323
 324 /** @brief Get categories that were already declared with #declare_tracing_category.
 325  *
 326  * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
 327  */
 328 const std::set<std::string, std::less<>>& get_tracing_categories()
 329 {
 330   return created_categories;
 331 }
 332
 333 } // namespace simgrid::instr
 334
 335 /** @ingroup TRACE_user_variables
 336  *  @brief Declare a new user state associated to hosts.
 337  *
 338  *  Declare a user state that will be associated to hosts.
 339  *  A user host state can be used to trace application states.
 340  *
 341  *  @param state The name of the new state to be declared.
 342  *
 343  *  @see TRACE_host_state_declare_value
 344  */
 345 void TRACE_host_state_declare (const char *state)
 346 {
 347   instr_new_user_state_type("HOST", state);
 348 }
 349
 350 /** @ingroup TRACE_user_variables
 351  *  @brief Declare a new value for a user state associated to hosts.
 352  *
 353  *  Declare a value for a state. The color needs to be a string with 3 numbers separated by spaces in the range [0,1].
 354  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
 355  *
 356  *  @param state The name of the new state to be declared.
 357  *  @param value The name of the value
 358  *  @param color The color of the value
 359  *
 360  *  @see TRACE_host_state_declare
 361  */
 362 void TRACE_host_state_declare_value (const char *state, const char *value, const char *color)
 363 {
 364   instr_new_value_for_user_state_type (state, value, color);
 365 }
 366
 367 /** @ingroup TRACE_user_variables
 368  *  @brief Set the user state to the given value.
 369  *
 370  *  Change a user state previously declared to the given value.
 371  *
 372  *  @param host The name of the host to be considered.
 373  *  @param state_name The name of the state previously declared.
 374  *  @param value_name The new value of the state.
 375  *
 376  *  @see TRACE_host_state_declare, TRACE_host_push_state, TRACE_host_pop_state
 377  */
 378 void TRACE_host_set_state(const char* host, const char* state_name, const char* value_name)
 379 {
 380   simgrid::instr::StateType* state = simgrid::instr::Container::by_name(host)->get_state(state_name);
 381   state->add_entity_value(value_name);
 382   state->set_event(value_name);
 383 }
 384
 385 /** @ingroup TRACE_user_variables
 386  *  @brief Push a new value for a state of a given host.
 387  *
 388  *  Change a user state previously declared by pushing the new value to the state.
 389  *
 390  *  @param host The name of the host to be considered.
 391  *  @param state_name The name of the state previously declared.
 392  *  @param value_name The value to be pushed.
 393  *
 394  *  @see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_pop_state
 395  */
 396 void TRACE_host_push_state(const char* host, const char* state_name, const char* value_name)
 397 {
 398   simgrid::instr::Container::by_name(host)->get_state(state_name)->push_event(value_name);
 399 }
 400
 401 /** @ingroup TRACE_user_variables
 402  *  @brief Pop the last value of a state of a given host.
 403  *
 404  *  Change a user state previously declared by removing the last value of the state.
 405  *
 406  *  @param host The name of the host to be considered.
 407  *  @param state_name The name of the state to be popped.
 408  *
 409  *  @see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state
 410  */
 411 void TRACE_host_pop_state(const char* host, const char* state_name)
 412 {
 413   simgrid::instr::Container::by_name(host)->get_state(state_name)->pop_event();
 414 }