opentelemetry-metrics-api 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6232b4090e467e0d9f7933342d5a1a9634a41186222306214d889b5c211af55c
-  data.tar.gz: 6e52fe54891237e36ef39fcd29ef035772051f1a54e18b67270369af8a06f352
+  metadata.gz: aee00375b1af8d663e0b22a4a28301bd0c57539cfee2285cca68892225d33478
+  data.tar.gz: ab779b3f63f322226096b7e1cd81914943cc4b4f71bc39560e9c07638294b5d4
 SHA512:
-  metadata.gz: cf96e7239ee84437c1b4389b763b3f80f7882c8d9e29b2db94f7bd0bb9c1cfbd8475a0cb75712e8c916833a3cc184c4028f95996905dd3d2fddec13a8999d9a3
-  data.tar.gz: 6d048b7a1622e36a791cf5e64f104f8a75faa3a9248495bd528ad7089fa6f2d685aa5f9f52026e92366b11aa4faefabe5f18cde5262d35df39fbc7f98092c5ca
+  metadata.gz: fc11b02c19b8b58e531b0eb725bd3d143d70a3d760ed0aefa43186be948f1017fac4318f66a9d9ac8a567f5943e4d7d35123fd13cf65d755b224a8e3fda3724d
+  data.tar.gz: 7740bb55aa66982a5b7c7545964692a1d9e7d24b6b1251d9ecdad9c3478347b19585bac87510ec107206251406c1f12f558fec2e33a0b029bf8cfec5891c7667

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History: opentelemetry-metrics-api
 
+### v0.2.0 / 2025-01-08
+
+* ADDED: Add synchronous gauge
+* DOCS: Add documentation for Metrics API instruments
+
 ### v0.1.1 / 2024-10-22
 
 * FIXED: Refactor instrument validation

data/lib/opentelemetry/internal/proxy_instrument.rb

@@ -19,7 +19,7 @@ module OpenTelemetry
 
       def upgrade_with(meter)
         @delegate = case @kind
-                    when :counter, :histogram, :up_down_counter
+                    when :counter, :histogram, :up_down_counter, :gauge
                       meter.send("create_#{@kind}", @name, unit: @unit, description: @desc)
                     when :observable_counter, :observable_gauge, :observable_up_down_counter
                       meter.send("create_#{@kind}", @name, unit: @unit, description: @desc, callback: @callback)

data/lib/opentelemetry/internal/proxy_meter.rb

@@ -45,6 +45,7 @@ module OpenTelemetry
           case kind
           when :counter then @delegate.create_counter(name, unit: unit, description: description)
           when :histogram then @delegate.create_histogram(name, unit: unit, description: description)
+          when :gauge then @delegate.create_gauge(name, unit: unit, description: description)
           when :up_down_counter then @delegate.create_up_down_counter(name, unit: unit, description: description)
           when :observable_counter then @delegate.create_observable_counter(name, unit: unit, description: description, callback: callback)
           when :observable_gauge then @delegate.create_observable_gauge(name, unit: unit, description: description, callback: callback)

data/lib/opentelemetry/metrics/instrument/gauge.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Metrics
+    module Instrument
+      # No-op implementation of Gauge.
+      class Gauge
+        # Record the current value for the Gauge
+        #
+        # @param [Numeric] amount The current absolute value.
+        # @param [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes
+        #   Values must be non-nil and (array of) string, boolean or numeric type.
+        #   Array values must not contain nil elements and all elements must be of
+        #   the same basic type (string, numeric, boolean).
+        def record(amount, attributes: {}); end
+      end
+    end
+  end
+end

data/lib/opentelemetry/metrics/instrument.rb

@@ -6,6 +6,7 @@
 
 require 'opentelemetry/metrics/instrument/counter'
 require 'opentelemetry/metrics/instrument/histogram'
+require 'opentelemetry/metrics/instrument/gauge'
 require 'opentelemetry/metrics/instrument/observable_counter'
 require 'opentelemetry/metrics/instrument/observable_gauge'
 require 'opentelemetry/metrics/instrument/observable_up_down_counter'

data/lib/opentelemetry/metrics/meter.rb

@@ -11,11 +11,14 @@ module OpenTelemetry
       COUNTER = Instrument::Counter.new
       OBSERVABLE_COUNTER = Instrument::ObservableCounter.new
       HISTOGRAM = Instrument::Histogram.new
+      GAUGE = Instrument::Gauge.new
       OBSERVABLE_GAUGE = Instrument::ObservableGauge.new
       UP_DOWN_COUNTER = Instrument::UpDownCounter.new
       OBSERVABLE_UP_DOWN_COUNTER = Instrument::ObservableUpDownCounter.new
 
-      private_constant(:COUNTER, :OBSERVABLE_COUNTER, :HISTOGRAM, :OBSERVABLE_GAUGE, :UP_DOWN_COUNTER, :OBSERVABLE_UP_DOWN_COUNTER)
+      NAME_REGEX = /\A[a-zA-Z][-.\w]{0,62}\z/
+
+      private_constant(:COUNTER, :OBSERVABLE_COUNTER, :HISTOGRAM, :GAUGE, :OBSERVABLE_GAUGE, :UP_DOWN_COUNTER, :OBSERVABLE_UP_DOWN_COUNTER)
 
       DuplicateInstrumentError = Class.new(OpenTelemetry::Error)
       InstrumentNameError = Class.new(OpenTelemetry::Error)
@@ -27,26 +30,141 @@ module OpenTelemetry
         @instrument_registry = {}
       end
 
+      # {https://opentelemetry.io/docs/specs/otel/metrics/api/#counter 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')
+      #
+      # @param name [String] the name of the counter
+      # @param unit [optional String] an optional string provided by user.
+      # @param description [optional String] an optional free-form text provided by user.
+      #
+      # @return [nil] after creation of counter, it will be stored in instrument_registry
       def create_counter(name, unit: nil, description: nil)
         create_instrument(:counter, name, unit, description, nil) { COUNTER }
       end
 
+      # 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")
+      #
+      # @param name [String] the name of the histogram
+      # @param unit [optional String] an optional string provided by user.
+      # @param description [optional String] an optional free-form text provided by user.
+      #
+      # @return [nil] after creation of histogram, it will be stored in instrument_registry
       def create_histogram(name, unit: nil, description: nil)
         create_instrument(:histogram, name, unit, description, nil) { HISTOGRAM }
       end
 
+      # 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")
+      #
+      #
+      # @param name [String] the name of the gauge.
+      # @param unit [optional String] an optional string provided by user.
+      # @param description [optional String] an optional free-form text provided by user.
+      #
+      # @return [nil] after creation of gauge, it will be stored in instrument_registry
+      def create_gauge(name, unit: nil, description: nil)
+        create_instrument(:gauge, name, unit, description, nil) { GAUGE }
+      end
+
+      # 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")
+      #
+      # @param name [String] the name of the up_down_counter
+      # @param unit [optional String] an optional string provided by user.
+      # @param description [optional String] an optional free-form text provided by user.
+      #
+      # @return [nil] after creation of up_down_counter, it will be stored in instrument_registry
       def create_up_down_counter(name, unit: nil, description: nil)
         create_instrument(:up_down_counter, name, unit, description, nil) { UP_DOWN_COUNTER }
       end
 
+      # 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')
+      #
+      #
+      # @param name [String] the name of the observable_counter
+      # @param callback [Proc] the callback function that used to collect metrics
+      # @param unit [optional String] an optional string provided by user.
+      # @param description [optional String] an optional free-form text provided by user.
+      #
+      # @return [nil] after creation of observable_counter, it will be stored in instrument_registry
       def create_observable_counter(name, callback:, unit: nil, description: nil)
         create_instrument(:observable_counter, name, unit, description, callback) { OBSERVABLE_COUNTER }
       end
 
+      # 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_counter("cpu.frequency",
+      #                                    pf_callback,
+      #                                    description: "the real-time CPU clock speed",
+      #                                    unit: 'ms')
+      #
+      #
+      # @param name [String] the name of the observable_gauge
+      # @param callback [Proc] the callback function that used to collect metrics
+      # @param unit [optional String] an optional string provided by user.
+      # @param description [optional String] an optional free-form text provided by user.
+      #
+      # @return [nil] after creation of observable_gauge, it will be stored in instrument_registry
       def create_observable_gauge(name, callback:, unit: nil, description: nil)
         create_instrument(:observable_gauge, name, unit, description, callback) { OBSERVABLE_GAUGE }
       end
 
+      # 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')
+      #
+      #
+      # @param name [String] the name of the observable_up_down_counter
+      # @param callback [Proc] the callback function that used to collect metrics
+      # @param unit [optional String] an optional string provided by user.
+      # @param description [optional String] an optional free-form text provided by user.
+      #
+      # @return [nil] after creation of observable_up_down_counter, it will be stored in instrument_registry
       def create_observable_up_down_counter(name, callback:, unit: nil, description: nil)
         create_instrument(:observable_up_down_counter, name, unit, description, callback) { OBSERVABLE_UP_DOWN_COUNTER }
       end

data/lib/opentelemetry/metrics/version.rb

@@ -7,6 +7,6 @@
 module OpenTelemetry
   module Metrics
     ## Current OpenTelemetry metrics version
-    VERSION = '0.1.1'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-metrics-api
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-22 00:00:00.000000000 Z
+date: 2025-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -164,7 +164,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.6
-description: 
+description:
 email:
 - cncf-opentelemetry-contributors@lists.cncf.io
 executables: []
@@ -182,6 +182,7 @@ files:
 - lib/opentelemetry/metrics.rb
 - lib/opentelemetry/metrics/instrument.rb
 - lib/opentelemetry/metrics/instrument/counter.rb
+- lib/opentelemetry/metrics/instrument/gauge.rb
 - lib/opentelemetry/metrics/instrument/histogram.rb
 - lib/opentelemetry/metrics/instrument/observable_counter.rb
 - lib/opentelemetry/metrics/instrument/observable_gauge.rb
@@ -195,11 +196,11 @@ homepage: https://github.com/open-telemetry/opentelemetry-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-api/v0.1.1/file.CHANGELOG.html
+  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-api/v0.2.0/file.CHANGELOG.html
   source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/metrics_api
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
-  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-api/v0.1.1
-post_install_message: 
+  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-api/v0.2.0
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -215,7 +216,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.2.33
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A stats collection and distributed tracing framework
 test_files: []