- / * This request is disabled, because DEBUG < INFO. * /
- XBT_DEBUG("Exiting gas station search");
-}
-\endverbatim
-
-\section log_user 3. User interface
-
-\section log_use_conf 3.1 Configuration
-
-Although rarely done, it is possible to configure the logs during
-program initialization by invoking the xbt_log_control_set() method
-manually. A more conventional way is to use the --log command line
-argument. xbt_init() (called by MSG_init() and friends)
-checks and deals properly with such arguments.
-
-\subsection log_use_conf_thres 3.1.1 Threshold configuration
-
-The most common setting is to control which logging event will get
-displayed by setting a threshold to each category through the
-<tt>threshold</tt> keyword.
-
-For example, \verbatim --log=root.threshold:debug\endverbatim will make
-SimGrid <b>extremely</b> verbose while \verbatim
---log=root.thres:critical\endverbatim should shut it almost
-completely off.
-
-Note that the <tt>threshold</tt> keyword can be abbreviated here. For example,
-all the following notations have the same result.
-\verbatim
---log=root.threshold:debug
---log=root.threshol:debug
---log=root.thresho:debug
---log=root.thresh:debug
---log=root.thres:debug
---log=root.thre:debug
---log=root.thr:debug
---log=root.th:debug
---log=root.t:debug
---log=root.:debug <--- That's obviously really ugly, but it actually works.
-\endverbatim
-
-The full list of recognized thresholds is the following:
-
- - trace: enter and return of some functions
- - debug: crufty output
- - verbose: verbose output for the user wanting more
- - info: output about the regular functionning
- - warning: minor issue encountered
- - error: issue encountered
- - critical: major issue encountered
-
-\subsection log_use_conf_multi 3.1.2 Passing several settings
-
-You can provide several of those arguments to change the setting of several
-categories, they will be applied from left to right. So,
-\verbatim --log="root.thres:debug root.thres:critical"\endverbatim should
-disable almost any logging.
-
-Note that the quotes on above line are mandatory because there is a space in
-the argument, so we are protecting ourselves from the shell, not from SimGrid.
-We could also reach the same effect with this:
-\verbatim --log=root.thres:debug --log=root.thres:critical\endverbatim
-
-\subsection log_use_conf_fmt 3.1.3 Format configuration
-
-As with SimGrid 3.3, it is possible to control the format of log
-messages. This is done through the <tt>fmt</tt> keyword. For example,
-\verbatim --log=root.fmt:%m\endverbatim reduces the output to the
-user-message only, removing any decoration such as the date, or the
-process ID, everything.
-
-Here are the existing format directives:
-
- - %%: the % char
- - %%n: platform-dependent line separator (LOG4J compatible)
- - %%e: plain old space (SimGrid extension)
-
- - %%m: user-provided message
-
- - %%c: Category name (LOG4J compatible)
- - %%p: Priority name (LOG4J compatible)
-
- - %%h: Hostname (SimGrid extension)
- - %%P: Process name (SimGrid extension -- note that with SMPI this is the integer value of the process rank)
- - %%t: Thread "name" (LOG4J compatible -- actually the address of the thread in memory)
- - %%i: Process PID (SimGrid extension -- this is a 'i' as in 'i'dea)
-
- - %%F: file name where the log event was raised (LOG4J compatible)
- - %%l: location where the log event was raised (LOG4J compatible, like '%%F:%%L' -- this is a l as in 'l'etter)
- - %%L: line number where the log event was raised (LOG4J compatible)
- - %%M: function name (LOG4J compatible -- called method name here of course).
- Defined only when using gcc because there is no __FUNCTION__ elsewhere.
-
- - %%b: full backtrace (Called %%throwable in LOG4J).
- Defined only under windows or when using the GNU libc because backtrace() is not defined
- elsewhere, and we only have a fallback for windows boxes, not mac ones for example.
- - %%B: short backtrace (only the first line of the %%b).
- Called %%throwable{short} in LOG4J; defined where %%b is.
-
- - %%d: date (UNIX-like epoch)
- - %%r: application age (time elapsed since the beginning of the application)
-
-
-If you want to mimic the simple layout with the format one, you would use this
-format: '[%%h:%%i:(%%i) %%r] %%l: [%%c/%%p] %%m%%n'. This is not completely correct
-because the simple layout do not display the message location for messages at
-priority INFO (thus, the fmt is '[%%h:%%i:(%%i) %%r] [%%c/%%p] %%m%%n' in this
-case). Moreover, if there is no process name (ie, messages coming from the
-library itself, or test programs doing strange things) do not display the
-process identity (thus, fmt is '[%%r] %%l: [%%c/%%p] %%m%%n' in that case, and '[%%r]
-[%%c/%%p] %%m%%n' if they are at priority INFO).
-
-For now, there is only two format modifiers: the precision and the
-width fields. You can for example specify %.4r to get the application
-age with 4 numbers after the radix, or %15p to get the process name
-on 15 columns. Finally, you can specify %10.6r to get the time on at
-most 10 columns, with 6 numbers after the radix.
-
-Note that when specifying the width, it is filled with spaces. That
-is to say that for example %5r in your format is converted to "% 5f"
-for printf (note the extra space); there is no way to fill the empty
-columns with 0 (ie, pass "%05f" to printf). Another limitation is
-that you cannot set specific layouts to the several priorities.
-
-\subsection log_use_conf_app 3.1.4 Category appender
-
-As with SimGrid 3.3, it is possible to control the appender of log
-messages. This is done through the <tt>app</tt> keyword. For example,
-\verbatim --log=root.app:file:mylogfile\endverbatim redirects the output
-to the file mylogfile.
-
-For splitfile appender, the format is
-\verbatim --log=root.app:splitfile:size:mylogfile_%.format\endverbatim
-
-The size is in bytes, and the % wildcard will be replaced by the number of the
-file. If no % is present, it will be appended at the end.
-
-rollfile appender is also available, it can be used as
-\verbatim --log=root.app:rollfile:size:mylogfile\endverbatim
-When the file grows to be larger than the size, it will be emptied and new log
-events will be sent at its beginning
-
-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.
-
-\subsection log_use_conf_add 3.1.5 Category additivity
-
-The <tt>add</tt> keyword allows to specify the additivity of a
-category (see \ref log_in_app). '0', '1', 'no', 'yes', 'on'
-and 'off' are all valid values, with 'yes' as default.
-
-The following example resets the additivity of the xbt category to true (which is its default value).
-\verbatim --log=xbt.add:yes\endverbatim
-
-\section log_use_misc 3.2 Misc and Caveats
-
- - Do not use any of the macros that start with '_'.
- - Log4J has a 'rolling file appender' which you can select with a run-time
- option and specify the max file size. This would be a nice default for
- non-kernel applications.
- - Careful, category names are global variables.
- - When writing a log format, you often want to use spaces. If you don't
- protect these spaces, they are used as configuration elements separators.
- For example, if you want to remove the date from the logs, you want to pass the following
- argument on the command line. The outer quotes are here to protect the string from the shell
- interpretation while the inner ones are there to prevent simgrid from splitting the string
- in several log parameters (that would be invalid).
- \verbatim --log="'root.fmt:%l: [%p/%c]: %m%n'"\endverbatim
- Another option is to use the SimGrid-specific format directive \%e for
- spaces, like in the following.
- \verbatim --log="root.fmt:%l:%e[%p/%c]:%e%m%n"\endverbatim
-
-\section log_internals 4. Internal considerations
-
-This module is a mess of macro black magic, and when it goes wrong,
-SimGrid studently loose its ability to explain its problems. When
-messing around this module, I often find useful to define
-XBT_LOG_MAYDAY (which turns it back to good old printf) for the time
-of finding what's going wrong. But things are quite verbose when
-everything is enabled...
-
-\section log_in_perf 4.1 Performance
-
-Except for the first invocation of a given category, a disabled logging request
-requires an a single comparison of a static variable to a constant.
-
-There is also compile time constant, \ref XBT_LOG_STATIC_THRESHOLD, which
-causes all logging requests with a lower priority to be optimized to 0 cost
-by the compiler. By setting it to xbt_log_priority_infinite, all logging
-requests are statically disabled at compile time and cost nothing. Released executables
-<i>might</i> be compiled with (note that it will prevent users to debug their problems)
-\verbatim-DXBT_LOG_STATIC_THRESHOLD=xbt_log_priority_infinite\endverbatim
-
-Compiling with the \verbatim-DNLOG\endverbatim option disables all logging
-requests at compilation time while the \verbatim-DNDEBUG\endverbatim disables
-the requests of priority below INFO.
-
-\todo Logging performance *may* be improved further by improving the message
-propagation from appender to appender in the category tree.
-
-\section log_in_app 4.2 Appenders
-
-Each category has an optional appender. An appender is a pointer to a
-structure which starts with a pointer to a do_append() function. do_append()
-prints a message to a log.
-
-When a category is passed a message by one of the logging macros, the
-category performs the following actions:
-
- - if the category has an appender, the message is passed to the
- appender's do_append() function,
- - if additivity is true for the category, the message is passed to
- the category's parent. Additivity is true by default, and can be
- controlled by xbt_log_additivity_set() or something like --log=root.add:1 (see \ref log_use_conf_add).
- Also, when you add an appender to a category, its additivity is automatically turned to off.
- Turn it back on afterward if it is not what you wanted.
-
-By default, only the root category have an appender, and any other category has
-its additivity set to true. This causes all messages to be logged by the root
-category's appender.
-
-The default appender function currently prints to stderr
-*/