C guide and API reference#
Include isaacsim/common/logging/Logging.h and link isaacsim::common-logging. The C API is a stateless facade
over the same private Carbonite backend used by C++ and Python:
#include <isaacsim/common/logging/Logging.h>
ISAACSIM_COMMON_LOGGING_INFO("isaacsim.simulation", "Simulation initialized");
The four convenience macros submit VERBOSE, INFO, WARNING, or ERROR records and automatically preserve
__FILE__, __func__, and __LINE__. Messages must already be formatted. Call
isaacsimCommonLoggingWrite directly when explicit source metadata is required.
Use ISAACSIM_COMMON_LOGGING_REPORT for output that must be visible regardless of Carbonite’s configured log level:
ISAACSIM_COMMON_LOGGING_REPORT("isaacsim.simulation", "Calculation result: 42");
It synchronously writes and flushes [channel] message to standard output, then submits the unprefixed message to
Carbonite at INFO with source metadata. Carbonite still controls admission and routing of the log record, so
console routing of INFO may display the message a second time. Call isaacsimCommonLoggingReport directly to
provide explicit source metadata.
The channel must be a non-empty null-terminated string, and the message must be a null-terminated string. The facade ignores invalid input because logging is supplemental and does not introduce a second result or last-error system. Source file and function pointers may be null. The call does not retain input strings.
Application-level configuration#
Initialize a patch with ISAACSIM_COMMON_LOGGING_GLOBAL_CONFIG_INIT, select fields, and apply it once at application
startup. Unselected fields leave the current process-wide Carbonite setting unchanged:
IsaacSimCommonLoggingGlobalConfig configuration = ISAACSIM_COMMON_LOGGING_GLOBAL_CONFIG_INIT;
configuration.fields = ISAACSIM_COMMON_LOGGING_CONFIG_FILE_PATH |
ISAACSIM_COMMON_LOGGING_CONFIG_FILE_APPEND |
ISAACSIM_COMMON_LOGGING_CONFIG_FILE_LEVEL;
configuration.filePath = "logs/isaac-sim-${pid}.log";
configuration.fileAppend = 1;
configuration.fileLevel = ISAACSIM_COMMON_LOGGING_LOG_INFO;
if (isaacsimCommonLoggingConfigureGlobal(&configuration) != ISAACSIM_COMMON_LOGGING_CONFIGURE_SUCCESS)
{
/* Invalid configuration or unavailable backend. */
}
Select FILE_PATH with a null or empty path to disable file logging. Create parent directories before configuring
the destination. Carbonite resolves relative paths from the working directory at configuration time and does not
report file-open failures through this API. Configure this global policy only from the application entry point.
Use CHANNELS to override Carbonite’s process-wide enablement or threshold for specific channels:
IsaacSimCommonLoggingChannelConfig channel = ISAACSIM_COMMON_LOGGING_CHANNEL_CONFIG_INIT;
channel.channel = "isaacsim.sensors.camera";
channel.enabledBehavior = ISAACSIM_COMMON_LOGGING_CHANNEL_SETTING_OVERRIDE;
channel.enabled = 0;
IsaacSimCommonLoggingGlobalConfig configuration = ISAACSIM_COMMON_LOGGING_GLOBAL_CONFIG_INIT;
configuration.fields = ISAACSIM_COMMON_LOGGING_CONFIG_CHANNELS;
configuration.channelConfigs = &channel;
configuration.channelConfigCount = 1;
isaacsimCommonLoggingConfigureGlobal(&configuration);
Set a behavior to INHERIT to clear that channel override and resume using the process-wide setting. Set it to
UNCHANGED to leave the corresponding Carbonite setting untouched. Enablement and minimum-level behaviors are
independent, and Carbonite performs the filtering.
The field mask covers process enablement and minimum level, asynchronous delivery, standard stream and Windows debug
console settings, file settings, timestamp and elapsed-time rendering, source metadata, identifiers, color output, and
multi-process serialization, plus named-channel enablement and thresholds. The declarations in Logging.h provide
the complete field inventory.
isaacsimCommonLoggingFlush drains Carbonite’s process-wide backend. The C API has no logger handles, callback
registry, local filtering engine, or per-instance lifecycle.
Host integration#
LoggingHost.h is reserved for native host adapters. A host that already owns Carbonite attaches its existing
carb::logging::ILogging pointer before any logging operation selects the standalone backend and retains the
returned ownership token. Loggers may be constructed before attachment. Detaching that token waits for active
submissions and removes this library’s channels without releasing the Carbonite framework. Feature libraries should
include only Logging.h and must not call this integration API.
The declarations and Doxygen comments in Logging.h and LoggingHost.h are the authoritative C reference.
API reference#
Public C declarations owned by isaacsim.common.logging.