Class: OpenTelemetry::Metrics::Meter

Inherits:
Object
  • Object
show all
Defined in:
lib/opentelemetry/metrics/meter.rb

Overview

No-op implementation of Meter.

Direct Known Subclasses

Internal::ProxyMeter

Constant Summary collapse

NAME_REGEX =
%r{\A[a-zA-Z][-./\w]{0,254}\z}
DuplicateInstrumentError =

rubocop:disable Style/EmptyClassDefinition

Class.new(OpenTelemetry::Error)
InstrumentNameError =
Class.new(OpenTelemetry::Error)
InstrumentUnitError =
Class.new(OpenTelemetry::Error)
InstrumentDescriptionError =
Class.new(OpenTelemetry::Error)

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Meter

rubocop:enable Style/EmptyClassDefinition



30
31
32
33
# File 'lib/opentelemetry/metrics/meter.rb', line 30

def initialize
  @mutex = Mutex.new
  @instrument_registry = {}
end

Instance Method Details

#create_counter(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil) ⇒ nil

Counter is a synchronous Instrument which supports non-negative increments.

With this api call:

exception_counter = meter.create_counter("exceptions",
                                       description: "number of exceptions caught",
                                       unit: 's',
                                       exemplar_filter: OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter,
                                       exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)

Parameters:

  • name (String) —

    the name of the counter

  • unit (optional String) (defaults to: nil) —

    an optional string provided by user.

  • description (optional String) (defaults to: nil) —

    an optional free-form text provided by user.

  • exemplar_filter (optional Object) (defaults to: nil) —

    an optional filter to control which measurements are eligible to become exemplars. Must respond to #should_sample?. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOnExemplarFilter - all measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOffExemplarFilter - no measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter - only measurements in a sampled span context are eligible
  • exemplar_reservoir (optional Object) (defaults to: nil) —

    an optional reservoir used to sample exemplars from eligible measurements. Must respond to #offer and #collect. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir - uniformly-weighted sampling
    • OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir - one exemplar per histogram bucket (recommended for histograms)
    • OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir - no-op, disables exemplar collection
  • advisory (optional Hash) (defaults to: nil) —

    optional advisory parameters: recommendations from the instrument author that implementations MAY ignore. The API does not validate them. @option advisory [Array] :attributes Recommended set of attribute keys for the resulting metrics. @option advisory [Array] :explicit_bucket_boundaries Applies to histograms only and has no effect here.

Returns:

  • (nil) —

    after creation of counter, it will be stored in instrument_registry



64
65
66
# File 'lib/opentelemetry/metrics/meter.rb', line 64

def create_counter(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
  create_instrument(:counter, name, unit, description, nil, exemplar_filter, exemplar_reservoir, advisory) { COUNTER }
end

#create_gauge(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil) ⇒ nil

Gauge is an synchronous Instrument which reports non-additive value(s)

With this api call:

meter.create_gauge("cpu.frequency",
                  description: "the real-time CPU clock speed",
                  unit: "ms",
                  exemplar_filter: OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter,
                  exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)

Parameters:

  • name (String) —

    the name of the gauge.

  • unit (optional String) (defaults to: nil) —

    an optional string provided by user.

  • description (optional String) (defaults to: nil) —

    an optional free-form text provided by user.

  • exemplar_filter (optional Object) (defaults to: nil) —

    an optional filter to control which measurements are eligible to become exemplars. Must respond to #should_sample?. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOnExemplarFilter - all measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOffExemplarFilter - no measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter - only measurements in a sampled span context are eligible
  • exemplar_reservoir (optional Object) (defaults to: nil) —

    an optional reservoir used to sample exemplars from eligible measurements. Must respond to #offer and #collect. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir - uniformly-weighted sampling
    • OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir - one exemplar per histogram bucket (recommended for histograms)
    • OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir - no-op, disables exemplar collection
  • advisory (optional Hash) (defaults to: nil) —

    optional advisory parameters: recommendations from the instrument author that implementations MAY ignore. The API does not validate them. @option advisory [Array] :attributes Recommended set of attribute keys for the resulting metrics. @option advisory [Array] :explicit_bucket_boundaries Applies to histograms only and has no effect here.

Returns:

  • (nil) —

    after creation of gauge, it will be stored in instrument_registry



133
134
135
# File 'lib/opentelemetry/metrics/meter.rb', line 133

def create_gauge(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
  create_instrument(:gauge, name, unit, description, nil, exemplar_filter, exemplar_reservoir, advisory) { GAUGE }
end

#create_histogram(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil) ⇒ nil

Histogram is a synchronous Instrument which can be used to report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentiles.

With this api call:

http_server_duration = meter.create_histogram("http.server.duration",
                                            description: "measures the duration of the inbound HTTP request",
                                            unit: "s",
                                            exemplar_filter: OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter,
                                            exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir.new)

Parameters:

  • name (String) —

    the name of the histogram

  • unit (optional String) (defaults to: nil) —

    an optional string provided by user.

  • description (optional String) (defaults to: nil) —

    an optional free-form text provided by user.

  • exemplar_filter (optional Object) (defaults to: nil) —

    an optional filter to control which measurements are eligible to become exemplars. Must respond to #should_sample?. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOnExemplarFilter - all measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOffExemplarFilter - no measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter - only measurements in a sampled span context are eligible
  • exemplar_reservoir (optional Object) (defaults to: nil) —

    an optional reservoir used to sample exemplars from eligible measurements. Must respond to #offer and #collect. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir - uniformly-weighted sampling
    • OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir - one exemplar per histogram bucket (recommended for histograms)
    • OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir - no-op, disables exemplar collection
  • advisory (optional Hash) (defaults to: nil) —

    optional advisory parameters: recommendations from the instrument author that implementations MAY ignore. The API does not validate them. @option advisory [Array] :explicit_bucket_boundaries Recommended bucket boundaries when this instrument is aggregated to an explicit bucket histogram. @option advisory [Array] :attributes Recommended set of attribute keys for the resulting metrics.

Returns:

  • (nil) —

    after creation of histogram, it will be stored in instrument_registry



100
101
102
# File 'lib/opentelemetry/metrics/meter.rb', line 100

def create_histogram(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
  create_instrument(:histogram, name, unit, description, nil, exemplar_filter, exemplar_reservoir, advisory) { HISTOGRAM }
end

#create_observable_counter(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil) ⇒ nil

ObservableCounter is an asynchronous Instrument which reports monotonically increasing value(s) when the instrument is being observed.

With this api call:

pf_callback = -> { # collect metrics here }
meter.create_observable_counter("PF",
                               pf_callback,
                               description: "process page faults",
                               unit: 'ms',
                               exemplar_filter: OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter,
                               exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)

Parameters:

  • name (String) —

    the name of the observable_counter

  • callback (optional Proc, Array<Proc>) (defaults to: nil) —

    zero or more callback functions used to collect metrics

  • unit (optional String) (defaults to: nil) —

    an optional string provided by user.

  • description (optional String) (defaults to: nil) —

    an optional free-form text provided by user.

  • exemplar_filter (optional Object) (defaults to: nil) —

    an optional filter to control which measurements are eligible to become exemplars. Must respond to #should_sample?. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOnExemplarFilter - all measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOffExemplarFilter - no measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter - only measurements in a sampled span context are eligible
  • exemplar_reservoir (optional Object) (defaults to: nil) —

    an optional reservoir used to sample exemplars from eligible measurements. Must respond to #offer and #collect. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir - uniformly-weighted sampling
    • OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir - one exemplar per histogram bucket (recommended for histograms)
    • OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir - no-op, disables exemplar collection
  • advisory (optional Hash) (defaults to: nil) —

    optional advisory parameters: recommendations from the instrument author that implementations MAY ignore. The API does not validate them. @option advisory [Array] :attributes Recommended set of attribute keys for the resulting metrics. @option advisory [Array] :explicit_bucket_boundaries Applies to histograms only and has no effect here.

Returns:

  • (nil) —

    after creation of observable_counter, it will be stored in instrument_registry



203
204
205
# File 'lib/opentelemetry/metrics/meter.rb', line 203

def create_observable_counter(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
  create_instrument(:observable_counter, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory) { OBSERVABLE_COUNTER }
end

#create_observable_gauge(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil) ⇒ nil

ObservableGauge is an asynchronous Instrument which reports non-additive value(s) (e.g. the room temperature - it makes no sense to report the temperature value from multiple rooms and sum them up) when the instrument is being observed.

With this api call:

pf_callback = -> { # collect metrics here }
meter.create_observable_gauge("cpu.frequency",
                             pf_callback,
                             description: "the real-time CPU clock speed",
                             unit: 'ms',
                             exemplar_filter: OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter,
                             exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)

Parameters:

  • name (String) —

    the name of the observable_gauge

  • callback (optional Proc, Array<Proc>) (defaults to: nil) —

    zero or more callback functions used to collect metrics

  • unit (optional String) (defaults to: nil) —

    an optional string provided by user.

  • description (optional String) (defaults to: nil) —

    an optional free-form text provided by user.

  • exemplar_filter (optional Object) (defaults to: nil) —

    an optional filter to control which measurements are eligible to become exemplars. Must respond to #should_sample?. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOnExemplarFilter - all measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOffExemplarFilter - no measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter - only measurements in a sampled span context are eligible
  • exemplar_reservoir (optional Object) (defaults to: nil) —

    an optional reservoir used to sample exemplars from eligible measurements. Must respond to #offer and #collect. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir - uniformly-weighted sampling
    • OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir - one exemplar per histogram bucket (recommended for histograms)
    • OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir - no-op, disables exemplar collection
  • advisory (optional Hash) (defaults to: nil) —

    optional advisory parameters: recommendations from the instrument author that implementations MAY ignore. The API does not validate them. @option advisory [Array] :attributes Recommended set of attribute keys for the resulting metrics. @option advisory [Array] :explicit_bucket_boundaries Applies to histograms only and has no effect here.

Returns:

  • (nil) —

    after creation of observable_gauge, it will be stored in instrument_registry



241
242
243
# File 'lib/opentelemetry/metrics/meter.rb', line 241

def create_observable_gauge(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
  create_instrument(:observable_gauge, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory) { OBSERVABLE_GAUGE }
end

#create_observable_up_down_counter(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil) ⇒ nil

ObservableUpDownCounter is an asynchronous Instrument which reports additive value(s) (e.g. the process heap size - it makes sense to report the heap size from multiple processes and sum them up, so we get the total heap usage) when the instrument is being observed.

With this api call:

pf_callback = -> { # collect metrics here }
meter.create_observable_up_down_counter("process.workingset",
                                       pf_callback,
                                       description: "process working set",
                                       unit: 'KB',
                                       exemplar_filter: OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter,
                                       exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)

Parameters:

  • name (String) —

    the name of the observable_up_down_counter

  • callback (optional Proc, Array<Proc>) (defaults to: nil) —

    zero or more callback functions used to collect metrics

  • unit (optional String) (defaults to: nil) —

    an optional string provided by user.

  • description (optional String) (defaults to: nil) —

    an optional free-form text provided by user.

  • exemplar_filter (optional Object) (defaults to: nil) —

    an optional filter to control which measurements are eligible to become exemplars. Must respond to #should_sample?. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOnExemplarFilter - all measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOffExemplarFilter - no measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter - only measurements in a sampled span context are eligible
  • exemplar_reservoir (optional Object) (defaults to: nil) —

    an optional reservoir used to sample exemplars from eligible measurements. Must respond to #offer and #collect. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir - uniformly-weighted sampling
    • OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir - one exemplar per histogram bucket (recommended for histograms)
    • OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir - no-op, disables exemplar collection
  • advisory (optional Hash) (defaults to: nil) —

    optional advisory parameters: recommendations from the instrument author that implementations MAY ignore. The API does not validate them. @option advisory [Array] :attributes Recommended set of attribute keys for the resulting metrics. @option advisory [Array] :explicit_bucket_boundaries Applies to histograms only and has no effect here.

Returns:

  • (nil) —

    after creation of observable_up_down_counter, it will be stored in instrument_registry



279
280
281
# File 'lib/opentelemetry/metrics/meter.rb', line 279

def create_observable_up_down_counter(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
  create_instrument(:observable_up_down_counter, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory) { OBSERVABLE_UP_DOWN_COUNTER }
end

#create_up_down_counter(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil) ⇒ nil

UpDownCounter is a synchronous Instrument which supports increments and decrements.

With this api call:

items_counter = meter.create_up_down_counter("store.inventory",
                                           description: "the number of the items available",
                                           unit: "s",
                                           exemplar_filter: OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter,
                                           exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)

Parameters:

  • name (String) —

    the name of the up_down_counter

  • unit (optional String) (defaults to: nil) —

    an optional string provided by user.

  • description (optional String) (defaults to: nil) —

    an optional free-form text provided by user.

  • exemplar_filter (optional Object) (defaults to: nil) —

    an optional filter to control which measurements are eligible to become exemplars. Must respond to #should_sample?. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOnExemplarFilter - all measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOffExemplarFilter - no measurements are eligible
    • OpenTelemetry::SDK::Metrics::Exemplar::TraceBasedExemplarFilter - only measurements in a sampled span context are eligible
  • exemplar_reservoir (optional Object) (defaults to: nil) —

    an optional reservoir used to sample exemplars from eligible measurements. Must respond to #offer and #collect. Available SDK implementations:

    • OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir - uniformly-weighted sampling
    • OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir - one exemplar per histogram bucket (recommended for histograms)
    • OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir - no-op, disables exemplar collection
  • advisory (optional Hash) (defaults to: nil) —

    optional advisory parameters: recommendations from the instrument author that implementations MAY ignore. The API does not validate them. @option advisory [Array] :attributes Recommended set of attribute keys for the resulting metrics. @option advisory [Array] :explicit_bucket_boundaries Applies to histograms only and has no effect here.

Returns:

  • (nil) —

    after creation of up_down_counter, it will be stored in instrument_registry



166
167
168
# File 'lib/opentelemetry/metrics/meter.rb', line 166

def create_up_down_counter(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
  create_instrument(:up_down_counter, name, unit, description, nil, exemplar_filter, exemplar_reservoir, advisory) { UP_DOWN_COUNTER }
end

#register_callback(instruments, callback) ⇒ nil

Registers a callback function against a declared set of asynchronous instruments from this Meter.

Parameters:

  • instruments (Array) —

    the asynchronous instruments the callback function reports Measurements for

  • callback (Proc) —

    the callback function

Returns:

  • (nil)


289
290
291
# File 'lib/opentelemetry/metrics/meter.rb', line 289

def register_callback(instruments, callback)
  instruments.each { |instrument| instrument.register_callback(callback) }
end

#unregister(instruments, callback) ⇒ nil

Unregisters a callback function previously registered via #register_callback.

Parameters:

  • instruments (Array) —

    the asynchronous instruments the callback function was registered against

  • callback (Proc) —

    the callback function

Returns:

  • (nil)


299
300
301
# File 'lib/opentelemetry/metrics/meter.rb', line 299

def unregister(instruments, callback)
  instruments.each { |instrument| instrument.unregister(callback) }
end