couchbase 3.7.0 → 3.8.0

data/lib/couchbase/management/view_index_manager.rb

@@ -15,9 +15,114 @@
 #  limitations under the License.
 
 require "couchbase/errors"
+require "couchbase/options"
 
 module Couchbase
   module Management
+    module Options
+      module View
+        # Options for {ViewIndexManager#get_design_document}
+        class GetDesignDocument < Couchbase::Options::Base
+          # Creates an instance of options for {ViewIndexManager#get_design_document}
+          #
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [GetDesignDocument]
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = new.freeze
+        end
+
+        # Options for {ViewIndexManager#get_all_design_documents}
+        class GetAllDesignDocuments < Couchbase::Options::Base
+          # Creates an instance of options for {ViewIndexManager#get_all_design_documents}
+          #
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [GetAllDesignDocuments]
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = new.freeze
+        end
+
+        # Options for {ViewIndexManager#upsert_design_document}
+        class UpsertDesignDocument < Couchbase::Options::Base
+          # Creates an instance of options for {ViewIndexManager#upsert_design_document}
+          #
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [UpsertDesignDocument]
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = new.freeze
+        end
+
+        # Options for {ViewIndexManager#drop_design_document}
+        class DropDesignDocument < Couchbase::Options::Base
+          # Creates an instance of options for {ViewIndexManager#drop_design_document}
+          #
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [DropDesignDocument]
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = new.freeze
+        end
+
+        # Options for {ViewIndexManager#publish_design_document}
+        class PublishDesignDocument < Couchbase::Options::Base
+          # Creates an instance of options for {ViewIndexManager#publish_design_document}
+          #
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [PublishDesignDocument]
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = new.freeze
+        end
+      end
+    end
+
     # The View Index Manager interface contains the means for managing design documents used for views.
     #
     # A design document belongs to either the "development" or "production" namespace. A development document has a name
@@ -33,6 +138,10 @@ module Couchbase
     # All methods (except publish) have a required "namespace" argument indicating whether the operation targets a
     # development document or a production document. The type of this argument is [Symbol] with allowed values
     # +:production+ and +:development+.
+    #
+    # @deprecated Views are deprecated in Couchbase Server 7.0+, and will be removed from a future server version.
+    #   Views are not compatible with the Magma storage engine. Instead of views, use indexes and queries using the
+    #   Index Service (GSI) and the Query Service (SQL++).
     class ViewIndexManager
       alias inspect to_s
 
@@ -41,35 +150,41 @@ module Couchbase
 
       # @param [Couchbase::Backend] backend
       # @param [String] bucket_name
-      def initialize(backend, bucket_name)
+      # @param [Observability::Wrapper] observability wrapper
+      def initialize(backend, bucket_name, observability)
         @backend = backend
         @bucket_name = bucket_name
+        @observability = observability
       end
 
       # Fetches a design document from the server
       #
       # @param [String] name the name of the design document
       # @param [:production, :development] namespace the namespace
-      # @param [GetDesignDocumentOptions] options
+      # @param [Options::View::GetDesignDocument] options
       #
       # @return [DesignDocument]
       #
       # @raise [Error::DesignDocumentNotFound]
-      def get_design_document(name, namespace, options = GetDesignDocumentOptions.new)
-        resp = @backend.view_index_get(@bucket_name, name, namespace, options.timeout)
-        extract_design_document(resp)
+      def get_design_document(name, namespace, options = Options::View::GetDesignDocument::DEFAULT)
+        @observability.record_operation(Observability::OP_VM_GET_DESIGN_DOCUMENT, options.parent_span, self, :views) do |obs_handler|
+          resp = @backend.view_index_get(@bucket_name, name, namespace, options.timeout, obs_handler)
+          extract_design_document(resp)
+        end
       end
 
       # Fetches all design documents from the server
       #
       # @param [:production, :development] namespace the namespace
-      # @param [GetAllDesignDocumentsOptions] options
+      # @param [Options::View::GetAllDesignDocuments] options
       #
       # @return [Array<DesignDocument>]
-      def get_all_design_documents(namespace, options = GetAllDesignDocumentsOptions.new)
-        resp = @backend.view_index_get_all(@bucket_name, namespace, options.timeout)
-        resp.map do |entry|
-          extract_design_document(entry)
+      def get_all_design_documents(namespace, options = Options::View::GetAllDesignDocuments::DEFAULT)
+        @observability.record_operation(Observability::OP_VM_GET_ALL_DESIGN_DOCUMENTS, options.parent_span, self, :views) do |obs_handler|
+          resp = @backend.view_index_get_all(@bucket_name, namespace, options.timeout, obs_handler)
+          resp.map do |entry|
+            extract_design_document(entry)
+          end
         end
       end
 
@@ -77,33 +192,37 @@ module Couchbase
       #
       # @param [DesignDocument] document
       # @param [:production, :development] namespace the namespace
-      # @param [UpsertDesignDocumentOptions] options
+      # @param [Options::View::UpsertDesignDocument] options
       #
       # @return [void]
-      def upsert_design_document(document, namespace, options = UpsertDesignDocumentOptions.new)
-        @backend.view_index_upsert(@bucket_name, {
-          name: document.name,
-          views: document.views.map do |name, view|
-            {
-              name: name,
-              map: view.map_function,
-              reduce: view.reduce_function,
-            }
-          end,
-        }, namespace, options.timeout)
+      def upsert_design_document(document, namespace, options = Options::View::UpsertDesignDocument::DEFAULT)
+        @observability.record_operation(Observability::OP_VM_UPSERT_DESIGN_DOCUMENT, options.parent_span, self, :views) do |obs_handler|
+          @backend.view_index_upsert(@bucket_name, {
+            name: document.name,
+            views: document.views.map do |name, view|
+              {
+                name: name,
+                map: view.map_function,
+                reduce: view.reduce_function,
+              }
+            end,
+          }, namespace, options.timeout, obs_handler)
+        end
       end
 
       # Removes the design document
       #
       # @param [String] name design document name
       # @param [:production, :development] namespace the namespace
-      # @param [DropDesignDocumentOptions] options
+      # @param [Options::View::DropDesignDocument] options
       #
       # @return [void]
       #
       # @raise [Error::DesignDocumentNotFound]
-      def drop_design_document(name, namespace, options = DropDesignDocumentOptions.new)
-        @backend.view_index_drop(@bucket_name, name, namespace, options.timeout)
+      def drop_design_document(name, namespace, options = Options::View::DropDesignDocument::DEFAULT)
+        @observability.record_operation(Observability::OP_VM_DROP_DESIGN_DOCUMENT, options.parent_span, self, :views) do |obs_handler|
+          @backend.view_index_drop(@bucket_name, name, namespace, options.timeout, obs_handler)
+        end
       end
 
       # Publishes the design document.
@@ -112,66 +231,40 @@ module Couchbase
       # it to the production namespace.
       #
       # @param [String] name design document name
-      # @param [PublishDesignDocumentOptions] options
+      # @param [Options::View::PublishDesignDocument] options
       #
       # @return [void]
       #
       # @raise [ArgumentError]
       # @raise [Error::DesignDocumentNotFound]
-      def publish_design_document(name, options = PublishDesignDocumentOptions.new)
-        document = get_design_document(name, :development, GetDesignDocumentOptions.new { |o| o.timeout = options.timeout })
-        upsert_design_document(document, :production, UpsertDesignDocumentOptions.new { |o| o.timeout = options.timeout })
-      end
-
-      class GetDesignDocumentOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
-
-        # @yieldparam [GetDesignDocumentOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
-
-      class GetAllDesignDocumentsOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
-
-        # @yieldparam [GetAllDesignDocumentsOptions] self
-        def initialize
-          yield self if block_given?
+      def publish_design_document(name, options = Options::View::PublishDesignDocument::DEFAULT)
+        @observability.record_operation(Observability::OP_VM_PUBLISH_DESIGN_DOCUMENT, options.parent_span, self, :views) do |obs_handler|
+          document = get_design_document(name, :development,
+                                         Options::View::GetDesignDocument.new(timeout: options.timeout, parent_span: obs_handler.op_span))
+          upsert_design_document(document, :production,
+                                 Options::View::UpsertDesignDocument.new(timeout: options.timeout, parent_span: obs_handler.op_span))
         end
       end
 
-      class UpsertDesignDocumentOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
-
-        # @yieldparam [UpsertDesignDocumentOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
+      # @api private
+      # @deprecated use {Options::View::GetDesignDocument} instead
+      GetDesignDocumentOptions = Options::View::GetDesignDocument
 
-      class DropDesignDocumentOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
+      # @api private
+      # @deprecated use {Options::View::GetAllDesignDocuments} instead
+      GetAllDesignDocumentsOptions = Options::View::GetAllDesignDocuments
 
-        # @yieldparam [DropDesignDocumentOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
+      # @api private
+      # @deprecated use {Options::View::UpsertDesignDocument} instead
+      UpsertDesignDocumentOptions = Options::View::UpsertDesignDocument
 
-      class PublishDesignDocumentOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
+      # @api private
+      # @deprecated use {Options::View::DropDesignDocument} instead
+      DropDesignDocumentOptions = Options::View::DropDesignDocument
 
-        # @yieldparam [PublishDesignDocumentOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
+      # @api private
+      # @deprecated use {Options::View::PublishDesignDocument} instead
+      PublishDesignDocumentOptions = Options::View::PublishDesignDocument
 
       private
 

data/lib/couchbase/metrics/logging_meter.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+#  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.
+
+require_relative "logging_value_recorder"
+require_relative "meter"
+require_relative "noop_meter"
+require "couchbase/utils/observability_constants"
+require "couchbase/utils/stdlib_logger_adapter"
+require "couchbase/logger"
+
+require "concurrent/map"
+require "concurrent/timer_task"
+
+module Couchbase
+  module Metrics
+    class LoggingMeter < Meter
+      # @api private
+      DEFAULT_EMIT_INTERVAL = 600_000 # milliseconds
+
+      def initialize(emit_interval: nil)
+        super()
+        @emit_interval = emit_interval || DEFAULT_EMIT_INTERVAL
+        @value_recorders = {
+          Observability::ATTR_VALUE_SERVICE_KV => Concurrent::Map.new,
+          Observability::ATTR_VALUE_SERVICE_QUERY => Concurrent::Map.new,
+          Observability::ATTR_VALUE_SERVICE_VIEWS => Concurrent::Map.new,
+          Observability::ATTR_VALUE_SERVICE_SEARCH => Concurrent::Map.new,
+          Observability::ATTR_VALUE_SERVICE_ANALYTICS => Concurrent::Map.new,
+          Observability::ATTR_VALUE_SERVICE_MANAGEMENT => Concurrent::Map.new,
+        }
+
+        # TODO(DC): Find better solution for logging
+        @logger = Couchbase.logger || Logger.new($stdout, Utils::StdlibLoggerAdapter.map_spdlog_level(Couchbase.log_level))
+        @task = Concurrent::TimerTask.new(execution_interval: @emit_interval / 1_000.0) do
+          report = create_report
+          return if report.empty?
+
+          @logger.info("Metrics: #{report.to_json}")
+        rescue StandardError => e
+          @logger.debug("Failed to log metrics: #{e.message}")
+        end
+      end
+
+      def value_recorder(name, tags)
+        return NoopMeter::VALUE_RECORDER_INSTANCE unless name == Observability::METER_NAME_OPERATION_DURATION
+
+        operation_name = tags[Observability::ATTR_OPERATION_NAME]
+        service = tags[Observability::ATTR_SERVICE]
+
+        return NoopMeter::VALUE_RECORDER_INSTANCE if operation_name.nil? || service.nil?
+
+        @value_recorders[service].put_if_absent(
+          operation_name,
+          LoggingValueRecorder.new(
+            operation_name: operation_name,
+            service: service,
+          ),
+        )
+
+        @value_recorders[service][operation_name]
+      end
+
+      def create_report
+        operations = {}
+        @value_recorders.each do |service, recorders|
+          recorders.each_key do |operation_name|
+            recorder = recorders[operation_name]
+            operation_report = recorder.report_and_reset
+            if operation_report
+              operations[service] ||= {}
+              operations[service][operation_name] = operation_report
+            end
+          end
+        end
+        if operations.empty?
+          {}
+        else
+          {
+            meta: {
+              emit_interval_ms: @emit_interval,
+            },
+            operations: operations,
+          }
+        end
+      end
+
+      def close
+        @task.shutdown
+        @value_recorders.each_value do |operation_map|
+          operation_map.each_value(&:close)
+        end
+      end
+    end
+  end
+end

data/lib/couchbase/metrics/logging_value_recorder.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#  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.
+
+require_relative "value_recorder"
+require "couchbase/utils/hdr_histogram"
+
+module Couchbase
+  module Metrics
+    class LoggingValueRecorder < ValueRecorder
+      attr_reader :operation_name
+      attr_reader :service
+
+      def initialize(operation_name:, service:)
+        super()
+        @operation_name = operation_name
+        @service = service
+        @histogram = Utils::HdrHistogram.new(
+          lowest_discernible_value: 1, # 1 microsecond
+          highest_trackable_value: 30_000_000, # 30 seconds
+          significant_figures: 3,
+        )
+      end
+
+      def record_value(value)
+        @histogram.record_value(value)
+      end
+
+      def report_and_reset
+        @histogram.report_and_reset
+      end
+
+      def close
+        @histogram.close
+      end
+    end
+  end
+end

data/lib/couchbase/metrics/meter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+#  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.
+
+module Couchbase
+  module Metrics
+    class Meter
+      def value_recorder(name, tags)
+        raise NotImplementedError, "The meter does not implement #value_recorder"
+      end
+
+      def close; end
+    end
+  end
+end

data/lib/couchbase/metrics/noop_meter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+#  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.
+
+require_relative 'meter'
+require_relative 'noop_value_recorder'
+
+module Couchbase
+  module Metrics
+    class NoopMeter < Meter
+      def value_recorder(_name, _tags)
+        VALUE_RECORDER_INSTANCE
+      end
+
+      VALUE_RECORDER_INSTANCE = NoopValueRecorder.new.freeze
+    end
+  end
+end

data/lib/couchbase/metrics/noop_value_recorder.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+#  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.
+
+require_relative 'value_recorder'
+
+module Couchbase
+  module Metrics
+    class NoopValueRecorder < ValueRecorder
+      def record_value(_value)
+        # Do nothing
+      end
+    end
+  end
+end

data/lib/couchbase/metrics/value_recorder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+#  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.
+
+module Couchbase
+  module Metrics
+    class ValueRecorder
+      def record_value(value)
+        raise NotImplementedError, "The value recorder does not implement #record_value"
+      end
+    end
+  end
+end