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:

name – [in] The name of the resource to add. The name will ideally conform to something in the attribute registry: https://opentelemetry.io/docs/specs/semconv/registry/attributes/
value – [in] The value of the resource to set. Empty strings are allowed and they will show up empty in the OTel resources.

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 and and the internal logger in the OpenTelemetry SDK/API. This log level does not in any way affect the filtering of log signals emitted through the OpenTelemetry API. The internal loggers in both the core library and the OpenTelemetry SDK/API is controlled by the OTEL_LOG_LEVEL and OMNI_OTEL_ENABLE_INTERNAL_LOGGING settings. By default, the internal loggers will be disabled.

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 and the OpenTelemetry SDK/API. This log level does not in any way affect the filtering of log signals emitted through the OpenTelemetry API. The internal loggers in both the core library and the OpenTelemetry SDK/API is controlled by the OTEL_LOG_LEVEL and OMNI_OTEL_ENABLE_INTERNAL_LOGGING settings. By default, the internal loggers will be disabled.

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 your library or component that emits the metrics.
schemaUrl – [in] The schema URL for the meter. This helps observability backends understand the structure and conventions used in your telemetry data, enabling consumers to interpret them correctly. An example of such standardization is the metric with name http.server.duration, which should be a histogram that uses seconds as the unit of measurement, and should include attributes http.method, http.status_code, http.route, server.address, and server.port.

Returns:

A meter instance, or nullptr if creation failed.

virtual bool isSignalEnabled(SignalType types) = 0#

Checks if the requested signal type(s) are currently configured and enabled.

Parameters:: types – [in] The signal types to check the enable status of. This may be any combination of the SignalType flags.
Returns:: true if all of the requested signal types are currently configured and enabled. A signal type is considered configured and enabled if it at least has a defined exporter and destination. The definition of a destination can vary across different exporters. For example, a ‘file’ exporter would need to have a file name also provided and that file was able to be opened for writing. For an ‘otlp’ exporter, a URL would also need to be provided (no validity checking would be done on the URL though). Returns false if either none or not all of the requested signal types are not configured or enabled.