opentelemetry-metrics-api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e083b923d5961c60a77e23cec51451171a627cdebaad0aad91c64dedb6f940e4
-  data.tar.gz: 7ec8d56f0f9fcc2db01d173d755351f7d3365632070861ac1d5f920613f7c77e
+  metadata.gz: aee00375b1af8d663e0b22a4a28301bd0c57539cfee2285cca68892225d33478
+  data.tar.gz: ab779b3f63f322226096b7e1cd81914943cc4b4f71bc39560e9c07638294b5d4
 SHA512:
-  metadata.gz: 1fe0235ce6aa725df40a48324dfedc6ccc4735bc250b90909964d6bc8d9af0c5c5586fbb174871ba292b2dac78f6971f7881dc6016d55dc5029dc7c0f8b74268
-  data.tar.gz: 6c7460fb94836f0754b9b7ba6f64a807f6477c4715518ae803db9b89da8618b549f140422f6e9749c33ac505c616419356b10fc091bc560e00654a4d6905e40c
+  metadata.gz: fc11b02c19b8b58e531b0eb725bd3d143d70a3d760ed0aefa43186be948f1017fac4318f66a9d9ac8a567f5943e4d7d35123fd13cf65d755b224a8e3fda3724d
+  data.tar.gz: 7740bb55aa66982a5b7c7545964692a1d9e7d24b6b1251d9ecdad9c3478347b19585bac87510ec107206251406c1f12f558fec2e33a0b029bf8cfec5891c7667

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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
+
 ### v0.1.0 / 2024-07-31
 
 Initial release.

data/README.md

@@ -12,7 +12,11 @@ OpenTelemetry provides a single set of APIs, libraries, agents, and collector se
 
 The `opentelemetry-metrics-api` gem defines the core OpenTelemetry interfaces in the form of abstract classes and no-op implementations. That is, it defines interfaces and data types sufficient for a library or application to code against to produce telemetry data, but does not actually collect, analyze, or export the data.
 
-To collect and analyze telemetry data, _applications_ should also install a concrete implementation of the API, such as the `opentelemetry-metrics-sdk` gem. However, _libraries_ that produce telemetry data should depend only on `opentelemetry-metrics-api`, deferring the choise of concrete implementation to the application developer.
+To collect and analyze telemetry data, _applications_ should also
+install a concrete implementation of the API, such as the
+`opentelemetry-metrics-sdk` gem. However, _libraries_ that produce
+telemetry data should depend only on `opentelemetry-metrics-api`,
+deferring the choice of concrete implementation to the application developer.
 
 This code is still under development and is not a complete implementation of the Metrics API. Until the code becomes stable, Metrics API functionality will live outside the `opentelemetry-api` library.
 
@@ -20,7 +24,7 @@ This code is still under development and is not a complete implementation of the
 
 Install the gem using:
 
-```
+```sh
 gem install opentelemetry-metrics-api
 ```
 

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/counter.rb

@@ -16,7 +16,7 @@ module OpenTelemetry
         #   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 add(increment, attributes: nil); end
+        def add(increment, attributes: {}); end
       end
     end
   end

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/histogram.rb

@@ -16,7 +16,7 @@ module OpenTelemetry
         #   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: nil); end
+        def record(amount, attributes: {}); end
       end
     end
   end

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

@@ -16,7 +16,7 @@ module OpenTelemetry
         #   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 add(amount, attributes: nil); end
+        def add(amount, attributes: {}); 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,13 +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
 
       NAME_REGEX = /\A[a-zA-Z][-.\w]{0,62}\z/
 
-      private_constant(:COUNTER, :OBSERVABLE_COUNTER, :HISTOGRAM, :OBSERVABLE_GAUGE, :UP_DOWN_COUNTER, :OBSERVABLE_UP_DOWN_COUNTER)
+      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)
@@ -29,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
@@ -56,23 +172,12 @@ module OpenTelemetry
       private
 
       def create_instrument(kind, name, unit, description, callback)
-        raise InstrumentNameError if name.nil?
-        raise InstrumentNameError if name.empty?
-        raise InstrumentNameError unless NAME_REGEX.match?(name)
-        raise InstrumentUnitError if unit && (!unit.ascii_only? || unit.size > 63)
-        raise InstrumentDescriptionError if description && (description.size > 1023 || !utf8mb3_encoding?(description.dup))
-
         @mutex.synchronize do
           OpenTelemetry.logger.warn("duplicate instrument registration occurred for instrument #{name}") if @instrument_registry.include? name
 
           @instrument_registry[name] = yield
         end
       end
-
-      def utf8mb3_encoding?(string)
-        string.force_encoding('UTF-8').valid_encoding? &&
-          string.each_char { |c| return false if c.bytesize >= 4 }
-      end
     end
   end
 end

data/lib/opentelemetry/metrics/version.rb

@@ -7,6 +7,6 @@
 module OpenTelemetry
   module Metrics
     ## Current OpenTelemetry metrics version
-    VERSION = '0.1.0'
+    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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-31 00:00:00.000000000 Z
+date: 2025-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -114,14 +114,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.51.0
+        version: '1.65'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.51.0
+        version: '1.65'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -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.0/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.0
-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: []