Is this page helpful?

Python API#

class TelemetryManager#

Bases: object

Singleton that manages structured-log schema registration and event emission.

On first access the common Isaac Sim schema is automatically registered so that the typed helper functions (emit_extension_activated(), emit_feature_used(), emit_error()) work without any setup.

Extensions that need domain-specific telemetry can register additional schemas via register_schema() and emit events via send_event().

classmethod get_instance() → TelemetryManager#

Return the singleton instance, creating it on first call.

Returns:

The global TelemetryManager instance.

Example:

from isaacsim.core.telemetry import TelemetryManager

manager = TelemetryManager.get_instance()
is_enabled() → bool#

Check whether structured logging is enabled.

Returns:

True if the /structuredLog/enable carb setting is truthy.

Example:

manager = TelemetryManager.get_instance()
if manager.is_enabled():
    print("Telemetry is active")
register_schema(
schema_name: str,
schema: dict,
) → dict | None#

Register a baked JSON schema with the structured-log system.

The schema dict must follow the Carbonite baked JSON Schema draft-07 format (with schemaMeta, definitions/events, $schema, anyOf). See the Carbonite structured-log walkthrough for details.

Parameters:

  • schema_name – Unique key for later lookups (e.g. the schema’s clientName).

  • schema – Baked JSON schema dict passed directly to omni.structuredlog.register_schema().

Returns:

Dict mapping short event names to event handles, or None if registration failed or telemetry is disabled.

Example:

from isaacsim.core.telemetry import get_telemetry_manager

events = get_telemetry_manager().register_schema(schema_name="my.schema", schema=my_schema_dict)
send_event(
schema_name: str,
event_name: str,
data: dict,
) → bool#

Emit a structured-log event.

Parameters:

  • schema_name – Key used during register_schema().

  • event_name – Short event name within the schema.

  • data – Dict of event properties matching the schema definition.

Returns:

True if the event was sent, False otherwise.

Example:

from isaacsim.core.telemetry import get_telemetry_manager

get_telemetry_manager().send_event(
    schema_name="my.schema", event_name="myEvent", data={"key": "value"}
)
unregister_schema(schema_name: str) → None#

Remove a previously registered schema from tracking.

This does not unregister the schema from the Carbonite structured-log system (schemas remain registered for the process lifetime), but it prevents further events from being sent through this manager for the given schema_name.

Parameters:

schema_name – Key used during register_schema().

Example:

from isaacsim.core.telemetry import get_telemetry_manager

get_telemetry_manager().unregister_schema("my.schema")
emit_error(
extension_id: str,
error_category: str,
error_type: str,
operation: str,
recoverable: bool = True,
) → bool#

Emit an errorOccurred event.

All parameters are structured identifiers — no free-form text is accepted, which eliminates PII risk by design.

Parameters:

  • extension_id – Extension where the error occurred.

  • error_category – Broad classification. Must be one of "import_failure", "validation_error", "runtime_error", "configuration_error", "dependency_error", or "timeout".

  • error_type – Extension-specific error code for drill-down (e.g. "urdf_joint_parse").

  • operation – The feature/operation active when the error happened. Should match featureName values used in featureUsed events.

  • recoverable – True if the operation could continue or degrade gracefully, False if it aborted.

Returns:

True if the event was sent successfully.

Example:

from isaacsim.core.telemetry import emit_error

emit_error(
    "isaacsim.asset.importer.urdf",
    "import_failure",
    "urdf_joint_parse",
    "import_urdf",
    recoverable=False,
)
emit_extension_activated(
extension_id: str,
extension_version: str,
action: str,
) → bool#

Emit an extensionActivated event.

Parameters:

  • extension_id – Extension identifier (e.g. "isaacsim.sensors.experimental.rtx").

  • extension_version – Semantic version string (e.g. "1.2.0").

  • action – "enabled" or "disabled".

Returns:

True if the event was sent successfully.

Example:

from isaacsim.core.telemetry import emit_extension_activated

emit_extension_activated(
    extension_id="isaacsim.sensors.experimental.rtx", extension_version="1.2.0", action="enabled"
)
emit_feature_used(
extension_id: str,
feature_name: str,
feature_type: str,
duration_ms: int = 0,
) → bool#

Emit a featureUsed event.

Parameters:

  • extension_id – Extension that owns the feature.

  • feature_name – Short identifier (e.g. "import_urdf").

  • feature_type – One of "command", "menu_item", or "api_call".

  • duration_ms – Wall-clock duration in milliseconds.

Returns:

True if the event was sent successfully.

Example:

from isaacsim.core.telemetry import emit_feature_used

emit_feature_used(
    extension_id="isaacsim.asset.importer.urdf",
    feature_name="import_urdf",
    feature_type="command",
    duration_ms=1234,
)
get_telemetry_manager() → TelemetryManager#

Return the global TelemetryManager singleton.

Returns:

The shared TelemetryManager instance.

Example:

from isaacsim.core.telemetry import get_telemetry_manager

manager = get_telemetry_manager()
    manager.send_event(schema_name="my.schema", event_name="myEvent", data={"key": "value"})
telemetry(
extension_id: str,
feature_name: str,
feature_type: str = 'api_call',
error_category: str = 'runtime_error',
) → Callable[[Callable[[...], Any]], Callable[[...], Any]]#

Decorator that instruments a function with full telemetry.

On successful return a featureUsed event is emitted with the wall-clock duration. If the function raises, an errorOccurred event is emitted instead and the exception is re-raised unchanged.

Works with both regular and async functions.

Parameters:

  • extension_id – Extension that owns the feature.

  • feature_name – Short identifier (e.g. "import_urdf").

  • feature_type – One of "command", "menu_item", or "api_call".

  • error_category – Category used in the errorOccurred event if the function raises.

Returns:

A decorator that wraps the target function.

Example:

from isaacsim.core.telemetry import telemetry

@telemetry(extension_id="isaacsim.sensors.experimental.rtx", feature_name="create_lidar_sensor")
def create_lidar_sensor(prim_path, config):
    ...

@telemetry(extension_id="isaacsim.asset.importer.urdf", feature_name="import_urdf", feature_type="command")
async def import_urdf(file_path):
    ...
telemetry_error(
extension_id: str,
feature_name: str,
error_category: str = 'runtime_error',
) → Callable[[Callable[[...], Any]], Callable[[...], Any]]#

Decorator that emits an errorOccurred event when the function raises.

No featureUsed event is emitted on success. Use this for functions where you only care about failure tracking.

Works with both regular and async functions.

Parameters:

  • extension_id – Extension where the error would occur.

  • feature_name – Operation name used as the operation field in the error event.

  • error_category – Broad error classification.

Returns:

A decorator that wraps the target function.

Example:

from isaacsim.core.telemetry import telemetry_error

@telemetry_error(extension_id="isaacsim.app.setup", feature_name="app_startup")
def initialize():
    ...
telemetry_extension(
cls: type[_T],
) → type[_T]#

Class decorator that instruments an omni.ext.IExt subclass with lifecycle telemetry.

Wraps on_startup and on_shutdown to automatically emit extensionActivated events with action="enabled" / "disabled". The extension name and version are parsed from the ext_id argument that Kit passes to on_startup (format "ext.name-X.Y.Z").

Handles both on_startup(self, ext_id) and on_startup(self) signatures — Kit inspects the method signature to decide whether to pass ext_id.

Parameters:

cls – The IExt subclass to decorate.

Returns:

The same class with wrapped on_startup / on_shutdown.

Example:

from isaacsim.core.telemetry import telemetry_extension

@telemetry_extension
class MyExtension(omni.ext.IExt):
    def on_startup(self, ext_id):
        ...

    def on_shutdown(self):
        ...
telemetry_usage(
extension_id: str,
feature_name: str,
feature_type: str = 'api_call',
) → Callable[[Callable[[...], Any]], Callable[[...], Any]]#

Decorator that emits a featureUsed event on successful return.

Exceptions are ignored (no errorOccurred event). Use this for functions where errors are expected or handled elsewhere.

Works with both regular and async functions.

Parameters:

  • extension_id – Extension that owns the feature.

  • feature_name – Short identifier (e.g. "query_sensor").

  • feature_type – One of "command", "menu_item", or "api_call".

Returns:

A decorator that wraps the target function.

Example:

from isaacsim.core.telemetry import telemetry_usage

@telemetry_usage(extension_id="isaacsim.sensors.experimental.rtx", feature_name="query_sensor")
def query_sensor(sensor_id):
    ...