-----------------------
The :ref:`tracing subsystem <outcomes_vizu>` can be configured in
-several different ways depending on the nature of the simulator (MSG,
-SimDag, SMPI) and the kind of traces that need to be obtained. See the
+several different ways depending on the used interface (S4U, SMPI, SimDag)
+and the kind of traces that needs to be obtained. See the
:ref:`Tracing Configuration Options subsection
-<tracing_tracing_options>` to get a detailed description of each
+<tracing_tracing_options>` for a full description of each
configuration option.
We detail here a simple way to get the traces working for you, even if
the paths of source files depend of the build settings. That would
break most of the tests since their output is continually compared.
-Logging Configuration
+.. _logging_config:
+
+Logging configuration
---------------------
As introduced in :ref:`outcome_logs`, the SimGrid logging mechanism allows to configure at runtime the messages that should be displayed and those that should be omitted. Each
that threshold are displayed), a layout (deciding how the messages in this category are formatted), and an appender (deciding what to do with the message: either print on stderr or
to a file).
-This section explains how to configure this logging features. You can also refer to the documentation of the :ref:`programmer's interface <xbt_log_prog>`, that allows to produce
+This section explains how to configure this logging features. You can also refer to the documentation of the :ref:`programmer's interface <logging_prog>`, that allows to produce
messages from your code.
-Most of the time, the logging mechanism is configured at runtime using the ``--log`` command-line argument, even if you can also use :ref:`xbt_log_control_set()` to control it from
+Most of the time, the logging mechanism is configured at runtime using the ``--log`` command-line argument, even if you can also use :c:func:`xbt_log_control_set()` to control it from
your program. To pass configure more than one setting, you can either pass several ``--log`` arguments, or separate your settings with spaces, that must be quoted accordingly. In
practice, the following is equivalent to the above settings: ``--log=root.thresh:error --log=s4u_host.thresh:debug``.
- %p: Priority name (LOG4J compatible)
- %h: Hostname (SimGrid extension)
- - %P: Actor name (SimGrid extension -- note that with SMPI this is the integer value of the process rank)
+ - %a: Actor name (SimGrid extension -- note that with SMPI this is the integer value of the process rank)
- %i: Actor PID (SimGrid extension -- this is a 'i' as in 'i'dea)
- %t: Thread "name" (LOG4J compatible -- actually the address of the thread in memory)
- %r: application age (time elapsed since the beginning of the application)
-``--log=root.fmt:'[%h:%P:(%i) %r] %l: %m%n'`` gives you the default layout used for info messages while ``--log=root.fmt:'[%h:%P:(%i) %r] %l: [%c/%p] %m%n'`` gives you the default
+``--log=root.fmt:'[%h:%a:(%i) %r] %l: %m%n'`` gives you the default layout used for info messages while ``--log=root.fmt:'[%h:%a:(%i) %r] %l: [%c/%p] %m%n'`` gives you the default
layout for the other priorities (it adds the source code location). Also, the actor identification is omitted by the default layout for the messages coming directly from the
SimGrid kernel, so info messages are formatted with ``[%r] [%c/%p] %m%n`` in this case. When specifying the layout manually, such distinctions are currently impossible, and the
provided layout is used for every messages.
The ``rollfile`` appender uses one file only, but the file is emptied and recreated when its size reaches the specified maximum. For example, ``--log=root.app:rollfile:500:mylog``
ensures that the log file ``mylog`` will never overpass 500 bytes in size.
-Any appender setup this way have its own layout format (simple one by default),
-so you may have to change it too afterward. Moreover, the additivity of the log category
-is also set to false to prevent log event displayed by this appender to "leak" to any other
-appender higher in the hierarchy. If it is not what you wanted, you can naturally change it
-manually.
+Any appender setup this way have its own layout format, that you may change afterward. When specifying a new appender, its additivity is set to false to prevent log event displayed
+by this appender to "leak" to any other appender higher in the hierarchy. You can naturally change that if you want your messages to be displayed twice.
Category additivity
...................
``iface.log`` file; the logging of the xbt toolbox will be sent to both the ``xbt.log`` file and the ``all.log`` file (because xbt additivity was enabled); and every other loggings
will only be sent to ``all.log``.
+Other options
+.............
+
+``--help-logs`` displays a complete help message about logging in SimGrid.
+
+``--help-log-categories`` displays the actual hierarchy of log categories for this binary.
+
+``--log=no_loc`` hides the source locations (file names and line numbers) from the messages. This is useful to make tests reproducible.
+
+
.. |br| raw:: html
<br />
