isaacsim.common.logging#
isaacsim.common.logging is a thin C, C++, and Python facade over the private, statically linked Carbonite logging
backend. Each feature library owns a lightweight logger with one immutable channel. Carbonite performs severity
filtering, rendering, destination routing, and asynchronous delivery.
Logger construction only caches its channel and does not select a backend. A native host may therefore attach its Carbonite interface after feature loggers are constructed. The first record submission, admission query, or global configuration operation selects the standalone backend when no host has attached. Host attachment must precede those operations when the application owns Carbonite.
The standalone backend disables absolute timestamps and enables a millisecond elapsed-time index on Carbonite’s
default logger. The elapsed index starts when that logger emits its first message. The application may subsequently
change process-wide Carbonite settings through configure_global. The unconditional standard-output line produced
by report() contains the logger channel and caller’s raw message; only its Carbonite copy receives the remaining
backend formatting.
The facade deliberately does not provide a second callback registry or filtering engine. It translates four delivered
severity levels, preserves provided source locations, and forwards already formatted messages to Carbonite. C++ macros
provide source locations automatically; Python callers opt in per submission with capture_source=True. Its global
configuration object patches Carbonite’s process-wide and per-channel settings rather than maintaining a second
configuration store. Backend unavailability makes log submission a no-op, causes admission queries to return false,
and does not affect feature-library error reporting.
Global configuration ownership#
Configure global logging only from the application or service entry point. Create one Logger in each feature
library, and leave process policy unchanged. Every optional C++ and Python configuration member, and every unselected
C field-mask bit, means “leave the current Carbonite setting unchanged.” This lets you change the file destination
without resetting console formatting or a host’s existing severity policy.
The configurable surface includes process admission, asynchronous delivery, standard-stream and debug-console
destinations, file path and append policy, destination thresholds and flush policy, absolute or elapsed timestamps,
source location fields, thread/process/trace identifiers, color output, and multi-process serialization. File paths
may be absolute or relative to the working directory at configuration time and may contain Carbonite’s ${pid}
placeholder. Create parent directories before configuring a file destination.
Applications can patch channel enablement and minimum severity with explicit override or inherit behavior.
Inheritance clears the Carbonite per-channel setting and resumes using the process-wide policy. Feature loggers remain
immutable channel handles and do not own filtering state.
The facade serializes configuration calls with one another but does not stop concurrent logging. Carbonite applies
individual settings synchronously; there is no atomic multi-setting transaction. Carbonite’s file configuration
setters do not report file-open failures, so a successful configuration result means the backend accepted the
settings, not that it opened a path successfully. Call flush() before shutdown or before consuming a log file.
Callback dispatch follows Carbonite’s contract because the facade does not add a callback layer. With asynchronous delivery, a record submitted by a Carbonite callback is queued after the current callback and can be delivered to that callback later. Callback implementations that submit records must prevent unbounded record generation.
Python usage#
Create a logger at feature-library initialization time and retain it for that library’s lifetime:
from isaacsim.common.logging import GlobalLoggingConfig, LogLevel, Logger, configure_global, flush
config = GlobalLoggingConfig()
config.file_path = "logs/isaac-sim-${pid}.log"
config.file_append = True
config.file_level = LogLevel.INFO
configure_global(config)
logger = Logger("isaacsim.simulation")
logger.info("Simulation initialized")
logger.warning("Fallback selected", capture_source=True)
result = 6 * 7
logger.report(f"Calculation result: {result}")
# Use only when the application needs an explicit process-wide drain.
flush()
The logger needs no explicit shutdown. flush() is process-wide because Carbonite, not an individual facade
instance, owns pending records.
report() is for result-style output that must remain visible regardless of Carbonite’s configured log level. It
synchronously writes and flushes [channel] message to standard output, then submits the unprefixed message to
Carbonite at INFO.
The Carbonite submission remains subject to Carbonite’s output policy. If Carbonite also routes the INFO record to
the console, the message can appear there a second time.
C++ formatting macros accept an explicit logger, use {fmt} syntax, and preserve source file, function, and line
metadata. The warning-once and deprecation-once macros are thread-safe and submit at most one admitted record per call
site. Logging is supplemental: disabling it does not change feature-library results or last-error behavior.
See C guide and API reference, C++ guide and API reference, and Python guide and API reference for language-specific references.