The XBT toolbox

XBT is not an interface to describe your application, but rather a toolbox of features that are used everywhere in SimGrid. The code described in this page is not specific to any of the existing interfaces, and it’s used in all of them.

Logging API

As introduced in Textual logging, the SimGrid logging mechanism allows to configure at runtime the messages that should be displayed and those that should be omitted. Each message produced in the code is given a category (denoting its topic) and a priority. Then at runtime, each category is given a threshold (only messages of priority higher than 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 documents the provided API. To see how to configure these features at runtime, please refer to Logging configuration.

Declaring categories

Typically, there will be a category for each module of the implementation, so that users can independently control the logging for each module. Refer to the Existing categories section for a list of all existing categories in SimGrid.

XBT_LOG_NEW_CATEGORY(category, description)

Creates a new category that is not within any existing categories. It will be located right below the root category. category must be a valid identifier (such as mycat) with no quote or anything. It should also be unique over the whole binary. description must be a string, between quotes.

XBT_LOG_NEW_SUBCATEGORY(category, parent_category, description)

Creates a new category under the provided parent_category.

XBT_LOG_NEW_DEFAULT_CATEGORY(category, description)

Similar to XBT_LOG_NEW_CATEGORY, and the created category is the default one in the current source file.

XBT_LOG_NEW_DEFAULT_SUBCATEGORY(category, parent_category, description)

Similar to XBT_LOG_NEW_SUBCATEGORY, and the created category is the default one in the current source file.

XBT_LOG_EXTERNAL_CATEGORY(category)

Make an external category (i.e., a category declared in another source file) visible from this source file. In each source file, at most one one category can be the default one.

XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(category)

Use an external category as default category in this source file.

Logging messages

Default category

XBT_CRITICAL(format_string, parameters…)

Report a fatal error to the default category.

XBT_ERROR(format_string, parameters…)

Report an error to the default category.

XBT_WARN(format_string, parameters…)

Report a warning or an important information to the default category.

XBT_INFO(format_string, parameters…)

Report an information of regular importance to the default category.

XBT_VERB(format_string, parameters…)

Report a verbose information to the default category.

XBT_DEBUG(format_string, parameters…)

Report a debug-only information to the default category.

For each of the logging macros, the first parameter must be a printf-like format string, and the subsequent parameters must match this format. If you compile with the -Wall option, the compiler will warn you for unmatched arguments, such as passing a pointer while the format string expects an integer. Using this option is usually a good idea.

Here is an example: XBT_WARN("Values are: %d and '%s'", 5, "oops");

XBT_IN(format_string, parameters…)

Report that the execution flow enters a given function (which name is displayed automatically).

XBT_OUT(format_string, parameters…)

Report that the execution flow exits a given function (which name is displayed automatically).

XBT_HERE(format_string, parameters…)

Report that the execution flow reaches a given location.

Specific category

XBT_CCRITICAL(category, format_string, parameters…)

Report a fatal error to the specified category.

XBT_CERROR(category, format_string, parameters…)

Report an error to the specified category.

XBT_CWARN(category, format_string, parameters…)

Report a warning or an important information to the specified category.

XBT_CINFO(category, format_string, parameters…)

Report an information of regular importance to the specified category.

XBT_CVERB(category, format_string, parameters…)

Report a verbose information to the specified category.

XBT_CDEBUG(category, format_string, parameters…)

Report a debug-only information to the specified category.

Of course, the specified category must be visible from this source file, either because it was created there (e.g. with XBT_LOG_NEW_CATEGORY) or because it was made visible with XBT_LOG_EXTERNAL_CATEGORY.

Other functions

XBT_LOG_ISENABLED(category, priority)

Returns true if that category displays the messages of that priority. It’s useful to compute a value that is used only in the logging, such as the textual representation of a non-trivial object.

The specified priority must be one of xbt_log_priority_trace, xbt_log_priority_debug, xbt_log_priority_verbose, xbt_log_priority_info, xbt_log_priority_warning, xbt_log_priority_error or xbt_log_priority_critical.

void xbt_log_control_set(const char *setting)

Sets the provided setting as if it was passed in a --log command-line parameter.

You should not use any of the macros which name starts with ‘_’.

Existing categories

This is the list of all categories existing in the SimGrid implementation. Some of them only exist with specific compile-time options, while your implementation may add new ones. Please add --help-log-categories to the command-line of a SimGrid simulator to see the exact list of categories usable with it.

  • instr: Logging the behavior of the tracing system (used for Visualization/Analysis of simulations)

    • instr_paje_events: Paje tracing event system (events)

    • instr_paje_trace: tracing event system

    • instr_routing: Tracing platform hierarchy

    • instr_smpi: Tracing SMPI

  • java: MSG for Java(TM)

  • kernel: SimGrid internals

    • ker_resource: Resources, modeling the platform performance

      • res_cpu: CPU resource, fueling execution activites

        • cpu_cas: CPU resource, CAS01 model (used by default)

        • cpu_ti: CPU resource, Trace Integration model

      • res_disk: Disk resources, fuelling I/O activities

      • res_host: Host resources agregate CPU, networking and I/O features

      • res_network: Network resources, that fuels communications

        • res_ns3: Network model based on ns-3

      • res_vm: Virtual Machines, containing actors and mobile accross hosts

  • lua: Lua Bindings

    • lua_platf: Lua bindings (platform module)

  • mc: All MC categories

    • Api: Logging specific to MC Facade APIs

    • mc_Channel: MC interprocess communication

    • mc_ModelChecker: ModelChecker

    • mc_Session: Model-checker session

    • mc_VisitedState: Logging specific to state equality detection mechanisms

    • mc_client: MC client logic

    • mc_comm_determinism: Logging specific to MC communication determinism detection

    • mc_dwarf: DWARF processing

    • mc_global: Logging specific to MC (global)

    • mc_hash: Logging specific to mc_hash

    • mc_liveness: Logging specific to algorithms for liveness properties verification

    • mc_observer: Logging specific to MC simcall observation

    • mc_process: MC process information

    • mc_record: Logging specific to MC record/replay facility

    • mc_safety: Logging specific to MC safety verification

    • mc_snapshot: Taking and restoring snapshots

    • mc_udpor: Logging specific to MC safety verification

    • mc_udpor_global: udpor_global

  • msg: All MSG categories

    • msg_task: Logging specific to MSG (task)

  • python: python

  • s4u: Log channels of the S4U (Simgrid for you) interface

    • s4u_activity: S4U activities

      • s4u_comm: S4U asynchronous communications

      • s4u_exec: S4U asynchronous executions

    • s4u_actor: S4U actors

    • s4u_barrier: S4U barrier

    • s4u_channel: S4U Communication Mailboxes

    • s4u_engine: Logging specific to S4U (engine)

    • s4u_file: S4U files

    • s4u_host: Logging specific to the S4U hosts

    • s4u_vm: S4U virtual machines

    • vm_live_migration: S4U virtual machines live migration

  • sd: Logging specific to SimDag

    • jed_sd: Jedule SimDag binding

    • sd_daxparse: Parsing DAX files

    • sd_dotparse: Parsing DOT files

    • sd_kernel: Logging specific to SimDag (kernel)

    • sd_task: Logging specific to SimDag (task)

  • simix: All SIMIX categories

    • simix_context: Context switching mechanism

    • simix_deployment: Logging specific to SIMIX (deployment)

    • simix_io: Logging specific to SIMIX (io)

    • simix_kernel: Logging specific to SIMIX (kernel)

    • simix_mailbox: Mailbox implementation

    • simix_network: SIMIX network-related synchronization

    • simix_popping: Popping part of SIMIX (transmuting from user request into kernel handlers)

    • simix_process: Logging specific to SIMIX (process)

    • simix_synchro: SIMIX Synchronization (mutex, semaphores and conditions)

      • simix_condition: Condition variables

      • simix_mutex: Mutex kernel-space implementation

      • simix_semaphore: Semaphore kernel-space implementation

  • smpi: All SMPI categories

    • smpi_bench: Logging specific to SMPI (benchmarking)

    • smpi_coll: Logging specific to SMPI collectives.

    • smpi_colls: Logging specific to SMPI collectives

    • smpi_comm: Logging specific to SMPI (comm)

    • smpi_config: Logging specific to SMPI (config)

    • smpi_datatype: Logging specific to SMPI (datatype)

    • smpi_host: Logging specific to SMPI (host)

    • smpi_io: Logging specific to SMPI (RMA operations)

    • smpi_kernel: Logging specific to SMPI (kernel)

    • smpi_memory: Memory layout support for SMPI

    • smpi_mpi: Logging specific to SMPI ,(mpi)

    • smpi_op: Logging specific to SMPI (op)

    • smpi_pmpi: Logging specific to SMPI (pmpi)

    • smpi_process: Logging specific to SMPI (kernel)

    • smpi_replay: Trace Replay with SMPI

    • smpi_request: Logging specific to SMPI (request)

    • smpi_rma: Logging specific to SMPI (RMA operations)

    • smpi_shared: Logging specific to SMPI (shared memory macros)

    • smpi_utils: Logging specific to SMPI (utils)

  • surf: All SURF categories

    • link_energy: Logging specific to the SURF LinkEnergy plugin

    • link_energy_wifi: Logging specific to the link energy wifi plugin

    • link_load: Logging specific to the SURF LinkLoad plugin

    • sg_version: About the versioning of SimGrid

    • surf_config: About the configuration of SimGrid

    • surf_energy: Logging specific to the SURF energy plugin

    • surf_kernel: Logging specific to SURF (kernel)

    • surf_maxmin: Logging specific to SURF (maxmin)

    • surf_parse: Logging specific to the SURF parsing module

    • surf_plugin_dvfs: Logging specific to the SURF HostDvfs plugin

    • surf_plugin_load: Logging specific to the HostLoad plugin

    • surf_route: Routing part of surf

      • surf_routing_generic: Generic implementation of the surf routing

    • surf_route_cluster: Routing part of surf

      • surf_route_cluster_dragonfly: Dragonfly Routing part of surf

      • surf_route_cluster_torus: Torus Routing part of surf

    • surf_route_dijkstra: Routing part of surf – dijkstra routing logic

    • surf_route_fat_tree: Routing for fat trees

    • surf_route_floyd: Routing part of surf

    • surf_route_full: Routing part of surf

    • surf_route_none: Routing part of surf

    • surf_route_vivaldi: Routing part of surf

    • surf_route_wifi: Routing part of surf

  • unit: Unit tests of the Trace Manager

  • xbt: All XBT categories (simgrid toolbox)

    • log: Loggings from the logging mechanism itself

    • mc_compare: Logging specific to mc_compare in mc

    • module: module handling

    • parse: Parsing functions

    • replay: Replay trace reader

    • xbt_cfg: configuration support

    • xbt_dict: Dictionaries provide the same functionalities as hash tables

      • xbt_dict_cursor: To traverse dictionaries

    • xbt_dyn: Dynamic arrays

    • xbt_exception: Exceptions

    • xbt_graph: Graph

    • xbt_help: Help messages

    • xbt_mallocator: Mallocators

    • xbt_parmap: parmap: parallel map

    • xbt_random: Random

Full example

#include "xbt/log.h"

/* create a category and a default subcategory */
XBT_LOG_NEW_CATEGORY(VSS);
XBT_LOG_NEW_DEFAULT_SUBCATEGORY(SA, VSS);

int main() {
    /* Now set the parent's priority.  (the string would typically be a runtime option) */
    xbt_log_control_set("SA.thresh:info");

    /* This request is enabled, because WARNING >= INFO. */
    XBT_CWARN(VSS, "Low fuel level.");

    /* This request is disabled, because DEBUG < INFO. */
    XBT_CDEBUG(VSS, "Starting search for nearest gas station.");

    /* The default category SA inherits its priority from VSS. Thus,
       the following request is enabled because INFO >= INFO.  */
    XBT_INFO("Located nearest gas station.");

    /* This request is disabled, because DEBUG < INFO. */
    XBT_DEBUG("Exiting gas station search");
}

Performance concern

This module is highly optimized. Messages that will not be displayed are not even built. For example, using XBT_DEBUG in a category that turns debug messages off only costs a single integer comparison at runtime, and the parameters are not even evaluated.

You can even specify a compile-time threshold that will completely remove every logging below the specified priority. Passing -DNDEBUG to cmake disables every logging of priority below INFO while -DNLOG removes any logging at compile time. Note that using this feature may hinder the stability of SimGrid, as we consider the logs to be fast enough to not thoughtfully test the case where they are removed at compile time.