release: metrics-sdk metrics-api (#1641)

* feat: metrics alpha release

* remove release exporter

* update one more script to run otlp metrics exporter

* docs: Add READMEs for metrics-api and metrics-sdk

* chore: Rename variable to match value

* chore: Edit text of metrics example README

* Update metrics_api/lib/opentelemetry/metrics/version.rb

Co-authored-by: Matthew Wear <[email protected]>

* Update metrics_sdk/lib/opentelemetry/sdk/metrics/version.rb

Co-authored-by: Matthew Wear <[email protected]>

---------

Co-authored-by: Kayla Reopelle <[email protected]>
Co-authored-by: Matthew Wear <[email protected]>

.toys/.data/releases.yml

@@ -84,3 +84,11 @@ gems:
     directory: test_helpers
     version_rb_path: lib/opentelemetry/test_helpers/version.rb
     version_constant: [OpenTelemetry, TestHelpers, VERSION]
+
+  - name: opentelemetry-metrics-api
+    directory: metrics_api
+    version_constant: [OpenTelemetry, Metrics, VERSION]
+
+  - name: opentelemetry-metrics-sdk
+    directory: metrics_sdk
+    version_constant: [OpenTelemetry, SDK, Metrics, VERSION]

examples/metrics_sdk/README.md

@@ -0,0 +1,75 @@
+# OpenTelemetry Ruby Metrics SDK Example
+
+### metrics_collect.rb
+
+Run the script to see the metric data from console
+
+```sh
+ruby metrics_collect.rb
+```
+
+### metrics_collect_otlp.rb
+
+**WARN: this example doesn't work on alpine aarch64 container due to grpc installation issues.**
+
+This example tests both the metrics sdk and the metrics otlp http exporter.
+
+You can view the metrics in your favored backend (e.g. jaeger).
+
+#### 1. Set up the local opentelemetry-collector.
+
+Given you have a `config.yml` file in your current directory and Docker is installed on your machine, run the following commands to pull the collector image and run the collector.
+
+```sh
+docker pull otel/opentelemetry-collector
+docker run --rm -v $(pwd)/config.yaml:/etc/otel/config.yaml -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector --config /etc/otel/config.yaml
+```
+
+Sample config.yaml
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+      http:
+      # Default endpoints: 0.0.0.0:4317 for gRPC and 0.0.0.0:4318 for HTTP
+
+exporters:
+  logging:
+    loglevel: debug
+
+processors:
+  batch:
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [logging]
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [logging]
+```
+
+More information on how to setup the OTel collector can be found in the in [quick start docs](https://opentelemetry.io/docs/collector/quick-start/).
+
+#### 2. Assign the endpoint value to your destination address
+
+```
+# Using environment variable
+ENV['OTEL_EXPORTER_OTLP_METRICS_ENDPOINT'] = 'http://host.docker.internal:4318/v1/metrics'
+
+# Or using export command
+export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://host.docker.internal:4318/v1/metrics
+```
+
+#### 3. Run the script to send metric data to OTLP collector
+
+```sh
+ruby metrics_collect_otlp.rb
+```
+
+You should see metric data appear in the collector.

examples/metrics_sdk/metrics_collect.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile(true) do
+  source 'https://rubygems.org'
+  gem "opentelemetry-api"
+  gem "opentelemetry-common"
+  gem "opentelemetry-sdk"
+
+  gem 'opentelemetry-metrics-api', path: '../../metrics_api'
+  gem 'opentelemetry-metrics-sdk', path: '../../metrics_sdk'
+end
+
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-sdk'
+
+OpenTelemetry::SDK.configure
+
+console_metric_exporter = OpenTelemetry::SDK::Metrics::Export::ConsoleMetricPullExporter.new
+
+OpenTelemetry.meter_provider.add_metric_reader(console_metric_exporter)
+
+meter = OpenTelemetry.meter_provider.meter("SAMPLE_METER_NAME")
+
+histogram = meter.create_histogram('histogram', unit: 'smidgen', description: 'desscription')
+
+histogram.record(123, attributes: {'foo' => 'bar'})
+
+OpenTelemetry.meter_provider.metric_readers.each(&:pull)
+OpenTelemetry.meter_provider.shutdown

examples/metrics_sdk/metrics_collect_otlp.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile(true) do
+  source 'https://rubygems.org'
+  gem "opentelemetry-api"
+  gem "opentelemetry-common"
+  gem "opentelemetry-sdk"
+
+  gem 'opentelemetry-metrics-api', path: '../../metrics_api'
+  gem 'opentelemetry-metrics-sdk', path: '../../metrics_sdk'
+  gem 'opentelemetry-exporter-otlp-metrics', path: '../../exporter/otlp-metrics'
+
+end
+
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-sdk'
+require 'opentelemetry-exporter-otlp-metrics'
+
+OpenTelemetry::SDK.configure
+
+otlp_metric_exporter = OpenTelemetry::Exporter::OTLP::MetricsExporter.new
+
+OpenTelemetry.meter_provider.add_metric_reader(otlp_metric_exporter)
+
+meter = OpenTelemetry.meter_provider.meter("SAMPLE_METER_NAME")
+
+histogram = meter.create_histogram('histogram', unit: 'smidgen', description: 'desscription')
+
+histogram.record(123, attributes: {'foo' => 'bar'})
+
+OpenTelemetry.meter_provider.metric_readers.each(&:pull)
+OpenTelemetry.meter_provider.shutdown

metrics_api/README.md

@@ -0,0 +1,69 @@
+# opentelemetry-metrics-api
+
+The `opentelemetry-metrics-api` gem is an alpha implementation of the [OpenTelemetry Metrics API][metrics-api] for Ruby applications. Using `opentelemetry-metrics-api`, a library or application can code against the OpenTelemetry interfaces to produce metric data.
+
+## What is OpenTelemetry?
+
+[OpenTelemetry][opentelemetry-home] is an open source observability framework, providing a general-purpose API, SDK, and related tools required for the instrumentation of cloud-native software, frameworks, and libraries.
+
+OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
+
+## How does this gem fit in?
+
+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.
+
+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.
+
+## How do I get started?
+
+Install the gem using:
+
+```
+gem install opentelemetry-metrics-api
+```
+
+Or, if you use [bundler][bundler-home], include `opentelemetry-metrics-api` in your `Gemfile`.
+
+Then, use the OpenTelemetry interfaces to produces traces and other telemetry data. Following is a basic example.
+
+```ruby
+require 'opentelemetry-metrics-api'
+
+# Obtain the current default meter provider
+provider = OpenTelemetry.meter_provider
+
+# Create a meter
+meter = provider.meter('my_app', '1.0')
+
+# Record a metric
+histogram = meter.create_histogram('histogram', unit: 's', description: 'duration in seconds')
+
+# Record a metric.
+histogram.record(123, attributes: {'foo' => 'bar'})
+```
+
+For additional examples, see the [examples on github][examples-github].
+
+## How can I get involved?
+
+The `opentelemetry-metrics-api` gem source is [on github][repo-github], along with related gems including `opentelemetry-metrics-sdk`.
+
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+
+There's still work to be done, to get to a spec-compliant metrics implementation and we'd love to have more folks contributing to the project. Check the [repo][repo-github] for issues and PRs labeled with `metrics` to see what's available.
+
+## License
+
+The `opentelemetry-api` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
+
+[metrics-api]: https://opentelemetry.io/docs/specs/otel/metrics/api/
+[opentelemetry-home]: https://opentelemetry.io
+[bundler-home]: https://bundler.io
+[repo-github]: https://github.com/open-telemetry/opentelemetry-ruby
+[license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/main/LICENSE
+[examples-github]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples
+[ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
+[community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

metrics_api/lib/opentelemetry/metrics/version.rb

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

metrics_sdk/README.md

@@ -0,0 +1,105 @@
+# opentelemetry-metrics-sdk
+
+The `opentelemetry-metrics-sdk` is an alpha implementation of the [OpenTelemetry Metrics SDK][metrics-sdk] for Ruby. It should be used in conjunction with the `opentelemetry-sdk` to collect, analyze and export metrics.
+
+## What is OpenTelemetry?
+
+[OpenTelemetry][opentelemetry-home] is an open source observability framework, providing a general-purpose API, SDK, and related tools required for the instrumentation of cloud-native software, frameworks, and libraries.
+
+OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces, metrics, and logs from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
+
+## How does this gem fit in?
+
+Metrics is one of the core signals in OpenTelemetry. This package allows you to emit OpenTelemetry metrics using Ruby. It leverages an alpha implementation of the OpenTelemetry Metrics API. At the current stage, things may break and APIs may change. Use this tool with caution.
+
+This gem does not have a full implementation of the Metrics SDK specification. The work is in progress.
+
+At this time, you should be able to:
+* Create synchronous:
+  * counters
+  * up down counters
+  * histograms
+  * observable counters
+  * observable gauges
+  * observable up down counters
+* Export using a pull exporter
+* Use delta aggregation temporality
+
+We do not yet have support for:
+* Asynchronous instruments
+* Cumulative aggregation temporality
+* Metrics Views
+* Metrics Exemplars
+* Periodic Exporting Metric Reader
+* Push metric exporting
+
+These lists are incomplete and are intended to give a broad description of what's available.
+
+Until the Ruby implementation of OpenTelemetry Metrics becomes stable, the functionality to create and export metrics will remain in a gem separate from the stable features available from the `opentelemetry-sdk`.
+
+## How do I get started?
+
+Install the gems using:
+
+```
+gem install opentelemetry-metrics-sdk
+gem install opentelemetry-sdk
+```
+
+Or, if you use [bundler][bundler-home], include `opentelemetry-metrics-sdk` and `opentelemetry-sdk` in your `Gemfile`.
+
+Then, configure the SDK according to your desired handling of telemetry data, and use the OpenTelemetry interfaces to produces traces and other information. Following is a basic example.
+
+```ruby
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-sdk'
+
+# Configure the sdk with default export and context propagation formats.
+OpenTelemetry::SDK.configure
+
+# Create an exporter. This example exports metrics to the console.
+console_metric_exporter = OpenTelemetry::SDK::Metrics::Export::ConsoleMetricPullExporter.new
+
+# Add the exporter to the meter provider as a new metric reader.
+OpenTelemetry.meter_provider.add_metric_reader(console_metric_exporter)
+
+# Create a meter to generate instruments.
+meter = OpenTelemetry.meter_provider.meter("SAMPLE_METER_NAME")
+
+# Create an instrument.
+histogram = meter.create_histogram('histogram', unit: 'smidgen', description: 'desscription')
+
+# Record a metric.
+histogram.record(123, attributes: {'foo' => 'bar'})
+
+# Send the recorded metrics to the metric readers.
+OpenTelemetry.meter_provider.metric_readers.each(&:pull)
+
+# Shut down the meter provider.
+OpenTelemetry.meter_provider.shutdown
+```
+
+For additional examples, see the [examples on github][examples-github].
+
+## How can I get involved?
+
+The `opentelemetry-metrics-sdk` gem source is [on github][repo-github], along with related gems including `opentelemetry-sdk`.
+
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+
+There's still work to be done, to get to a spec-compliant metrics implementation and we'd love to have more folks contributing to the project. Check the [repo][repo-github] for issues and PRs labeled with `metrics` to see what's available.
+
+## License
+
+The `opentelemetry-metrics-sdk` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
+
+
+[metrics-sdk]: https://opentelemetry.io/docs/specs/otel/metrics/sdk/
+[opentelemetry-home]: https://opentelemetry.io
+[bundler-home]: https://bundler.io
+[repo-github]: https://github.com/open-telemetry/opentelemetry-ruby
+[license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/main/LICENSE
+[examples-github]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples/
+[ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
+[community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

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.0.1'
+      VERSION = '0.1.0'
     end
   end
 end