omni::structuredlog::IStructuredLogSettings2_abi

Defined in omni/structuredlog/IStructuredLogSettings2.h

class IStructuredLogSettings2_abi : public omni::core::Inherits<omni::structuredlog::IStructuredLogSettings_abi, std::integral_constant<uint64_t, carb::fnv1aHash("omni.structuredlog.IStructuredLogSettings2")>::value>

Interface for the second version of the IStructuredLogSettings interface.

This interface exposes more settings to control the behaviour of the structured logging system. This object can be retrieved directly or by casting the main IStructuredLog interface to this type using omni::core::ObjectPtr::as<>().

Subclassed by omni::core::Generated< omni::structuredlog::IStructuredLogSettings2_abi >

Public Functions

inline void *cast(omni::core::TypeId id) noexcept

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety

This method is thread safe.

inline void acquire() noexcept

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

inline void release() noexcept

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

Protected Functions

virtual uint64_t getHeartbeatPeriod_abi() noexcept = 0

Retrieves the current heartbeat message period in seconds.

Returns

The minimum time in seconds between heartbeat events. This will be omni::structuredlog::kHeartbeatDisabled if the heartbeat events are disabled. When enabled, the heartbeat events will be generated within ~100ms of this scheduled time. In general, it is expected that the heartbeat period be on the scale of one minute or more to reduce the overall amount of event traffic.

virtual void setHeartbeatPeriod_abi(uint64_t period) noexcept = 0

Sets the new heartbeat event period in seconds.

Remark

The heartbeat events can be used to get an estimate of a session’s length even if the ‘exit’ or ‘crash’ process lifetime events are missing (ie: power loss, user kills the process, blue screen of death or kernel panic, etc). The session can neither be assumed to have exited normally nor crashed with only these heartbeat events present however.

Parameters

period – [in] The minimum time in seconds between generated heartbeat events. This may be omni::structuredlog::kHeartbeatDisabled to disable the heartbeat events.

Returns

No return value.

virtual bool getNeedLogHeaders_abi() noexcept = 0

Retrieves whether header objects will be added to each newly written log file.

Returns

true if headers will be written to each new log file. Returns false if header objects will be omitted from new log files.

virtual void setNeedLogHeaders_abi(bool needHeaders) noexcept = 0

Sets whether headers will be added to each newly written log file.

Remark

This sets whether log headers will be written out to each new log file. The header is consumed and modified by the telemetry transmitter app to allow it to store its progress in processing each log file. If the header is missing, the transmitter app will simply ignore the log file. Omitting the headers in log files allows the log output to purely just be the structured log event messages so they can be more easily consumed wholesale by external apps.

Note

Changing this setting will only take effect the next time a new log file is written out to disk. Disabling this will not remove the header object from an existing log file.

Parameters

needHeaders – [in] Set to true to indicate that headers should be added to each newly written log file. Set to false to indicate that the header should be omitted.

Returns

No return value.

virtual OutputFlags getOutputFlags_abi() noexcept = 0

Retrieves the current set of output flags for structured logging.

Returns

The current output flags for the structured logging system. These indicate how various aspects of the logging system will function. Note that some flags may affect whether the produced messages are compatible with the remainder of the telemetry toolchain in Omniverse apps. By default, all output flags are off.

virtual void setOutputFlags_abi(OutputFlags flagsToAdd, OutputFlags flagsToRemove) noexcept = 0

Sets or clears one or more output flags for structured logging.

Remark

This sets or clears flags that affect the output from the structured logging system. These flags are all disabled by default. These flags will take effect the next time a message is emitted.

Parameters
Returns

No return value.

virtual size_t getEventQueueSize_abi() noexcept = 0

Retrieves the current event queue size.

Thread Safety

This call is thread safe.

Returns

The current size of the event queue buffer in bytes. Note that once the first event message is sent, the event queue will be running and this will continue to return the ‘active’ size of the event queue regardless of any new size that is passed to omni::structuredlog::IStructuredLogSettings::setEventQueueSize(). Any new size will only be made active once the event queue is stopped with omni::structuredlog::IStructuredLogControl::stop(). The default size is 2MiB.

virtual int64_t getLogSizeLimit_abi() noexcept = 0

Retrieves the current maximum log file size.

Thread Safety

This call is thread safe.

Returns

The current maximum log file size in bytes. This helps to control when log files get rotated out and started anew for the process. The number of old logs that are kept is controlled by the log retention count. The default size is 50MB.

virtual size_t getLogRetentionCount_abi() noexcept = 0

Retrieves the current log retention count.

Thread Safety

This call is thread safe.

Returns

The maximum number of log files to retain when rotating log files. When a new log is rotated out, the oldest one that is beyond this count will be deleted. The default is 3.

virtual IdMode getEventIdMode_abi() noexcept = 0

Retrieves the current event identifier mode.

Thread Safety

This call is thread safe.

Returns

The current event identifier mode. The default is omni::structuredlog::IdMode::eFastSequential.

virtual IdType getEventIdType_abi() noexcept = 0

Retrieves the current event identifier type.

Thread Safety

This call is thread safe.

Returns

The current event identifier type. The default is omni::structuredlog::IdType::eUuid.

virtual const char *getLogOutputPath_abi() noexcept = 0

Retrieves the current log output path.

Thread Safety

This call is thread safe to retrieve the path string. However, the string itself may become invalidated after return if the log output path is changed with a call to omni::structuredlog::IStructuredLogSettings::setLogOutputPath(). It is the host app’s responsibility to ensure the log output path is not being changed while this string is being used. The returned string generally should not be cached anywhere. It should be retrieved from here any time it is needed.

Returns

The path that log files will be written to. This defaults to the launcher app’s default log directory. The host app should override that if that location is not suitable.

virtual const char *getLogDefaultName_abi() noexcept = 0

Retrieves the default log name if any has been set.

Thread Safety

This call itself is thread safe. However, the returned string is only valid until either the log path or the default log name changes. It is the caller’s responsibility to ensure the returned string is used safely.

Returns

The default log file name that will be used to output all events that are not explicitly marked with the omni::structuredlog::fEventFlagUseLocalLog flag. This name will include the log output path as set by omni::structuredlog::IStructuredLogSettings::getLogOutputPath().

Returns

nullptr if no default log name has been set with omni::structuredlog::IStructuredLogSettings::setLogDefaultName() or the default log name has been cleared.

virtual const char *getLogPathForEvent_abi(EventId eventId) noexcept = 0

Retrieves the log path that a given event will be written to.

Thread Safety

This call itself is thread safe. However, the returned string is only valid until either the log path or the default log name changes. It is the caller’s responsibility to ensure the returned string is used safely.

Parameters

eventId – [in] The ID of the event to retrieve the log path for. This must be the same ID used when the event was registered. This may also be omni::structuredlog::kDefaultLogPathEvent to retrieve the path for the default log.

Returns

The name and path of the log file that the requested event would go to if it were emitted with current settings.

Returns

the name and path of the default log file if kDefaultLogPathEvent is used for for the event ID.

Returns

nullptr if the given event ID is unknown or kDefaultLogPathEvent was used and no default log name has been set.

virtual const char *getUserId_abi() noexcept = 0

Retrieves the current user ID.

Thread Safety

This call is thread safe to retrieve the user ID. However, the string itself may become invalidated after return if the user ID is changed with a call to to omni::structuredlog::IStructuredLogSettings::setUserId(). It is the host app’s responsibility to ensure the user ID is not being changed while this string is being used. The returned string generally should not be cached anywhere. It should be retrieved from here any time it is needed.

Returns

The current user ID. This may be a user name or user identification number. The specific format and content is left entirely up to the host app itself. By default, the user ID will either be the user ID listed in the privacy settings file if present, or a random number if the user ID setting is not present. When a random number is used for the user ID, it is useful for anonymizing user event messages.

virtual SessionId getSessionId_abi() noexcept = 0

Retrieves the current session ID.

Remark

This retrieves the session ID for the current structured log session. This ID is chosen when the structured log session starts and remains constant for its lifetime.

Returns

The identifier for the current session if the current privacy settings allow it.

virtual void setEventQueueSize_abi(size_t sizeInBytes) noexcept = 0

Sets the new event queue buffer size.

Remark

This sets the new event queue buffer size. A larger buffer allows more events to be sent and processed simultaneously in an app. If the buffer ever fills up, events may be dropped if they cannot be processed fast enough. For host apps that infrequently send small events, some memory can be saved by reducing this buffer size. However, host apps that need to be able to send messages frequently, especially simultaneously from multiple threads, should use a larger buffer size to allow the event queue to keep up with the incoming event demand.

Remark

Once the event queue is running (ie: the first message has been sent), changing its size will cause a second queue to be created at the new size. The old queue will be flushed and the new queue will be made active. There will be a short period where two queues will be running simultaneously. Any new events that are queued during this period will be added to the new queue. There is no need to stop the old queue before changing the size, this will be handled automatically. Note that during one of these queue transitions there may be a short period where omni::structuredlog::getEventQueueSize() may return the new queue’s size even if the old queue is still active.

Thread Safety

This call is thread safe.

Note

Changing the queue size frequently will lead to stalls in the processing pipeline. Generally the queue size should be set once on startup of an app and left at that configured size for the process’ lifetime.

Parameters

sizeInBytes – [in] the new event queue buffer size in bytes to use. This will be silently clamped to an acceptable minimum size. The default is 2MiB.

Returns

No return value.

virtual void setLogSizeLimit_abi(int64_t limitInBytes) noexcept = 0

Sets the log size limit.

Remark

This sets the log size limit. When a log reaches (approximately) this size, it will be rotated out and a new log file started. The number of old log files that are kept is controlled by the log retention count.

Thread Safety

This call is thread safe.

Parameters

limitInBytes – [in] The new log size limit in bytes. This controls the maximum size a log file can get up to before it is rotated out and a new log is started. This will be silently clamped to an acceptable minimum size. The default is 50MiB. The minimum size limit is 256KiB.

Returns

No return value.

virtual void setLogRetentionCount_abi(size_t count) noexcept = 0

Sets the log retention count.

Thread Safety

This call is thread safe.

Parameters

count – [in] The maximum number of old log files to maintain. When a log file grows beyond the current size limit, it will be renamed and a new log opened with the original name. The oldest log file may be deleted if there are more logs than this count. The default is 3.

Returns

No return value.

virtual void setEventIdMode_abi(IdMode mode, IdType type) noexcept = 0

Sets the current event identifier mode and type.

Thread Safety

This call is thread safe.

Parameters

  • mode – [in] The new identifier mode to use. This will take effect on the next event that is sent. The default is IdMode::eFastSequential.

  • type – [in] The new identifier type to use. This will take effect on the next event that is sent. The default is IdType::eUuid.

Returns

No return value.

virtual void setLogOutputPath_abi(const char *path) noexcept = 0

Sets the new log output path.

Remark

This changes the log file location for the calling process. The log file locations for all registered schemas will be updated as well. If a schema has been set to keep its log file open, it will be closed at this point (if already open). The next event that is written to the log file will open a new log at the new location. The old log file (if any) will not be moved from the previous location.

Thread Safety

This call is thread safe. However, it is the caller’s responsibility to ensure that no other host thread is simultaneously operating on the log output path string returned from omni::structuredlog::IStructuredLogSettings::getLogOutputPath() and that nothing else has cached that returned string since it could become invalidated here.

Note

There is still a possible race condition with changing the log directory if events are pending for processing. If the log file had been opened to write out a message at the same time this is changing the log path, the change in log path will not take effect until the next event message is being processed.

Parameters

path – [in] The new log file path to use. This may not be an empty string. The default is the Launcher app’s expected log file path. This may be either a relative or absolute path. However, note that if this is relative, the location of the log files may change if the process’s current working directory ever changes. It is highly suggested that only absolute paths be used. This may also be omni::structuredlog::kDefaultLogPathName or nullptr to set the log output path back to its default location.

Returns

No return value.

virtual void setLogDefaultName_abi(const char *name) noexcept = 0

Sets the new default log name to use for message output.

Remark

This sets the new default log file name. When set to a valid file name, all messages coming from events that do not use the omni::structuredlog::fEventFlagUseLocalLog flag will be written to the log file using this name in the current log output directory. When either this name or the log output directory changes, any open log files will be closed and reopened under the new name and path when the next event is written.

Note

When log rotation occurs, the rotation number is inserted before the file extension (e.g. filename.ext is rotated to filename.1.ext). If no extension is detected, the number is just appended to the file name. A file extension is detected with the following regex: \..{0,4}$.

Parameters

name – [in] The new default name to set for the message log file. This may be an empty string or nullptr to restore the default behavior of writing each new message to its own schema’s log file. This should just be the name of the file and not include any path components. This may also be one of the special values /dev/stdout or /dev/stderr to send the output to only the stdout or stderr streams. In this case, all events are output to these streams even if a given schema uses the fSchemaFlagUseLocalLog or event uses the fEventFlagUseLocalLog flag. Otherwise, if a filename is given and this name contains any path components (ie: a ‘/’), setting the default log name will fail. The log output path should be set using omni::structuredlog::IStructuredLogSettings::setLogOutputPath() instead. If this name does not have a file extension, a “.log” extension will be added. If the “.log” extension is not desired, this may be suppressed by ending the name in “.”. In this case, the final trailing “.” will be removed from the name. This name may also contain the token ‘${pid}’ that will be replaced by the current process ID.

Returns

No return value.

virtual void setUserId_abi(const char *userId) noexcept = 0

Sets the user ID to use in messages.

Remark

This sets the user ID to be used in the ‘source’ property of all event messages going forward. This will not affect the user ID of any messages that are currently being processed at the time of this call. This will affect all pending messages that are not being immediately processed however. Only the host app should set this user ID. External plugins and extensions should never change the user ID.

Thread Safety

This call is thread safe. However, it is the caller’s responsibility to ensure that no other host thread is simultaneously operating on the user ID string returned from omni::structuredlog::IStructuredLogSettings::getUserId() and that nothing else has cached that returned string since it could become invalidated here.

Parameters

userId – [in] The user ID to use with all event messages going forward. This may not be nullptr or an empty string. The default is a random number.

Returns

No return value.

virtual bool loadPrivacySettings_abi() noexcept = 0

Attempts to load the privacy settings file.

Remark

This will attempt to load the privacy settings file for the current user. Regardless of whether the file is successfully loaded, appropriate defaults will always be set for each of the expected privacy settings (as long as the ISettings interface is available).

Note

This expects that some other system has already found and attempted to load the plugin that implements the ISettings interface.

Returns

true if the privacy settings file was successfully loaded.

Returns

false if the privacy settings file could not be loaded. This failure may be caused by the file being missing, failing to open the file due to permissions, failing to allocate memory to read in the file, the file not being formatted correctly as a TOML file, or failing to merge the new values into the settings registry.

virtual bool enableSchemasFromSettings_abi() noexcept = 0

Checks app settings to see if any schemas or events should be disabled or enabled.

Remark

This checks the settings registry to determine if any schemas or events should be disabled initially. The keys in the settings registry that will be looked at are under omni::structuredlog::kSchemasStateListSetting, omni::structuredlog::kEventsStateListSetting, omni::structuredlog::kEventsStateArraySetting, and omni::structuredlog::kSchemasStateArraySetting. Each of these parts of the settings registry expects the schema or event name to be specified in a different way. Once the settings have been loaded, they are cached internally and will be used as the initial state of any newly registered schemas or events. Any state changes to events or schemas after these settings are cached can still be done programmatically with omni::structuredlog::IStructuredLog::setEnabled().

Returns

true if the settings registry was successfully checked for enable or disable states. Returns false if the carb::settings::ISettings or carb::dictionary::IDictionary plugins have not been loaded yet.

virtual void *cast_abi(TypeId id) noexcept = 0

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety

This method is thread safe.

virtual void acquire_abi() noexcept = 0

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

virtual void release_abi() noexcept = 0

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.