Add Rakefile, README, API docs, change namespace of Otel tracer/meter

Author: DemetrisChr

.gitignore

@@ -8,14 +8,14 @@
 .byebug_history
 /.rakeTasks
 /.ruby-version
-/.yardoc
+/**/.yardoc
 /_yardoc/
 /cmake-build-*/
 /build*
 /coverage/
-/doc/
+/**/doc/
 /ext/cache/
-/pkg/
+/**/pkg/
 /test/reports/
 /tmp/
 /logs/

README.md

@@ -18,7 +18,7 @@ Please attach version information to the ticket/post. To obtain this information
 
 ## Installation
 
-The library has been tested with MRI 3.1, 3.2, 3.3 and 3.4. Supported platforms are Linux and MacOS.
+The library has been tested with MRI 3.2, 3.3, 3.4 and 4.0. Supported platforms are Linux and MacOS.
 
 Add this line to your application's Gemfile:
 

couchbase-opentelemetry/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: ../.rubocop.yml

couchbase-opentelemetry/.yardopts

@@ -0,0 +1,3 @@
+--no-progress --output-dir doc/couchbase-ruby-client-master lib - README.md
+--tag couchbase.stability:"Stability"
+--transitive-tag couchbase.stability

couchbase-opentelemetry/README.md

@@ -0,0 +1,83 @@
+# Couchbase Ruby Client OpenTelemetry Integration
+
+## Installation
+
+The library has been tested with MRI 3.2, 3.3, 3.4 and 4.0. Supported platforms are Linux and MacOS.
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "couchbase-opentelemetry", "0.1.0"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install couchbase-opentelemetry
+
+## Usage
+
+Here is an example on how to set up Tracing and Metrics with OpenTelemetr:
+
+```ruby
+require "couchbase"
+require "couchbase/opentelemetry"
+
+require "opentelemetry-sdk"
+require "opentelemetry-metrics-sdk"
+
+# Initialize a tracer provider
+tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
+tracer_provider.add_span_processor(
+    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+        OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint: "https://<hostname>:<port>/v1/traces")
+    )
+)
+
+# Initialize the Couchbase OpenTelemetry Request Tracer
+tracer = Couchbase::OpenTelemetry::RequestTracer.new(tracer_provider)
+
+# Initialize a meter provider
+meter_provider = OpenTelemetry::SDK::Metrics::MeterProvider.new
+meter_provider.add_metric_reader(
+    OpenTelemetry::SDk::Metrics::Export::PeriodicMetricReader.new(
+        exporter: OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
+            endpoint: "https://<hostname>:<port>/v1/metrics"
+        )
+    )
+)
+
+# Initialize the Couchbase OpenTelemetry Meter
+meter = Couchbase::OpenTelemetry::Meter.new(meter_provider)
+
+# Configure tracer and meter in cluster options
+options = Couchbase::Options::Cluster.new(
+    authenticator: Couchbase::PasswordAuthenticator.new("Administrator", "password")
+    tracer: tracer,
+    meter: meter
+)
+
+# Initialize cluster instance
+cluster = Cluster.connect("couchbase://127.0.0.1", options)
+```
+
+## License
+
+The gem is available as open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).
+
+    Copyright 2025-Present Couchbase, Inc.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

couchbase-opentelemetry/Rakefile

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+#  Copyright 2026-Present Couchbase, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+desc "Generate YARD documentation"
+task :doc do
+  require "couchbase/opentelemetry/version"
+  input_dir = File.join(__dir__, "lib")
+  output_dir = File.join(__dir__, "doc", "couchbase-ruby-client-#{Couchbase::OpenTelemetry::VERSION}")
+  rm_rf output_dir
+  sh "bundle exec yard doc --no-progress --hide-api private --output-dir #{output_dir} #{input_dir} --main README.md"
+  puts "#{File.realpath(output_dir)}/index.html"
+end
+
+desc "An alias for documentation generation task"
+task :docs => :doc
+
+desc "Display stats on undocumented things"
+task :undocumented => :doc do
+  sh "yard stats --list-undoc --compact"
+end
+
+RuboCop::RakeTask.new

couchbase-opentelemetry/couchbase-opentelemetry.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.description = "OpenTelemetry integration for the Couchbase Ruby Client"
   spec.homepage = "https://www.couchbase.com"
   spec.license = "Apache-2.0"
-  spec.required_ruby_version = "> 3.1"
+  spec.required_ruby_version = "> 3.2"
 
   spec.metadata = {
     "homepage_uri" => "https://docs.couchbase.com/ruby-sdk/current/hello-world/start-using-sdk.html",

couchbase-opentelemetry/lib/couchbase/metrics/open_telemetry_meter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#  Copyright 2026-Present Couchbase, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require_relative "opentelemetry/request_tracer"
+require_relative "opentelemetry/meter"

couchbase-opentelemetry/lib/couchbase/opentelemetry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+#  Copyright 2026-Present Couchbase, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require "couchbase/metrics/meter"
+require "couchbase/errors"
+require_relative "value_recorder"
+
+require "opentelemetry-metrics-api"
+
+module Couchbase
+  module OpenTelemetry
+    # @couchbase.stability
+    #  **Uncommitted:** This API may change in the future, as Metrics in OpenTelemetry Ruby are currently in development.
+    #
+    #  See the {https://opentelemetry.io/docs/languages/ruby/#status-and-releases OpenTelemetry Ruby documentation} for more information.
+    class Meter < ::Couchbase::Metrics::Meter
+      # Initializes a Couchbase OpenTelemetry Meter
+      #
+      # @param [::OpenTelemetry::Metrics::MeterProvider] meter_provider The OpenTelemetry meter provider
+      #
+      # @raise [Couchbase::Error::MeterError] if the meter cannot be created for any reason
+      #
+      # @example Initializing a Couchbase OpenTelemetry Meter with an OTLP Exporter
+      #   require "opentelemetry-metrics-sdk"
+      #
+      #   # Initialize a meter provider
+      #   meter_provider = ::OpenTelemetry::SDK::Metrics::MeterProvider.new
+      #   meter_provider.add_metric_reader(
+      #       ::OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader.new(
+      #           exporter: ::OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
+      #               endpoint: "https://<hostname>:<port>/v1/metrics"
+      #          )
+      #       )
+      #   )
+      #   # Initialize the Couchbase OpenTelemetry Meter
+      #   meter = Couchbase::OpenTelemetry::Meter.new(meter_provider)
+      #
+      #   # Set the meter in the cluster options
+      #   options = Couchbase::Options::Cluster.new(
+      #      authenticator: Couchbase::PasswordAuthenticator.new("Administrator", "password")
+      #      meter: meter
+      #   )
+      #
+      # @see https://www.rubydoc.info/gems/opentelemetry-metrics-sdk/OpenTelemetry/SDK/Metrics/MeterProvider
+      #  <tt>opentelemetry-metrics-sdk</tt> API Reference
+      def initialize(meter_provider)
+        super()
+        @histogram_cache = Concurrent::Map.new
+        begin
+          @wrapped = meter_provider.meter("com.couchbase.client/ruby")
+        rescue StandardError => e
+          raise Error::MeterError.new("Failed to create OpenTelemetry Meter: #{e.message}", nil, e)
+        end
+      end
+
+      def value_recorder(name, tags)
+        unit = tags.delete("__unit")
+
+        otel_histogram = @histogram_cache.compute_if_absent(name) do
+          @wrapped.create_histogram(name, unit: unit)
+        end
+
+        ValueRecorder.new(otel_histogram, tags, unit: unit)
+      rescue StandardError => e
+        raise Error::MeterError.new("Failed to create OpenTelemetry Histogram: #{e.message}", nil, e)
+      end
+    end
+  end
+end