IObservabilityProvider#

Fully qualified name: omni::observability::IObservabilityProvider

Defined in omni/observability/IObservabilityProvider.h

class IObservabilityProvider#

Direct interface for observability functionality based on OpenTelemetry.

This includes support for OTLP communications over HTTP or gRPC, and includes support for log, trace, and metric signal types. The OpenTelemetry system is initialized and configured with the IObservabilityProvider::initialize() function. Configuration options are provided through the standard OpenTelemetry environment variables first, then through the InitializeDesc::settings object only if a given environment variable is not defined.

Remark

This is an ABI layer for the library. This is intended to be accessed through the State object, which automatically handles lifetimes.

Public Functions

virtual void addResource(
carb::cpp::string_view name,
carb::cpp::string_view value,
) = 0#

Add a resource key/value pair to the opentelemetry context.

Remark

Resources are emitted with every log message. Resources need to be set before initialize is called for the first time. If a resource with this name has already been set, the previous value will be overwritten. Resources cannot be removed.

Thread Safety

Calls to this are internally serialized under a mutex.

Note

The OTEL_RESOURCE_ATTRIBUTES environment variable (as well as the /observability/resourceAttributes settings key) can override any keys that are set by addResource().

Parameters:
virtual void initialize(const InitializeDesc &desc) = 0#

Initialize telemetry for the process.

Remark

This will initialize opentelemetry for the process the first time it is called. Subsequent calls will not alter the telemetry state. Each call increments an internal ref count that must be decremented by calling finish().

Thread Safety

The calls to this function are internally serialized.

Parameters:

desc – [in] Additional information to configure telemetry with.

virtual void flush() = 0#

Flush all queues without shutting down.

Remark

This function forces a flush of all telemetry data (metrics, traces, logs) without shutting down the telemetry system or affecting reference counting.

Thread Safety

The calls to this function are internally serialized.

virtual void finish() = 0#

Shutdown OpenTelemetry and flush all queues.

Remark

This function internally decrements the ref count that was incremented by each initialize call. Once that hits 0, this will flush all queues and shut the telemetry system down.

Thread Safety

The calls to this function are internally serialized.

virtual LoggerId registerLogger(Logger *logger) = 0#

Registers an optional logger object for debugging purposes.

Remark

This registers a new debug logger with the core library. This logger will receive internal log messages from the core library so that the host app may dispatch them to its own logging system.

Note

These logger objects are only for internal diagnostic and debugging messages from this library. These are not related to log signals sent through OTLP messages.

Parameters:

logger – [in] The new logger object to register with the core library. This will receive debug log messages from the core library itself. This logger object may decide what to do with the log information. For example, the log message could be emitted through the host app’s own logging system. The host app may also choose to filter the log messages depending on app settings. If no loggers are registered, all internal log messages will be written to stderr unconditionally. Registering a logger that simply ignores each message can also be used to silence the internal debug log messages.

Returns:

An ID that should be used to later unregister a given logger. This will return kInvalidLoggerId if the logger could not be registered for any reason. When a valid logger ID is returned, it must be unregistered later by passing the same ID to unregisterLogger(). Any given logger ID that is returned from here must be unregistered even if the same ID is returned on multiple calls.

virtual void unregisterLogger(LoggerId id) = 0#

Unregisters a previously registered debug logger.

Remark

This unregisters a debug logger that was previously registered. Once this logger is unregistered, it will no receive any log messages.

Parameters:

id – [in] The ID of the logger to be unregistered. All successful calls to registerLogger() must be paired with a call to unregisterLogger() passing the same ID. If this is kInvalidLoggerId, the operation will silently fail immediately.

virtual void setLogLevel(LogLevel level) = 0#

Sets the current log level for messages coming from the core library itself.

Remark

This sets the new log level for log messages coming from the core library. This log level does not affect log messages coming from the OpenTelemetry SDK though. That log level is controlled by the OTEL_LOG_LEVEL environment variable.

Parameters:

level – [in] The new log level to set. This must be one of the kLogLevel* values. Any other values will be clamped to the range of those known values.

virtual LogLevel getLogLevel() = 0#

Retrieves the current log level for the core library itself.

Returns:

The current log level for the core library. This level only affects log messages generated internally by the core library, not messages from the OpenTelemetry SDK. The latter is controlled by the OTEL_LOG_LEVEL environment variable.

virtual carb::ObjectPtr<IMeter> createMeter(
carb::cpp::string_view name,
carb::cpp::string_view version,
carb::cpp::string_view schemaUrl,
) = 0#

Create a meter for collecting metrics.

Parameters:

  • name – [in] The name of the meter.

  • version – [in] The version of the meter.

  • schemaUrl – [in] The schema URL for the meter.

Returns:

A meter instance, or nullptr if creation failed.