couchbase 3.7.0 → 3.8.0

data/lib/couchbase/binary_collection.rb

@@ -23,9 +23,12 @@ module Couchbase
     alias inspect to_s
 
     # @param [Couchbase::Collection] collection parent collection
+    #
+    # @api private
     def initialize(collection)
       @collection = collection
       @backend = collection.instance_variable_get(:@backend)
+      @observability = collection.instance_variable_get(:@observability)
     end
 
     # Appends binary content to the document
@@ -41,11 +44,14 @@ module Couchbase
     #
     # @return [Collection::MutationResult]
     def append(id, content, options = Options::Append::DEFAULT)
-      resp = @backend.document_append(@collection.bucket_name, @collection.scope_name, @collection.name,
-                                      id, content, options.to_backend)
-      Collection::MutationResult.new do |res|
-        res.cas = resp[:cas]
-        res.mutation_token = @collection.send(:extract_mutation_token, resp)
+      @observability.record_operation(Observability::OP_APPEND, options.parent_span, self, :kv) do |obs_handler|
+        obs_handler.add_durability_level(options.durability_level)
+        resp = @backend.document_append(@collection.bucket_name, @collection.scope_name, @collection.name,
+                                        id, content, options.to_backend, obs_handler)
+        Collection::MutationResult.new do |res|
+          res.cas = resp[:cas]
+          res.mutation_token = @collection.send(:extract_mutation_token, resp)
+        end
       end
     end
 
@@ -62,11 +68,14 @@ module Couchbase
     #
     # @return [Collection::MutationResult]
     def prepend(id, content, options = Options::Prepend::DEFAULT)
-      resp = @backend.document_prepend(@collection.bucket_name, @collection.scope_name, @collection.name,
-                                       id, content, options.to_backend)
-      Collection::MutationResult.new do |res|
-        res.cas = resp[:cas]
-        res.mutation_token = @collection.send(:extract_mutation_token, resp)
+      @observability.record_operation(Observability::OP_PREPEND, options.parent_span, self, :kv) do |obs_handler|
+        obs_handler.add_durability_level(options.durability_level)
+        resp = @backend.document_prepend(@collection.bucket_name, @collection.scope_name, @collection.name,
+                                         id, content, options.to_backend, obs_handler)
+        Collection::MutationResult.new do |res|
+          res.cas = resp[:cas]
+          res.mutation_token = @collection.send(:extract_mutation_token, resp)
+        end
       end
     end
 
@@ -83,12 +92,15 @@ module Couchbase
     #
     # @return [CounterResult]
     def increment(id, options = Options::Increment::DEFAULT)
-      resp = @backend.document_increment(@collection.bucket_name, @collection.scope_name, @collection.name, id,
-                                         options.to_backend)
-      CounterResult.new do |res|
-        res.cas = resp[:cas]
-        res.content = resp[:content]
-        res.mutation_token = @collection.send(:extract_mutation_token, resp)
+      @observability.record_operation(Observability::OP_INCREMENT, options.parent_span, self, :kv) do |obs_handler|
+        obs_handler.add_durability_level(options.durability_level)
+        resp = @backend.document_increment(@collection.bucket_name, @collection.scope_name, @collection.name, id,
+                                           options.to_backend, obs_handler)
+        CounterResult.new do |res|
+          res.cas = resp[:cas]
+          res.content = resp[:content]
+          res.mutation_token = @collection.send(:extract_mutation_token, resp)
+        end
       end
     end
 
@@ -105,12 +117,15 @@ module Couchbase
     #
     # @return [CounterResult]
     def decrement(id, options = Options::Decrement::DEFAULT)
-      resp = @backend.document_decrement(@collection.bucket_name, @collection.scope_name, @collection.name, id,
-                                         options.to_backend)
-      CounterResult.new do |res|
-        res.cas = resp[:cas]
-        res.content = resp[:content]
-        res.mutation_token = @collection.send(:extract_mutation_token, resp)
+      @observability.record_operation(Observability::OP_DECREMENT, options.parent_span, self, :kv) do |obs_handler|
+        obs_handler.add_durability_level(options.durability_level)
+        resp = @backend.document_decrement(@collection.bucket_name, @collection.scope_name, @collection.name, id,
+                                           options.to_backend, obs_handler)
+        CounterResult.new do |res|
+          res.cas = resp[:cas]
+          res.content = resp[:content]
+          res.mutation_token = @collection.send(:extract_mutation_token, resp)
+        end
       end
     end
 

data/lib/couchbase/bucket.rb

@@ -30,17 +30,20 @@ module Couchbase
     alias inspect to_s
 
     # @param [Couchbase::Backend] backend
-    def initialize(backend, name)
+    #
+    # @api private
+    def initialize(backend, name, observability)
       backend.open_bucket(name, true)
       @backend = backend
       @name = name
+      @observability = observability
     end
 
     # Get default scope
     #
     # @return [Scope]
     def default_scope
-      Scope.new(@backend, @name, "_default")
+      Scope.new(@backend, @name, "_default", @observability)
     end
 
     # Get a named scope
@@ -49,7 +52,7 @@ module Couchbase
     #
     # @return [Scope]
     def scope(scope_name)
-      Scope.new(@backend, @name, scope_name)
+      Scope.new(@backend, @name, scope_name, @observability)
     end
 
     # Opens the named collection in the default scope of the bucket
@@ -65,7 +68,7 @@ module Couchbase
     #
     # @return [Collection]
     def default_collection
-      Collection.new(@backend, @name, "_default", "_default")
+      Collection.new(@backend, @name, "_default", "_default", @observability)
     end
 
     # Performs query to view index.
@@ -82,18 +85,24 @@ module Couchbase
     #                     ))
     #
     # @return [ViewResult]
+    #
+    # @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++).
     def view_query(design_document_name, view_name, options = Options::View::DEFAULT)
-      resp = @backend.document_view(@name, design_document_name, view_name, options.namespace, options.to_backend)
-      ViewResult.new do |res|
-        res.meta_data = ViewMetaData.new do |meta|
-          meta.total_rows = resp[:meta][:total_rows]
-          meta.debug_info = resp[:meta][:debug_info]
-        end
-        res.rows = resp[:rows].map do |entry|
-          ViewRow.new do |row|
-            row.id = entry[:id] if entry.key?(:id)
-            row.key = JSON.parse(entry[:key])
-            row.value = JSON.parse(entry[:value])
+      @observability.record_operation(Observability::OP_VIEW_QUERY, options.parent_span, self, :views) do |obs_handler|
+        resp = @backend.document_view(@name, design_document_name, view_name, options.namespace, options.to_backend, obs_handler)
+        ViewResult.new do |res|
+          res.meta_data = ViewMetaData.new do |meta|
+            meta.total_rows = resp[:meta][:total_rows]
+            meta.debug_info = resp[:meta][:debug_info]
+          end
+          res.rows = resp[:rows].map do |entry|
+            ViewRow.new do |row|
+              row.id = entry[:id] if entry.key?(:id)
+              row.key = JSON.parse(entry[:key])
+              row.value = JSON.parse(entry[:value])
+            end
           end
         end
       end
@@ -101,12 +110,16 @@ module Couchbase
 
     # @return [Management::CollectionManager]
     def collections
-      Management::CollectionManager.new(@backend, @name)
+      Management::CollectionManager.new(@backend, @name, @observability)
     end
 
     # @return [Management::ViewIndexManager]
+    #
+    # @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++).
     def view_indexes
-      Management::ViewIndexManager.new(@backend, @name)
+      Management::ViewIndexManager.new(@backend, @name, @observability)
     end
 
     # Performs application-level ping requests against services in the couchbase cluster
@@ -115,20 +128,22 @@ module Couchbase
     #
     # @return [PingResult]
     def ping(options = Options::Ping::DEFAULT)
-      resp = @backend.ping(@name, options.to_backend)
-      PingResult.new do |res|
-        res.version = resp[:version]
-        res.id = resp[:id]
-        res.sdk = resp[:sdk]
-        resp[:services].each do |type, svcs|
-          res.services[type] = svcs.map do |svc|
-            PingResult::ServiceInfo.new do |info|
-              info.id = svc[:id]
-              info.state = svc[:state]
-              info.latency = svc[:latency]
-              info.remote = svc[:remote]
-              info.local = svc[:local]
-              info.error = svc[:error]
+      @observability.record_operation(Observability::OP_PING, options.parent_span, self) do |_obs_handler|
+        resp = @backend.ping(@name, options.to_backend)
+        PingResult.new do |res|
+          res.version = resp[:version]
+          res.id = resp[:id]
+          res.sdk = resp[:sdk]
+          resp[:services].each do |type, svcs|
+            res.services[type] = svcs.map do |svc|
+              PingResult::ServiceInfo.new do |info|
+                info.id = svc[:id]
+                info.state = svc[:state]
+                info.latency = svc[:latency]
+                info.remote = svc[:remote]
+                info.local = svc[:local]
+                info.error = svc[:error]
+              end
             end
           end
         end

data/lib/couchbase/cluster.rb

@@ -28,6 +28,12 @@ require "couchbase/analytics_options"
 require "couchbase/diagnostics"
 
 require "couchbase/protostellar"
+require "couchbase/utils/observability"
+
+require "couchbase/tracing/threshold_logging_tracer"
+require "couchbase/tracing/noop_tracer"
+require "couchbase/metrics/noop_meter"
+require "couchbase/metrics/logging_meter"
 
 module Couchbase
   # The main entry point when connecting to a Couchbase cluster.
@@ -87,7 +93,39 @@ module Couchbase
     #
     # @return [Bucket]
     def bucket(name)
-      Bucket.new(@backend, name)
+      Bucket.new(@backend, name, @observability)
+    end
+
+    # Updates the authenticator used for this cluster connection
+    #
+    # @param [PasswordAuthenticator, CertificateAuthenticator, JWTAuthenticator] authenticator the new authenticator
+    def update_authenticator(authenticator)
+      credentials = {}
+
+      case authenticator
+      when PasswordAuthenticator
+        credentials[:username] = authenticator.username
+        raise ArgumentError, "missing username" unless credentials[:username]
+
+        credentials[:password] = authenticator.password
+        raise ArgumentError, "missing password" unless credentials[:password]
+
+      when CertificateAuthenticator
+        credentials[:certificate_path] = authenticator.certificate_path
+        raise ArgumentError, "missing certificate path" unless credentials[:certificate_path]
+
+        credentials[:key_path] = authenticator.key_path
+        raise ArgumentError, "missing key path" unless credentials[:key_path]
+
+      when JWTAuthenticator
+        credentials[:jwt] = authenticator.token
+        raise ArgumentError, "missing token" unless credentials[:jwt]
+
+      else
+        raise ArgumentError, "argument must be an authenticator"
+      end
+
+      @backend.update_credentials(credentials)
     end
 
     # Performs a query against the query (N1QL) services
@@ -109,30 +147,34 @@ module Couchbase
     #
     # @return [QueryResult]
     def query(statement, options = Options::Query::DEFAULT)
-      resp = @backend.document_query(statement, options.to_backend)
-
-      QueryResult.new do |res|
-        res.meta_data = QueryMetaData.new do |meta|
-          meta.status = resp[:meta][:status]
-          meta.request_id = resp[:meta][:request_id]
-          meta.client_context_id = resp[:meta][:client_context_id]
-          meta.signature = JSON.parse(resp[:meta][:signature]) if resp[:meta][:signature]
-          meta.profile = JSON.parse(resp[:meta][:profile]) if resp[:meta][:profile]
-          meta.metrics = QueryMetrics.new do |metrics|
-            if resp[:meta][:metrics]
-              metrics.elapsed_time = resp[:meta][:metrics][:elapsed_time]
-              metrics.execution_time = resp[:meta][:metrics][:execution_time]
-              metrics.sort_count = resp[:meta][:metrics][:sort_count]
-              metrics.result_count = resp[:meta][:metrics][:result_count]
-              metrics.result_size = resp[:meta][:metrics][:result_size]
-              metrics.mutation_count = resp[:meta][:metrics][:mutation_count]
-              metrics.error_count = resp[:meta][:metrics][:error_count]
-              metrics.warning_count = resp[:meta][:metrics][:warning_count]
+      @observability.record_operation(Observability::OP_QUERY, options.parent_span, self, :query) do |obs_handler|
+        obs_handler.add_query_statement(statement, options)
+
+        resp = @backend.document_query(statement, options.to_backend, obs_handler)
+
+        QueryResult.new do |res|
+          res.meta_data = QueryMetaData.new do |meta|
+            meta.status = resp[:meta][:status]
+            meta.request_id = resp[:meta][:request_id]
+            meta.client_context_id = resp[:meta][:client_context_id]
+            meta.signature = JSON.parse(resp[:meta][:signature]) if resp[:meta][:signature]
+            meta.profile = JSON.parse(resp[:meta][:profile]) if resp[:meta][:profile]
+            meta.metrics = QueryMetrics.new do |metrics|
+              if resp[:meta][:metrics]
+                metrics.elapsed_time = resp[:meta][:metrics][:elapsed_time]
+                metrics.execution_time = resp[:meta][:metrics][:execution_time]
+                metrics.sort_count = resp[:meta][:metrics][:sort_count]
+                metrics.result_count = resp[:meta][:metrics][:result_count]
+                metrics.result_size = resp[:meta][:metrics][:result_size]
+                metrics.mutation_count = resp[:meta][:metrics][:mutation_count]
+                metrics.error_count = resp[:meta][:metrics][:error_count]
+                metrics.warning_count = resp[:meta][:metrics][:warning_count]
+              end
             end
+            meta.warnings = resp[:warnings].map { |warn| QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
           end
-          meta.warnings = resp[:warnings].map { |warn| QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
+          res.instance_variable_set(:@rows, resp[:rows])
         end
-        res.instance_variable_set(:@rows, resp[:rows])
       end
     end
 
@@ -147,30 +189,34 @@ module Couchbase
     #
     # @return [AnalyticsResult]
     def analytics_query(statement, options = Options::Analytics::DEFAULT)
-      resp = @backend.document_analytics(statement, options.to_backend)
-
-      AnalyticsResult.new do |res|
-        res.transcoder = options.transcoder
-        res.meta_data = AnalyticsMetaData.new do |meta|
-          meta.status = resp[:meta][:status]
-          meta.request_id = resp[:meta][:request_id]
-          meta.client_context_id = resp[:meta][:client_context_id]
-          meta.signature = JSON.parse(resp[:meta][:signature]) if resp[:meta][:signature]
-          meta.profile = JSON.parse(resp[:meta][:profile]) if resp[:meta][:profile]
-          meta.metrics = AnalyticsMetrics.new do |metrics|
-            if resp[:meta][:metrics]
-              metrics.elapsed_time = resp[:meta][:metrics][:elapsed_time]
-              metrics.execution_time = resp[:meta][:metrics][:execution_time]
-              metrics.result_count = resp[:meta][:metrics][:result_count]
-              metrics.result_size = resp[:meta][:metrics][:result_size]
-              metrics.error_count = resp[:meta][:metrics][:error_count]
-              metrics.warning_count = resp[:meta][:metrics][:warning_count]
-              metrics.processed_objects = resp[:meta][:metrics][:processed_objects]
+      @observability.record_operation(Observability::OP_ANALYTICS_QUERY, options.parent_span, self, :analytics) do |obs_handler|
+        obs_handler.add_query_statement(statement, options)
+
+        resp = @backend.document_analytics(statement, options.to_backend, obs_handler)
+
+        AnalyticsResult.new do |res|
+          res.transcoder = options.transcoder
+          res.meta_data = AnalyticsMetaData.new do |meta|
+            meta.status = resp[:meta][:status]
+            meta.request_id = resp[:meta][:request_id]
+            meta.client_context_id = resp[:meta][:client_context_id]
+            meta.signature = JSON.parse(resp[:meta][:signature]) if resp[:meta][:signature]
+            meta.profile = JSON.parse(resp[:meta][:profile]) if resp[:meta][:profile]
+            meta.metrics = AnalyticsMetrics.new do |metrics|
+              if resp[:meta][:metrics]
+                metrics.elapsed_time = resp[:meta][:metrics][:elapsed_time]
+                metrics.execution_time = resp[:meta][:metrics][:execution_time]
+                metrics.result_count = resp[:meta][:metrics][:result_count]
+                metrics.result_size = resp[:meta][:metrics][:result_size]
+                metrics.error_count = resp[:meta][:metrics][:error_count]
+                metrics.warning_count = resp[:meta][:metrics][:warning_count]
+                metrics.processed_objects = resp[:meta][:metrics][:processed_objects]
+              end
             end
+            res[:warnings] = resp[:warnings].map { |warn| AnalyticsWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
           end
-          res[:warnings] = resp[:warnings].map { |warn| AnalyticsWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
+          res.instance_variable_set(:@rows, resp[:rows])
         end
-        res.instance_variable_set(:@rows, resp[:rows])
       end
     end
 
@@ -191,8 +237,10 @@ module Couchbase
     #
     # @return [SearchResult]
     def search_query(index_name, query, options = Options::Search::DEFAULT)
-      resp = @backend.document_search(nil, nil, index_name, JSON.generate(query), {}, options.to_backend)
-      convert_search_result(resp, options)
+      @observability.record_operation(Observability::OP_SEARCH_QUERY, options.parent_span, self, :search) do |obs_handler|
+        resp = @backend.document_search(nil, nil, index_name, JSON.generate(query), {}, options.to_backend, obs_handler)
+        convert_search_result(resp, options)
+      end
     end
 
     # Performs a request against the Full Text Search (FTS) service.
@@ -203,34 +251,37 @@ module Couchbase
     #
     # @return [SearchResult]
     def search(index_name, search_request, options = Options::Search::DEFAULT)
-      encoded_query, encoded_req = search_request.to_backend
-      resp = @backend.document_search(nil, nil, index_name, encoded_query, encoded_req, options.to_backend(show_request: false))
-      convert_search_result(resp, options)
+      @observability.record_operation(Observability::OP_SEARCH_QUERY, options.parent_span, self, :search) do |obs_handler|
+        encoded_query, encoded_req = search_request.to_backend
+        resp = @backend.document_search(nil, nil, index_name, encoded_query, encoded_req, options.to_backend(show_request: false),
+                                        obs_handler)
+        convert_search_result(resp, options)
+      end
     end
 
     # @return [Management::UserManager]
     def users
-      Management::UserManager.new(@backend)
+      Management::UserManager.new(@backend, @observability)
     end
 
     # @return [Management::BucketManager]
     def buckets
-      Management::BucketManager.new(@backend)
+      Management::BucketManager.new(@backend, @observability)
     end
 
     # @return [Management::QueryIndexManager]
     def query_indexes
-      Management::QueryIndexManager.new(@backend)
+      Management::QueryIndexManager.new(@backend, @observability)
     end
 
     # @return [Management::AnalyticsIndexManager]
     def analytics_indexes
-      Management::AnalyticsIndexManager.new(@backend)
+      Management::AnalyticsIndexManager.new(@backend, @observability)
     end
 
     # @return [Management::SearchIndexManager]
     def search_indexes
-      Management::SearchIndexManager.new(@backend)
+      Management::SearchIndexManager.new(@backend, @observability)
     end
 
     # Closes all connections to services and free allocated resources
@@ -238,6 +289,7 @@ module Couchbase
     # @return [void]
     def disconnect
       @backend.close
+      @observability.close
     end
 
     # Creates diagnostic report that can be used to determine the health of the network connections.
@@ -332,24 +384,28 @@ module Couchbase
           raise ArgumentError, "missing username" unless credentials[:username]
           raise ArgumentError, "missing password" unless credentials[:password]
         when Options::Cluster
-          open_options = options&.to_backend || {}
-          authenticator = options&.authenticator
+          tracer = options.tracer
+          meter = options.meter
+          open_options = options.to_backend || {}
+          authenticator = options.authenticator
           case authenticator
           when PasswordAuthenticator
-            credentials[:username] = authenticator&.username
+            credentials[:username] = authenticator.username
             raise ArgumentError, "missing username" unless credentials[:username]
 
-            credentials[:password] = authenticator&.password
+            credentials[:password] = authenticator.password
             raise ArgumentError, "missing password" unless credentials[:password]
 
-            open_options[:allowed_sasl_mechanisms] = authenticator&.allowed_sasl_mechanisms
+            open_options[:allowed_sasl_mechanisms] = authenticator.allowed_sasl_mechanisms
           when CertificateAuthenticator
-            credentials[:certificate_path] = authenticator&.certificate_path
+            credentials[:certificate_path] = authenticator.certificate_path
             raise ArgumentError, "missing certificate path" unless credentials[:certificate_path]
 
-            credentials[:key_path] = authenticator&.key_path
+            credentials[:key_path] = authenticator.key_path
             raise ArgumentError, "missing key path" unless credentials[:key_path]
-
+          when JWTAuthenticator
+            credentials[:jwt] = authenticator.token
+            raise ArgumentError, "missing token" unless credentials[:jwt]
           else
             raise ArgumentError, "options must have authenticator configured"
           end
@@ -359,6 +415,35 @@ module Couchbase
       end
 
       @backend = Backend.new
+
+      @observability = Observability::Wrapper.new(backend: @backend) do |w|
+        w.tracer = if !open_options[:enable_tracing].nil? && !open_options[:enable_tracing]
+                     Tracing::NoopTracer.new
+                   elsif tracer.nil?
+                     Tracing::ThresholdLoggingTracer.new(
+                       emit_interval: open_options[:threshold_emit_interval],
+                       kv_threshold: open_options[:key_value_threshold],
+                       query_threshold: open_options[:query_threshold],
+                       views_threshold: open_options[:view_threshold],
+                       search_threshold: open_options[:search_threshold],
+                       analytics_threshold: open_options[:analytics_threshold],
+                       management_threshold: open_options[:management_threshold],
+                       sample_size: open_options[:threshold_sample_size],
+                     )
+                   else
+                     tracer
+                   end
+        w.meter = if !open_options[:enable_metrics].nil? && !open_options[:enable_metrics]
+                    Metrics::NoopMeter.new
+                  elsif meter.nil?
+                    Metrics::LoggingMeter.new(
+                      emit_interval: open_options[:metrics_emit_interval],
+                    )
+                  else
+                    meter
+                  end
+      end
+
       @backend.open(connection_string, credentials, open_options)
     end