Merge branch 'main' of github.com:open-telemetry/opentelemetry-ruby i…

…nto issues-1783 * 'main' of github.com:open-telemetry/opentelemetry-ruby: release: Release 3 gems (open-telemetry#1791) docs: add documentation for Metrics API instruments (open-telemetry#1720) docs: use link-inspector (open-telemetry#1790) feat: Gauge metrics exporter encoding (open-telemetry#1780)
garoazinha · Jan 15, 2025 · 0c47cd2 · 0c47cd2
2 parents cb2df41 + baeda39
commit 0c47cd2
Show file tree

Hide file tree

Showing 14 changed files with 150 additions and 24 deletions.
diff --git a/.github/workflows/ci-markdown-link.yml b/.github/workflows/ci-markdown-link.yml
@@ -2,16 +2,19 @@ name: Markdown Link Check
 
 on:
   pull_request:
+    paths:
+      - '**/*.md'
 
 jobs:
   markdown-link-check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: "Markdown Link Check"
-        uses: gaurav-nelson/github-action-markdown-link-check@v1
+      # equivalent cli: linkspector check
+      - name: Run linkspector
+        uses: umbrelladocs/action-linkspector@v1
         with:
-          config-file: '.markdown-link-check.json'
-          use-quiet-mode: 'yes'
-          use-verbose-mode: 'yes'
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          reporter: github-pr-review
+          fail_on_error: true
diff --git a/.markdown-link-check.json b/.markdown-link-check.json
diff --git a/exporter/otlp-metrics/CHANGELOG.md b/exporter/otlp-metrics/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Release History: opentelemetry-exporter-otlp-metrics
 
+### v0.3.0 / 2025-01-08
+
+* ADDED: Gauge metrics exporter encoding
+
 ### v0.2.1 / 2024-12-04
 
 * FIXED: Handle float value in NumberDataPoint

diff --git a/exporter/otlp-metrics/lib/opentelemetry/exporter/otlp/metrics/metrics_exporter.rb b/exporter/otlp-metrics/lib/opentelemetry/exporter/otlp/metrics/metrics_exporter.rb
@@ -214,18 +214,17 @@ def encode(metrics_data)
           end
 
           # metrics_pb has following type of data: :gauge, :sum, :histogram, :exponential_histogram, :summary
-          # current metric sdk only implements instrument: :counter -> :sum, :histogram -> :histogram
+          # current metric sdk only implements instrument: :counter -> :sum, :histogram -> :histogram, :gauge -> :gauge
           #
           # metrics [MetricData]
           def as_otlp_metrics(metrics)
             case metrics.instrument_kind
-            when :observable_gauge
+            when :observable_gauge, :gauge
               Opentelemetry::Proto::Metrics::V1::Metric.new(
                 name: metrics.name,
                 description: metrics.description,
                 unit: metrics.unit,
                 gauge: Opentelemetry::Proto::Metrics::V1::Gauge.new(
-                  aggregation_temporality: as_otlp_aggregation_temporality(metrics.aggregation_temporality),
                   data_points: metrics.data_points.map do |ndp|
                     number_data_point(ndp)
                   end

diff --git a/exporter/otlp-metrics/lib/opentelemetry/exporter/otlp/metrics/version.rb b/exporter/otlp-metrics/lib/opentelemetry/exporter/otlp/metrics/version.rb
@@ -9,7 +9,7 @@ module Exporter
     module OTLP
       module Metrics
         ## Current OpenTelemetry OTLP exporter version
-        VERSION = '0.2.1'
+        VERSION = '0.3.0'
       end
     end
   end

diff --git a/exporter/otlp-metrics/opentelemetry-exporter-otlp-metrics.gemspec b/exporter/otlp-metrics/opentelemetry-exporter-otlp-metrics.gemspec
@@ -29,8 +29,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'google-protobuf', '>= 3.18', '< 5.0'
   spec.add_dependency 'opentelemetry-api', '~> 1.1'
   spec.add_dependency 'opentelemetry-common', '~> 0.20'
-  spec.add_dependency 'opentelemetry-metrics-api', '~> 0.1'
-  spec.add_dependency 'opentelemetry-metrics-sdk', '~> 0.2'
+  spec.add_dependency 'opentelemetry-metrics-api', '~> 0.2'
+  spec.add_dependency 'opentelemetry-metrics-sdk', '~> 0.5'
   spec.add_dependency 'opentelemetry-sdk', '~> 1.2'
   spec.add_dependency 'opentelemetry-semantic_conventions'
 

diff --git a/exporter/otlp-metrics/test/opentelemetry/exporter/otlp/metrics/metrics_exporter_test.rb b/exporter/otlp-metrics/test/opentelemetry/exporter/otlp/metrics/metrics_exporter_test.rb
@@ -576,11 +576,16 @@
       stub_request(:post, 'http://localhost:4318/v1/metrics').to_return(status: 200)
       meter_provider.add_metric_reader(exporter)
       meter   = meter_provider.meter('test')
+
       counter = meter.create_counter('test_counter', unit: 'smidgen', description: 'a small amount of something')
       counter.add(5, attributes: { 'foo' => 'bar' })
 
       histogram = meter.create_histogram('test_histogram', unit: 'smidgen', description: 'a small amount of something')
       histogram.record(10, attributes: { 'oof' => 'rab' })
+
+      gauge = meter.create_gauge('test_gauge', unit: 'smidgen', description: 'a small amount of something')
+      gauge.record(15, attributes: { 'baz' => 'qux' })
+
       exporter.pull
       meter_provider.shutdown
 
@@ -644,6 +649,24 @@
                         ],
                         aggregation_temporality: Opentelemetry::Proto::Metrics::V1::AggregationTemporality::AGGREGATION_TEMPORALITY_DELTA
                       )
+                    ),
+                    Opentelemetry::Proto::Metrics::V1::Metric.new(
+                      name: 'test_gauge',
+                      description: 'a small amount of something',
+                      unit: 'smidgen',
+                      gauge: Opentelemetry::Proto::Metrics::V1::Gauge.new(
+                        data_points: [
+                          Opentelemetry::Proto::Metrics::V1::NumberDataPoint.new(
+                            attributes: [
+                              Opentelemetry::Proto::Common::V1::KeyValue.new(key: 'baz', value: Opentelemetry::Proto::Common::V1::AnyValue.new(string_value: 'qux'))
+                            ],
+                            as_int: 15,
+                            start_time_unix_nano: 1_699_593_427_329_946_585,
+                            time_unix_nano: 1_699_593_427_329_946_586,
+                            exemplars: nil
+                          )
+                        ]
+                      )
                     )
                   ]
                 )

diff --git a/exporter/otlp-metrics/test/test_helper.rb b/exporter/otlp-metrics/test/test_helper.rb
@@ -26,6 +26,7 @@ def collect(start_time, end_time, data_points)
 
 OpenTelemetry::SDK::Metrics::Aggregation::Sum.prepend(MockSum)
 OpenTelemetry::SDK::Metrics::Aggregation::ExplicitBucketHistogram.prepend(MockSum)
+OpenTelemetry::SDK::Metrics::Aggregation::LastValue.prepend(MockSum)
 
 def create_metrics_data(name: '', description: '', unit: '', instrument_kind: :counter, resource: nil,
                         instrumentation_scope: OpenTelemetry::SDK::InstrumentationScope.new('', 'v0.0.1'),

diff --git a/metrics_api/CHANGELOG.md b/metrics_api/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

diff --git a/metrics_api/lib/opentelemetry/metrics/meter.rb b/metrics_api/lib/opentelemetry/metrics/meter.rb
@@ -30,10 +30,38 @@ def initialize
         @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
@@ -56,18 +84,87 @@ 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

diff --git a/metrics_api/lib/opentelemetry/metrics/version.rb b/metrics_api/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
diff --git a/metrics_sdk/CHANGELOG.md b/metrics_sdk/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Release History: opentelemetry-metrics-sdk
 
+### v0.5.0 / 2025-01-08
+
+* ADDED: Add synchronous gauge
+
 ### v0.4.1 / 2024-12-04
 
 * FIXED: Handle float value in NumberDataPoint

diff --git a/metrics_sdk/lib/opentelemetry/sdk/metrics/version.rb b/metrics_sdk/lib/opentelemetry/sdk/metrics/version.rb
@@ -8,7 +8,7 @@ module OpenTelemetry
   module SDK
     module Metrics
       # Current OpenTelemetry metrics sdk version
-      VERSION = '0.4.1'
+      VERSION = '0.5.0'
     end
   end
 end
diff --git a/metrics_sdk/opentelemetry-metrics-sdk.gemspec b/metrics_sdk/opentelemetry-metrics-sdk.gemspec
@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.0'
 
   spec.add_dependency 'opentelemetry-api', '~> 1.1'
-  spec.add_dependency 'opentelemetry-metrics-api', '~> 0.1.1'
+  spec.add_dependency 'opentelemetry-metrics-api', '~> 0.2'
   spec.add_dependency 'opentelemetry-sdk', '~> 1.2'
 
   spec.add_development_dependency 'benchmark-ipsa', '~> 0.2.0'