IMeter#

Fully qualified name: omni::observability::IMeter

Defined in omni/observability/IMetrics.h

class IMeter : public carb::IObject#

Factory interface for creating metric instruments.

Each instrument is uniquely identified by its name, description, and unit. Two instruments with the same name but different units are considered distinct instruments. Units should follow the UCUM (Unified Code for Units of Measure) standard: https://unitsofmeasure.org/ucum.html

Remark

This interface provides virtual member functions to create various types of metric instruments including counters, up/down counters, histograms, and observable instruments. The virtual functions are provided for ABI stability. Users should prefer the namespace-scope function templates defined later in this file, which provide object lifetime safety and convenience.

If multiple instruments are created with the same name, description, and unit, the returned objects will be different but the actual metric data (such as counter values) will be shared. This allows multiple parts of code to independently obtain references to the same logical instrument.

Parameter validation for the instrument creation functions below: Name must start with a letter, contain only letters, digits, and -_./ characters, max 255 chars. Unit must be ASCII only, max 63 chars. Description has no restrictions.

Public Functions

virtual ~IMeter() = default#
virtual ICounter<std::uint64_t> *createCounter_uint64_t(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create a counter instrument for std::uint64_t values.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “requests”).

Returns:

A pointer to the created counter, or nullptr on failure.

virtual ICounter<double> *createCounter_double(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create a counter instrument for double values.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “requests”).

Returns:

A pointer to the created counter, or nullptr on failure.

virtual IUpDownCounter<std::int64_t> *createUpDownCounter_int64_t(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create an up/down counter instrument for std::int64_t values.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the up/down counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “connections”).

Returns:

A pointer to the created up/down counter, or nullptr on failure.

virtual IUpDownCounter<double> *createUpDownCounter_double(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create an up/down counter instrument for double values.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the up/down counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “connections”).

Returns:

A pointer to the created up/down counter, or nullptr on failure.

virtual IHistogram<std::uint64_t> *createHistogram_uint64_t(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create a histogram instrument for std::uint64_t values.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the histogram instrument.

  • description – [in] A description of what the histogram measures.

  • unit – [in] The unit of measurement (e.g., “ms”, “bytes”).

Returns:

A pointer to the created histogram, or nullptr on failure.

virtual IHistogram<double> *createHistogram_double(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create a histogram instrument for double values.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the histogram instrument.

  • description – [in] A description of what the histogram measures.

  • unit – [in] The unit of measurement (e.g., “ms”, “bytes”).

Returns:

A pointer to the created histogram, or nullptr on failure.

virtual IObservableInstrument *createObservableCounter_int64_t(
ObservableInstrumentCallback<std::int64_t> callback,
void *context,
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create an observable counter instrument for std::int64_t values.

Parameters:

  • callback – [in] The callback function to invoke for sampling the counter value.

  • context – [in] User-defined context passed to the callback.

  • name – [in] The name of the observable counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “requests”).

Returns:

A pointer to the created observable instrument, or nullptr on failure.

virtual IObservableInstrument *createObservableCounter_double(
ObservableInstrumentCallback<double> callback,
void *context,
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create an observable counter instrument for double values.

Parameters:

  • callback – [in] The callback function to invoke for sampling the counter value.

  • context – [in] User-defined context passed to the callback.

  • name – [in] The name of the observable counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “requests”).

Returns:

A pointer to the created observable instrument, or nullptr on failure.

virtual IObservableInstrument *createObservableUpDownCounter_int64_t(
ObservableInstrumentCallback<std::int64_t> callback,
void *context,
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create an observable up/down counter instrument for std::int64_t values.

Parameters:

  • callback – [in] The callback function to invoke for sampling the counter value.

  • context – [in] User-defined context passed to the callback.

  • name – [in] The name of the observable up/down counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “connections”).

Returns:

A pointer to the created observable instrument, or nullptr on failure.

virtual IObservableInstrument *createObservableUpDownCounter_double(
ObservableInstrumentCallback<double> callback,
void *context,
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit,
) noexcept = 0#

Create an observable up/down counter instrument for double values.

Parameters:

  • callback – [in] The callback function to invoke for sampling the counter value.

  • context – [in] User-defined context passed to the callback.

  • name – [in] The name of the observable up/down counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “connections”).

Returns:

A pointer to the created observable instrument, or nullptr on failure.

template<class ValueType>
ICounter<ValueType> *createCounter(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit = "",
) noexcept#

Create a counter instrument with the specified ValueType.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “requests”).

Returns:

A pointer to the created counter, or nullptr on failure.

template<class ValueType>
IUpDownCounter<ValueType> *createUpDownCounter(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit = "",
) noexcept#

Create an up/down counter instrument with the specified ValueType.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the up/down counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “connections”).

Returns:

A pointer to the created up/down counter, or nullptr on failure.

template<class ValueType>
IHistogram<ValueType> *createHistogram(
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit = "",
) noexcept#

Create a histogram instrument with the specified ValueType.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • name – [in] The name of the histogram instrument.

  • description – [in] A description of what the histogram measures.

  • unit – [in] The unit of measurement (e.g., “ms”, “bytes”).

Returns:

A pointer to the created histogram, or nullptr on failure.

template<class ValueType>
IObservableInstrument *createObservableCounter(
ObservableInstrumentCallback<ValueType> callback,
void *context,
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit = "",
) noexcept#

Create an observable counter instrument with the specified ValueType.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • callback – [in] The callback function to invoke for sampling the counter value.

  • context – [in] User-defined context passed to the callback.

  • name – [in] The name of the observable counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “requests”).

Returns:

A pointer to the created observable instrument, or nullptr on failure.

template<class ValueType>
IObservableInstrument *createObservableUpDownCounter(
ObservableInstrumentCallback<ValueType> callback,
void *context,
carb::cpp::string_view name,
carb::cpp::string_view description,
carb::cpp::string_view unit = "",
) noexcept#

Create an observable up/down counter instrument with the specified ValueType.

Remark

The returned pointer should be managed using carb::ObjectPtr for proper lifetime management.

Parameters:

  • callback – [in] The callback function to invoke for sampling the counter value.

  • context – [in] User-defined context passed to the callback.

  • name – [in] The name of the observable up/down counter instrument.

  • description – [in] A description of what the counter measures.

  • unit – [in] The unit of measurement (e.g., “bytes”, “connections”).

Returns:

A pointer to the created observable instrument, or nullptr on failure.

virtual size_t addRef() = 0#

Atomically add one to the reference count.

Returns:

The current reference count after one was added, though this value may change before read if other threads are also modifying the reference count. The return value is guaranteed to be non-zero.

virtual size_t release() = 0#

Atomically subtracts one from the reference count.

If the result is zero, carb::deleteHandler() is called for this.

Returns:

The current reference count after one was subtracted. If zero is returned, carb::deleteHandler() was called for this.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc(
) noexcept#

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:

The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc(
) noexcept#

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:

The carb::InterfaceDesc struct with information about the latest version of this interface.