Python guide and API reference#

The Python API exposes the native logger and process-wide application configuration through nanobind. Logger methods return None and delegate filtering, rendering, destinations, and asynchronous delivery to Carbonite.

Summary#

LogLevel

Severity of a submitted log record.

Logger

Logger with one immutable channel.

ChannelLoggingConfig

Patch-style settings for one logging channel.

ChannelSettingBehavior

Action to apply to one channel setting in a configuration patch.

GlobalLoggingConfig

Application-level logging configuration patch.

ConfigureResult

Result of applying logging configuration.

OutputStream

Selection of the standard logging stream.

ElapsedTimeUnit

Unit used for the elapsed-time prefix.

configure_global

isaacsim.common.logging.bindings._bindings.GlobalLoggingConfig) -> isaacsim.common.logging.bindings._bindings.ConfigureResult

flush

flush() -> None

Severity#

class isaacsim.common.logging.LogLevel(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)#

Severity of a submitted log record.

ERROR = 3#
INFO = 1#
VERBOSE = 0#
WARNING = 2#

Logger#

Construct Logger with one non-empty channel, then submit already formatted messages with log, verbose, info, warning, or error. warn is a compatibility alias for warning. Python source capture is disabled by default. Construction caches the channel without selecting a backend, allowing a native host to attach after feature modules are imported. Pass the keyword-only argument capture_source=True to attach the immediate Python caller’s filename, function name, and line number to an individual submission. Calls through a Python wrapper identify the wrapper until a stack-level API is added.

logger.warning("Using the fallback backend", capture_source=True)

Use report to synchronously print and flush [channel] message to standard output and also submit the unprefixed message to Carbonite at INFO. The standard-output write ignores Carbonite’s level, while the Carbonite record remains subject to its configured policy and may cause duplicate console output. The channel is immutable and the logger needs no explicit destruction. Use is_enabled before constructing an expensive message. Filtered calls skip source capture even when requested.

class isaacsim.common.logging.Logger(self, channel: str)#

Logger with one immutable channel.

Construction caches the channel without selecting or initializing a logging backend.

Parameters:

channel – Non-empty channel attached to every submitted record.

Raises:

ValueError – If channel is empty.

Example:

>>> from isaacsim.common.logging import Logger

>>> logger = Logger("isaacsim.simulation")
property channel#

The logger’s immutable channel.

error#

Submit an ERROR record.

Parameters:
  • message – Message to submit.

  • capture_source – Whether to attach the immediate Python caller’s filename, function, and line.

Example:

>>> logger.error("Simulation initialization failed")
info#

Submit an INFO record.

Parameters:
  • message – Message to submit.

  • capture_source – Whether to attach the immediate Python caller’s filename, function, and line.

Example:

>>> logger.info("Simulation initialized")
is_enabled#

Return whether the backend currently admits a severity for this channel.

Parameters:

severity – Severity to query.

Returns:

Whether a record at the severity is currently admitted.

Example:

>>> logger.is_enabled(LogLevel.INFO)
True
log#

Submit an already formatted message.

Parameters:
  • severity – Severity assigned to the record.

  • message – Message to submit.

  • capture_source – Whether to attach the immediate Python caller’s filename, function, and line.

Example:

>>> logger.log(LogLevel.INFO, "Simulation initialized")
report#

Print [channel] message to standard output and submit an INFO record.

Parameters:
  • message – Message to print after the channel prefix and submit.

  • capture_source – Whether to attach the immediate Python caller’s filename, function, and line.

Example:

>>> logger.report("Calculation result: 42")
verbose#

Submit a VERBOSE record.

Parameters:
  • message – Message to submit.

  • capture_source – Whether to attach the immediate Python caller’s filename, function, and line.

Example:

>>> logger.verbose("Loaded detailed simulation state")
warn#

Submit a WARNING record.

This is a compatibility alias for warning().

Parameters:
  • message – Message to submit.

  • capture_source – Whether to attach the immediate Python caller’s filename, function, and line.

Example:

>>> logger.warn("Using the fallback backend")
warning#

Submit a WARNING record.

Parameters:
  • message – Message to submit.

  • capture_source – Whether to attach the immediate Python caller’s filename, function, and line.

Example:

>>> logger.warning("Using the fallback backend")

Application-level configuration#

Configure global logging only from the application entry point. Every property defaults to None, which leaves the corresponding Carbonite setting unchanged. Set file_path to an empty string to disable file logging. The channels list is empty by default.

from isaacsim.common.logging import GlobalLoggingConfig, LogLevel, configure_global

config = GlobalLoggingConfig()
config.file_path = "logs/isaac-sim-${pid}.log"
config.file_append = True
config.file_level = LogLevel.INFO
result = configure_global(config)

To disable one channel while leaving the process-wide policy enabled, add a channel patch:

from isaacsim.common.logging import ChannelLoggingConfig, ChannelSettingBehavior

channel = ChannelLoggingConfig()
channel.channel = "isaacsim.sensors.camera"
channel.enabled_behavior = ChannelSettingBehavior.OVERRIDE
channel.enabled = False

config = GlobalLoggingConfig()
config.channels = [channel]
configure_global(config)

Set enabled_behavior or minimum_level_behavior to INHERIT to clear that override and resume using the process-wide setting. UNCHANGED leaves the corresponding Carbonite setting untouched. Carbonite performs the filtering.

Create parent directories before configuring a file destination. Carbonite resolves relative file paths from the working directory at the time of the call and does not report file-open failures through its configuration interface.

class isaacsim.common.logging.GlobalLoggingConfig(self)#

Application-level logging configuration patch.

An attribute set to None leaves the corresponding scalar setting unchanged.

Example:

>>> from isaacsim.common.logging import GlobalLoggingConfig, LogLevel

>>> config = GlobalLoggingConfig()
>>> config.minimum_level = LogLevel.WARNING
property asynchronous#

Whether backend delivery is asynchronous.

property channels#

Per-channel enablement and threshold patches.

property color_included#

Whether terminal color codes are included.

property debug_console_enabled#

Whether the Windows debug console destination is enabled.

property debug_console_level#

The Windows debug-console threshold.

property elapsed_time#

The elapsed-time prefix unit.

property enabled#

Whether process-wide logging is enabled.

property file_append#

Whether file output appends instead of replacing.

property file_flush_level#

The minimum severity that flushes the file.

property file_level#

The file-destination threshold.

property file_path#

Log path; an empty string disables file logging.

property filename_included#

Whether source filenames are included.

property force_ansi_color#

Whether ANSI color codes are forced.

property function_name_included#

Whether source function names are included.

property line_number_included#

Whether source line numbers are included.

property microsecond_timestamps#

Whether absolute timestamps use microsecond precision.

property minimum_level#

The process-wide admission threshold.

property multiprocess_group_id#

A nonzero identifier for cross-process output serialization.

property output_stream#

Default stdout/stderr routing or forced stderr output.

property process_id_included#

Whether process identifiers are included.

property source_included#

Whether logger channels are included.

property standard_stream_enabled#

Whether stdout and stderr output is enabled.

property standard_stream_flush#

Whether stdout is flushed after every record.

property standard_stream_level#

The standard-stream threshold.

property thread_id_included#

Whether thread identifiers are included.

property timestamp_included#

Whether absolute timestamps are included.

property trace_id_included#

Whether active trace identifiers are included.

property utc_timestamps#

Whether absolute timestamps use UTC.

class isaacsim.common.logging.ChannelLoggingConfig(self)#

Patch-style settings for one logging channel.

Example:

>>> from isaacsim.common.logging import ChannelLoggingConfig

>>> channel = ChannelLoggingConfig()
>>> channel.channel = "isaacsim.sensors.camera"
property channel#

The non-empty logging channel.

property enabled#

The enabled value used by OVERRIDE.

property enabled_behavior#

The action to apply to enabled.

property minimum_level#

The threshold used by OVERRIDE.

property minimum_level_behavior#

The action to apply to minimum_level.

class isaacsim.common.logging.ChannelSettingBehavior(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)#

Action to apply to one channel setting in a configuration patch.

INHERIT = 1#
OVERRIDE = 2#
UNCHANGED = 0#
class isaacsim.common.logging.ConfigureResult(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)#

Result of applying logging configuration.

BACKEND_UNAVAILABLE = 2#
INVALID_ARGUMENT = 1#
SUCCESS = 0#
class isaacsim.common.logging.OutputStream(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)#

Selection of the standard logging stream.

DEFAULT = 0#
STDERR = 1#
class isaacsim.common.logging.ElapsedTimeUnit(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)#

Unit used for the elapsed-time prefix.

DISABLED = 0#
MICROSECONDS = 2#
MILLISECONDS = 1#
NANOSECONDS = 3#
isaacsim.common.logging.configure_global(
config: isaacsim.common.logging.bindings._bindings.GlobalLoggingConfig,
) → isaacsim.common.logging.bindings._bindings.ConfigureResult#

Apply selected process-wide logging settings.

Parameters:

config – Configuration patch to apply.

Returns:

Result of applying the selected settings.

Example:

>>> configure_global(config)
ConfigureResult.SUCCESS

Flush#

isaacsim.common.logging.flush() → None#

Flush records pending in the process-wide native logging backend.

Example:

>>> flush()

flush drains Carbonite’s process-wide backend; it is not scoped to one logger.