C++ guide and API reference#
Include isaacsim/common/logging/Logging.hpp and link isaacsim::common-logging. Store one Logger for each
feature-library channel:
#include <isaacsim/common/logging/Logging.hpp>
using isaacsim::common::logging::LogLevel;
using isaacsim::common::logging::Logger;
Logger logger("isaacsim.simulation");
logger.log(LogLevel::eInfo, "Simulation initialized");
Logger copies its non-empty channel during construction without selecting a backend, allowing a native host to
attach after feature loggers are created. Records have four delivered severities: eVerbose, eInfo,
eWarning, and eError. Carbonite owns filtering and output policy; the facade has no callback registry,
per-logger policy, or last-error state.
The C++ macros use the pinned header-only {fmt} dependency, submit without a second message copy, and preserve
source location metadata:
ISAACSIM_LOG_INFO(logger, "Loaded {} objects", objectCount);
ISAACSIM_LOG_WARN(logger, "Falling back to backend {}", backendName);
ISAACSIM_LOG_WARN_ONCE(logger, "The fallback backend is active");
ISAACSIM_LOG_DEPRECATION_ONCE(logger, "old_api() is deprecated; use new_api() instead");
ISAACSIM_LOG_WARNING_ONCE and its ISAACSIM_LOG_WARN_ONCE alias submit at most one admitted record for each
macro call site, including when multiple threads reach that site concurrently. A filtered call does not consume the
call site’s record. ISAACSIM_LOG_DEPRECATION_ONCE provides the same behavior at WARNING severity and leaves the
deprecation message unchanged. All formatting macros check admission before evaluating their formatting arguments.
Use Logger::isEnabled when expensive work must happen before the macro call or when calling Logger::log
directly.
For code that already owns source metadata, pass SourceLocation to Logger::log or Logger::report directly:
using isaacsim::common::logging::SourceLocation;
logger.log(LogLevel::eInfo, message, SourceLocation{ sourceFile, sourceFunction, sourceLine });
The logger borrows the three pointers only for the call. A default-constructed SourceLocation omits the metadata.
Use report for result-style output that must remain visible regardless of Carbonite’s configured log level. The
formatted macro also preserves source metadata:
logger.report("Calculation complete");
ISAACSIM_REPORT(logger, "Calculation result: {:.2f}", result);
Both forms synchronously write and flush [channel] message to standard output, then submit the unprefixed message
to Carbonite at INFO. Carbonite still controls admission and routing of the log record, so console routing of
INFO may display the message a second time.
Formatting failures are ignored because logging is supplemental. Callers that need compile-time format-string
checking with the pinned fmt 7 dependency can wrap a literal with FMT_STRING.
Application-level configuration#
GlobalLoggingConfiguration is an application-level patch over Carbonite’s process-wide default logger and named
channels.
Empty optionals leave current scalar settings unchanged, so applications can update one destination without resetting
the others:
using isaacsim::common::logging::ConfigureResult;
using isaacsim::common::logging::GlobalLoggingConfiguration;
using isaacsim::common::logging::configureGlobalLogging;
GlobalLoggingConfiguration configuration;
configuration.filePath = "logs/isaac-sim-${pid}.log";
configuration.fileAppend = true;
configuration.fileLevel = LogLevel::eInfo;
if (configureGlobalLogging(configuration) != ConfigureResult::eSuccess)
{
// Invalid configuration or unavailable backend.
}
An empty filePath string disables 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 its configuration interface. Configure this process-wide policy only from the application entry
point.
Applications can also patch Carbonite’s per-channel enablement and threshold. eOverride applies the supplied
value, eInherit clears the corresponding channel override, and eUnchanged leaves it untouched:
using isaacsim::common::logging::ChannelLoggingConfiguration;
using isaacsim::common::logging::ChannelSettingBehavior;
ChannelLoggingConfiguration channel;
channel.channel = "isaacsim.sensors.camera";
channel.enabledBehavior = ChannelSettingBehavior::eOverride;
channel.enabled = false;
GlobalLoggingConfiguration configuration;
configuration.channels.push_back(channel);
configureGlobalLogging(configuration);
Enablement and minimum-level behaviors are independent. Carbonite performs the filtering; Logger does not keep a
local policy copy.
Logging calls are noexcept and return void. Use isaacsim::common::logging::flush() only when the application
needs to drain Carbonite’s process-wide logging backend explicitly. Logger destruction does not flush global state.
The declarations and Doxygen comments in Logging.hpp are the authoritative C++ reference.
API reference#
Fully qualified namespace: isaacsim::common::logging
-
namespace logging#
Classes Summary#
- Logger
Lightweight logger with one immutable Carbonite channel.
Enumerations Summary#
- ChannelSettingBehavior
Action to apply to one channel setting in a configuration patch.
- ConfigureResult
Result of applying process-wide logging configuration.
- ElapsedTimeUnit
Unit used for the elapsed-time prefix.
- LogLevel
Severity of a submitted log record.
- OutputStream
Selection of the standard stream used by the Carbonite standard logger.
Functions Summary#
- ConfigureResult configureGlobalLogging(const GlobalLoggingConfiguration &configuration) noexcept
Apply selected process-wide logging settings.
- void flush() noexcept
Flush all records currently pending in the process-wide Carbonite backend.
Namespaces Summary#
Structs Summary#
- ChannelLoggingConfiguration
Patch-style Carbonite settings for one logging channel.
- GlobalLoggingConfiguration
Patch-style process-wide logging configuration.
- SourceLocation
Borrowed source metadata forwarded to the logging backend.