ceph/src/jaegertracing/opentelemetry-cpp/api/include/opentelemetry/_metrics/meter.h

   1 // Copyright The OpenTelemetry Authors
   2 // SPDX-License-Identifier: Apache-2.0
   3
   4 #pragma once
   5 #ifdef ENABLE_METRICS_PREVIEW
   6
   7 #  include "opentelemetry/_metrics/async_instruments.h"
   8 #  include "opentelemetry/_metrics/instrument.h"
   9 #  include "opentelemetry/_metrics/sync_instruments.h"
  10 #  include "opentelemetry/nostd/shared_ptr.h"
  11 #  include "opentelemetry/nostd/span.h"
  12 #  include "opentelemetry/nostd/string_view.h"
  13 #  include "opentelemetry/version.h"
  14
  15 OPENTELEMETRY_BEGIN_NAMESPACE
  16 namespace metrics
  17 {
  18 /**
  19  * Handles instrument creation and provides a facility for batch recording.
  20  *
  21  * This class provides methods to create new metric instruments, record a
  22  * batch of values to a specified set of instruments, and collect
  23  * measurements from all instruments.
  24  *
  25  */
  26 class Meter
  27 {
  28 public:
  29   virtual ~Meter() = default;
  30
  31   /**
  32    * Creates a Counter with the passed characteristics and returns a shared_ptr to that Counter.
  33    *
  34    * @param name the name of the new Counter.
  35    * @param description a brief description of what the Counter is used for.
  36    * @param unit the unit of metric values following https://unitsofmeasure.org/ucum.html.
  37    * @param enabled a boolean value that turns on or off the metric instrument.
  38    * @return a shared pointer to the created Counter.
  39    * @throws NullPointerException if {@code name} is null
  40    * @throws IllegalArgumentException if a different metric by the same name exists in this meter.
  41    * @throws IllegalArgumentException if the {@code name} does not match spec requirements.
  42    */
  43   virtual nostd::shared_ptr<Counter<short>> NewShortCounter(nostd::string_view name,
  44                                                             nostd::string_view description,
  45                                                             nostd::string_view unit,
  46                                                             const bool enabled) = 0;
  47
  48   virtual nostd::shared_ptr<Counter<int>> NewIntCounter(nostd::string_view name,
  49                                                         nostd::string_view description,
  50                                                         nostd::string_view unit,
  51                                                         const bool enabled) = 0;
  52
  53   virtual nostd::shared_ptr<Counter<float>> NewFloatCounter(nostd::string_view name,
  54                                                             nostd::string_view description,
  55                                                             nostd::string_view unit,
  56                                                             const bool enabled) = 0;
  57
  58   virtual nostd::shared_ptr<Counter<double>> NewDoubleCounter(nostd::string_view name,
  59                                                               nostd::string_view description,
  60                                                               nostd::string_view unit,
  61                                                               const bool enabled) = 0;
  62
  63   /**
  64    * Creates an UpDownCounter with the passed characteristics and returns a shared_ptr to that
  65    * UpDownCounter.
  66    *
  67    * @param name the name of the new UpDownCounter.
  68    * @param description a brief description of what the UpDownCounter is used for.
  69    * @param unit the unit of metric values following https://unitsofmeasure.org/ucum.html.
  70    * @param enabled a boolean value that turns on or off the metric instrument.
  71    * @return a shared pointer to the created UpDownCounter.
  72    * @throws NullPointerException if {@code name} is null
  73    * @throws IllegalArgumentException if a different metric by the same name exists in this meter.
  74    * @throws IllegalArgumentException if the {@code name} does not match spec requirements.
  75    */
  76   virtual nostd::shared_ptr<UpDownCounter<short>> NewShortUpDownCounter(
  77       nostd::string_view name,
  78       nostd::string_view description,
  79       nostd::string_view unit,
  80       const bool enabled) = 0;
  81
  82   virtual nostd::shared_ptr<UpDownCounter<int>> NewIntUpDownCounter(nostd::string_view name,
  83                                                                     nostd::string_view description,
  84                                                                     nostd::string_view unit,
  85                                                                     const bool enabled) = 0;
  86
  87   virtual nostd::shared_ptr<UpDownCounter<float>> NewFloatUpDownCounter(
  88       nostd::string_view name,
  89       nostd::string_view description,
  90       nostd::string_view unit,
  91       const bool enabled) = 0;
  92
  93   virtual nostd::shared_ptr<UpDownCounter<double>> NewDoubleUpDownCounter(
  94       nostd::string_view name,
  95       nostd::string_view description,
  96       nostd::string_view unit,
  97       const bool enabled) = 0;
  98
  99   /**
 100    * Creates a ValueRecorder with the passed characteristics and returns a shared_ptr to that
 101    * ValueRecorder.
 102    *
 103    * @param name the name of the new ValueRecorder.
 104    * @param description a brief description of what the ValueRecorder is used for.
 105    * @param unit the unit of metric values following https://unitsofmeasure.org/ucum.html.
 106    * @param enabled a boolean value that turns on or off the metric instrument.
 107    * @return a shared pointer to the created DoubleValueRecorder.
 108    * @throws NullPointerException if {@code name} is null
 109    * @throws IllegalArgumentException if a different metric by the same name exists in this meter.
 110    * @throws IllegalArgumentException if the {@code name} does not match spec requirements.
 111    */
 112   virtual nostd::shared_ptr<ValueRecorder<short>> NewShortValueRecorder(
 113       nostd::string_view name,
 114       nostd::string_view description,
 115       nostd::string_view unit,
 116       const bool enabled) = 0;
 117
 118   virtual nostd::shared_ptr<ValueRecorder<int>> NewIntValueRecorder(nostd::string_view name,
 119                                                                     nostd::string_view description,
 120                                                                     nostd::string_view unit,
 121                                                                     const bool enabled) = 0;
 122
 123   virtual nostd::shared_ptr<ValueRecorder<float>> NewFloatValueRecorder(
 124       nostd::string_view name,
 125       nostd::string_view description,
 126       nostd::string_view unit,
 127       const bool enabled) = 0;
 128
 129   virtual nostd::shared_ptr<ValueRecorder<double>> NewDoubleValueRecorder(
 130       nostd::string_view name,
 131       nostd::string_view description,
 132       nostd::string_view unit,
 133       const bool enabled) = 0;
 134
 135   /**
 136    * Creates a SumObserver with the passed characteristics and returns a shared_ptr to that
 137    * SumObserver.
 138    *
 139    * @param name the name of the new SumObserver.
 140    * @param description a brief description of what the SumObserver is used for.
 141    * @param unit the unit of metric values following https://unitsofmeasure.org/ucum.html.
 142    * @param enabled a boolean value that turns on or off the metric instrument.
 143    * @param callback the function to be observed by the instrument.
 144    * @return a shared pointer to the created SumObserver.
 145    * @throws NullPointerException if {@code name} is null
 146    * @throws IllegalArgumentException if a different metric by the same name exists in this meter.
 147    * @throws IllegalArgumentException if the {@code name} does not match spec requirements.
 148    */
 149   virtual nostd::shared_ptr<SumObserver<short>> NewShortSumObserver(
 150       nostd::string_view name,
 151       nostd::string_view description,
 152       nostd::string_view unit,
 153       const bool enabled,
 154       void (*callback)(ObserverResult<short>)) = 0;
 155
 156   virtual nostd::shared_ptr<SumObserver<int>> NewIntSumObserver(
 157       nostd::string_view name,
 158       nostd::string_view description,
 159       nostd::string_view unit,
 160       const bool enabled,
 161       void (*callback)(ObserverResult<int>)) = 0;
 162
 163   virtual nostd::shared_ptr<SumObserver<float>> NewFloatSumObserver(
 164       nostd::string_view name,
 165       nostd::string_view description,
 166       nostd::string_view unit,
 167       const bool enabled,
 168       void (*callback)(ObserverResult<float>)) = 0;
 169
 170   virtual nostd::shared_ptr<SumObserver<double>> NewDoubleSumObserver(
 171       nostd::string_view name,
 172       nostd::string_view description,
 173       nostd::string_view unit,
 174       const bool enabled,
 175       void (*callback)(ObserverResult<double>)) = 0;
 176
 177   /**
 178    * Creates an UpDownSumObserver with the passed characteristics and returns a shared_ptr to
 179    * that UpDowNSumObserver.
 180    *
 181    * @param name the name of the new UpDownSumObserver.
 182    * @param description a brief description of what the UpDownSumObserver is used for.
 183    * @param unit the unit of metric values following https://unitsofmeasure.org/ucum.html.
 184    * @param enabled a boolean value that turns on or off the metric instrument.
 185    * @param callback the function to be observed by the instrument.
 186    * @return a shared pointer to the created UpDownSumObserver.
 187    * @throws NullPointerException if {@code name} is null
 188    * @throws IllegalArgumentException if a different metric by the same name exists in this meter.
 189    * @throws IllegalArgumentException if the {@code name} does not match spec requirements.
 190    */
 191   virtual nostd::shared_ptr<UpDownSumObserver<short>> NewShortUpDownSumObserver(
 192       nostd::string_view name,
 193       nostd::string_view description,
 194       nostd::string_view unit,
 195       const bool enabled,
 196       void (*callback)(ObserverResult<short>)) = 0;
 197
 198   virtual nostd::shared_ptr<UpDownSumObserver<int>> NewIntUpDownSumObserver(
 199       nostd::string_view name,
 200       nostd::string_view description,
 201       nostd::string_view unit,
 202       const bool enabled,
 203       void (*callback)(ObserverResult<int>)) = 0;
 204
 205   virtual nostd::shared_ptr<UpDownSumObserver<float>> NewFloatUpDownSumObserver(
 206       nostd::string_view name,
 207       nostd::string_view description,
 208       nostd::string_view unit,
 209       const bool enabled,
 210       void (*callback)(ObserverResult<float>)) = 0;
 211
 212   virtual nostd::shared_ptr<UpDownSumObserver<double>> NewDoubleUpDownSumObserver(
 213       nostd::string_view name,
 214       nostd::string_view description,
 215       nostd::string_view unit,
 216       const bool enabled,
 217       void (*callback)(ObserverResult<double>)) = 0;
 218
 219   /**
 220    * Creates a ValueObserver with the passed characteristics and returns a shared_ptr to that
 221    * ValueObserver.
 222    *
 223    * @param name the name of the new ValueObserver.
 224    * @param description a brief description of what the ValueObserver is used for.
 225    * @param unit the unit of metric values following https://unitsofmeasure.org/ucum.html.
 226    * @param enabled a boolean value that turns on or off the metric instrument.
 227    * @param callback the function to be observed by the instrument.
 228    * @return a shared pointer to the created ValueObserver.
 229    * @throws NullPointerException if {@code name} is null
 230    * @throws IllegalArgumentException if a different metric by the same name exists in this meter.
 231    * @throws IllegalArgumentException if the {@code name} does not match spec requirements.
 232    */
 233   virtual nostd::shared_ptr<ValueObserver<short>> NewShortValueObserver(
 234       nostd::string_view name,
 235       nostd::string_view description,
 236       nostd::string_view unit,
 237       const bool enabled,
 238       void (*callback)(ObserverResult<short>)) = 0;
 239
 240   virtual nostd::shared_ptr<ValueObserver<int>> NewIntValueObserver(
 241       nostd::string_view name,
 242       nostd::string_view description,
 243       nostd::string_view unit,
 244       const bool enabled,
 245       void (*callback)(ObserverResult<int>)) = 0;
 246
 247   virtual nostd::shared_ptr<ValueObserver<float>> NewFloatValueObserver(
 248       nostd::string_view name,
 249       nostd::string_view description,
 250       nostd::string_view unit,
 251       const bool enabled,
 252       void (*callback)(ObserverResult<float>)) = 0;
 253
 254   virtual nostd::shared_ptr<ValueObserver<double>> NewDoubleValueObserver(
 255       nostd::string_view name,
 256       nostd::string_view description,
 257       nostd::string_view unit,
 258       const bool enabled,
 259       void (*callback)(ObserverResult<double>)) = 0;
 260
 261   /**
 262    * Utility method that allows users to atomically record measurements to a set of
 263    * synchronous metric instruments with a common set of labels.
 264    *
 265    * @param labels the set of labels to associate with this recorder.
 266    * @param instruments a span of pointers to the instruments to record to.
 267    * @param values a span of values to record to the instruments in the corresponding
 268    * position in the instruments span.
 269    */
 270   virtual void RecordShortBatch(const common::KeyValueIterable &labels,
 271                                 nostd::span<SynchronousInstrument<short> *> instruments,
 272                                 nostd::span<const short> values) noexcept = 0;
 273
 274   virtual void RecordIntBatch(const common::KeyValueIterable &labels,
 275                               nostd::span<SynchronousInstrument<int> *> instruments,
 276                               nostd::span<const int> values) noexcept = 0;
 277
 278   virtual void RecordFloatBatch(const common::KeyValueIterable &labels,
 279                                 nostd::span<SynchronousInstrument<float> *> instruments,
 280                                 nostd::span<const float> values) noexcept = 0;
 281
 282   virtual void RecordDoubleBatch(const common::KeyValueIterable &labels,
 283                                  nostd::span<SynchronousInstrument<double> *> instruments,
 284                                  nostd::span<const double> values) noexcept = 0;
 285 };
 286 }  // namespace metrics
 287 OPENTELEMETRY_END_NAMESPACE
 288 #endif