docs/source/Outcomes.rst

   1 .. _outcomes:
   2
   3 Simulation outcomes
   4 ###################
   5
   6 .. raw:: html
   7
   8    <object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
   9    <script>
  10    window.onload=function() { // Wait for the SVG to be loaded before changing it
  11      //var elem=document.querySelector("#TOC").contentDocument.getElementById("DeployBox")
  12      //elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
  13    }
  14    </script>
  15    <br/>
  16    <br/>
  17
  18 .. _outcome_logs:
  19
  20 Textual logging
  21 ***************
  22
  23 Using ``printf`` or ``println`` to display information is possible, but quickly unpractical, as the logs of all processes get intermixed in your program's output. Instead, you
  24 should use SimGrid's logging facilities, that are inspired from `Log4J <https://en.wikipedia.org/wiki/Log4j>`_. This way, you can filter the messages at runtime, based on their
  25 severity and their topic. There  is four main concepts in SimGrid's logging mechanism:
  26
  27 The **category** of a message represents its topic. These categories are organized as a hierarchy, loosely corresponding to SimGrid's modules architecture. :ref:`Existing categories
  28 <logging_categories>` are documented online, but some of them may be disabled depending on the compilation options. Use ``--help-log-categories`` on the command line to see
  29 the categories actually provided a given simulator.
  30
  31 The message **priority** represents its severity. It can be one of ``trace``, ``debug``, ``verb``, ``info``, ``warn``, ``error`` and ``critical``. Every category has a configured
  32 threshold, and only the messages with a higher severity are displayed (the others are not even evaluated). For example, you may want to see every debugging message of the Host
  33 handling, while filtering out every other messages that are of a lesser priority than "error". For that, use the following command line argument:
  34 ``--log=root.thresh:error --log=s4u_host.thresh:debug``
  35
  36 You can also change the **layout** used to format the messages, using format directives that are similar to the *printf* ones: ``%r`` prints the time elapsed since the beginning of
  37 the simulation; ``%a`` gives the actor name, etc. Many such directives :ref:`are available <log/fmt>`. You can have a specific layout per category, and it will be inherited by all
  38 its sub-categories.
  39
  40 Finally, the **appender** actually displays the produced messages. SimGrid provides four appenders so far: the default one prints on *stderr*. ``file`` writes to a given file,
  41 ``rollfile`` does the same, but overwrites old messages when the file grows too large and ``splitfile`` creates new files when the maximum size is reached. Each category can have
  42 its own appender.
  43
  44 For more information, please refer to the :ref:`programmer's interface <logging_prog>` to learn how to produce messages from your code, or to :ref:`logging_config` to see how to
  45 change the settings at runtime.
  46
  47 .. _outcome_vizu:
  48
  49 Graphical and statistical logging
  50 *********************************
  51
  52 To be written. For now, see `this page <https://simgrid.org/contrib/R_visualization.html>`_.
  53
  54 Building your own logging
  55 *************************
  56
  57 You can add callbacks to the existing signals to get informed of each and every even occurring in the simulator. These callbacks can be used to write logs on disk in the format that
  58 you want. Some users did so to visualize the behavior of their simulators with `Jaeger <https://www.jaegertracing.io/>`_.