Dynamically Loaded Configuration Extension#
Overview#
The omni.kit.watched_config extension allows for changes to a config file to be tracked so that
it can be dynamically loaded into the settings registry after a change is detected. A config file
may also be loaded explicitly on request as needed. When loading a config file either from an
explicit call or due to a detected change on a watched file, an optional timeout can be set to
allow the previous settings to be restored automatically at a later time.
This extension is intended to be used as a debugging helper for live services. This can be used to temporarily change logging settings on a running service to get more information out of a problem without needing to take down the node, restart the service with different logging settings, then restart it again with normal settings when bringing the node back online.
Interface#
The omni.kit.watched_config extension contains an implementation of the omni::kit::IWatchedConfig
interface. There is also a Python bindings module for the interface at omni.kit.watched_config.
The interface provides all the functionality for the extension including setting the name and path
of the file to be tracked, helper functions to immediately load and restore settings, and a way to
register for callbacks (C++ only) that indicate when settings have been merged or restored. The
callbacks can be used by other plugins or extensions to allow them to refresh their own settings
values when a change occurs (a settings change subscription can be used for this purpose as well),
or allow for synchronization or waiting on an expected change to be loaded into the settings registry.
Configuration Options#
The following configuration options are avaialble with the omni.kit.watched_config extension. These
allow its config file change tracking functionality to be enabled immediately at startup instead of
needing to do it programmatically.
/app/watchedConfigFile: Setting that specifies the name of the file to initially track for changes. This must be either a.jsonor.tomlfile. This may be a relative or absolute path. If a relative path is given, it will be assumed to be relative to the current working directory at startup time. This may be an empty string if no config file is to be tracked for changes. This setting does not have a default value but is treated as if no file were specified./app/watchedConfigDurationSeconds: Setting that specifies how long in seconds newly merged settings should be valid for after loading a config file. If this value is positive and non-zero, a restore dictionary will be created and merged once the timeout expires. Note that this value may also be changed inside a watched config file itself. In that case, the value in the config file will only take effect the next time the file’s settings are merged. Once the settings are restored again, the original value will be restored. This defaults to 0 seconds (ie: loaded config changes will persist for the remainder of the process).