mongo 2.22.0 → 2.23.0

data/lib/mongo/tracing/open_telemetry/operation_tracer.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025-present MongoDB 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 Mongo
+  module Tracing
+    module OpenTelemetry
+      # OperationTracer is responsible for tracing MongoDB driver operations using OpenTelemetry.
+      #
+      # @api private
+      class OperationTracer
+        extend Forwardable
+
+        def_delegators :@parent_tracer,
+                       :cursor_context_map,
+                       :parent_context_for,
+                       :transaction_context_map,
+                       :transaction_map_key
+
+        # Initializes a new OperationTracer.
+        #
+        # @param otel_tracer [ OpenTelemetry::Trace::Tracer ] the OpenTelemetry tracer.
+        # @param parent_tracer [ Mongo::Tracing::OpenTelemetry::Tracer ] the parent tracer
+        #   for accessing shared context maps.
+        def initialize(otel_tracer, parent_tracer)
+          @otel_tracer = otel_tracer
+          @parent_tracer = parent_tracer
+        end
+
+        # Trace a MongoDB operation.
+        #
+        # Creates an OpenTelemetry span for the operation, capturing attributes such as
+        # database name, collection name, operation name, and cursor ID. The span is finished
+        # automatically when the operation completes or fails.
+        #
+        # @param operation [ Mongo::Operation ] the MongoDB operation to trace.
+        # @param operation_context [ Mongo::Operation::Context ] the context of the operation.
+        # @param op_name [ String | nil ] an optional name for the operation. If nil, the
+        #   operation class name is used.
+        #
+        # @yield the block representing the operation to be traced.
+        #
+        # @return [ Object ] the result of the operation.
+        #
+        # rubocop:disable Lint/RescueException
+        def trace_operation(operation, operation_context, op_name: nil, &block)
+          span = create_operation_span(operation, operation_context, op_name)
+          execute_with_span(span, operation, &block)
+        rescue Exception => e
+          handle_span_exception(span, e)
+          raise e
+        ensure
+          span&.finish
+        end
+        # rubocop:enable Lint/RescueException
+
+        private
+
+        # Creates an OpenTelemetry span for the operation.
+        #
+        # @param operation [ Mongo::Operation ] the operation.
+        # @param operation_context [ Mongo::Operation::Context ] the operation context.
+        # @param op_name [ String | nil ] optional operation name.
+        #
+        # @return [ OpenTelemetry::Trace::Span ] the created span.
+        def create_operation_span(operation, operation_context, op_name)
+          parent_context = parent_context_for(operation_context, operation.cursor_id)
+          @otel_tracer.start_span(
+            operation_span_name(operation, op_name),
+            attributes: span_attributes(operation, op_name),
+            with_parent: parent_context,
+            kind: :client
+          )
+        end
+
+        # Executes the operation block within the span context.
+        #
+        # @param span [ OpenTelemetry::Trace::Span ] the span.
+        # @param operation [ Mongo::Operation ] the operation.
+        #
+        # @yield the block to execute.
+        #
+        # @return [ Object ] the result of the block.
+        def execute_with_span(span, operation)
+          ::OpenTelemetry::Trace.with_span(span) do |s, c|
+            yield.tap do |result|
+              process_cursor_context(result, operation.cursor_id, c, s)
+            end
+          end
+        end
+
+        # Handles exception for the span.
+        #
+        # @param span [ OpenTelemetry::Trace::Span ] the span.
+        # @param exception [ Exception ] the exception.
+        def handle_span_exception(span, exception)
+          return unless span
+
+          span.record_exception(exception)
+          span.status = ::OpenTelemetry::Trace::Status.error(
+            "Unhandled exception of type: #{exception.class}"
+          )
+        end
+
+        # Returns the operation name from the provided name or operation class.
+        #
+        # @param operation [ Mongo::Operation ] the operation.
+        # @param op_name [ String | nil ] optional operation name.
+        #
+        # @return [ String ] the operation name in lowercase.
+        def operation_name(operation, op_name = nil)
+          op_name || operation.class.name.split('::').last.downcase
+        end
+
+        # Builds span attributes for the operation.
+        #
+        # @param operation [ Mongo::Operation ] the operation.
+        # @param op_name [ String | nil ] optional operation name.
+        #
+        # @return [ Hash ] OpenTelemetry span attributes following MongoDB semantic conventions.
+        def span_attributes(operation, op_name)
+          {
+            'db.system' => 'mongodb',
+            'db.namespace' => operation.db_name.to_s,
+            'db.collection.name' => collection_name(operation),
+            'db.operation.name' => operation_name(operation, op_name),
+            'db.operation.summary' => operation_span_name(operation, op_name),
+            'db.mongodb.cursor_id' => operation.cursor_id,
+          }.compact
+        end
+
+        # Processes cursor context after operation execution.
+        #
+        # Updates the cursor context map based on the result. Removes closed cursors
+        # and stores context for newly created cursors.
+        #
+        # @param result [ Object ] the operation result.
+        # @param cursor_id [ Integer | nil ] the cursor ID before the operation.
+        # @param context [ OpenTelemetry::Context ] the OpenTelemetry context.
+        # @param span [ OpenTelemetry::Trace::Span ] the current span.
+        def process_cursor_context(result, cursor_id, context, span)
+          return unless result.is_a?(Cursor)
+
+          if result.id.zero?
+            # If the cursor is closed, remove it from the context map.
+            cursor_context_map.delete(cursor_id)
+          elsif result.id && cursor_id.nil?
+            # New cursor created, store its context.
+            cursor_context_map[result.id] = context
+            span.set_attribute('db.mongodb.cursor_id', result.id)
+          end
+        end
+
+        # Extracts the collection name from the operation.
+        #
+        # @param operation [ Mongo::Operation ] the operation.
+        #
+        # @return [ String | nil ] the collection name, or nil if not applicable.
+        def collection_name(operation)
+          return operation.coll_name.to_s if operation.respond_to?(:coll_name) && operation.coll_name
+
+          extract_collection_from_spec(operation)
+        end
+
+        # Extracts collection name from operation spec based on operation type.
+        #
+        # @param operation [ Mongo::Operation ] the operation.
+        #
+        # @return [ String | nil ] the collection name, or nil if not found.
+        def extract_collection_from_spec(operation)
+          collection_key = collection_key_for_operation(operation)
+          return nil unless collection_key
+
+          value = if collection_key == :first_value
+                    operation.spec[:selector].values.first
+                  else
+                    operation.spec[:selector][collection_key]
+                  end
+          value&.to_s
+        end
+
+        # Returns the collection key for a given operation type.
+        #
+        # @param operation [ Mongo::Operation ] the operation.
+        #
+        # @return [ Symbol | nil ] the collection key symbol or nil.
+        def collection_key_for_operation(operation)
+          case operation
+          when Operation::Aggregate then :aggregate
+          when Operation::Count then :count
+          when Operation::Create then :create
+          when Operation::Distinct then :distinct
+          when Operation::Drop then :drop
+          when Operation::WriteCommand then :first_value
+          end
+        end
+
+        # Generates the span name for the operation.
+        #
+        # @param operation [ Mongo::Operation ] the operation.
+        # @param op_name [ String | nil ] optional operation name.
+        #
+        # @return [ String ] span name in format "operation_name db.collection" or "operation_name db".
+        def operation_span_name(operation, op_name = nil)
+          coll_name = collection_name(operation)
+          if coll_name && !coll_name.empty?
+            "#{operation_name(operation, op_name)} #{operation.db_name}.#{coll_name}"
+          else
+            "#{operation_name(operation, op_name)} #{operation.db_name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/tracing/open_telemetry/tracer.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025-present MongoDB 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 Mongo
+  module Tracing
+    module OpenTelemetry
+      # OpenTelemetry tracer for MongoDB operations and commands.
+      # @api private
+      class Tracer
+        # @return [ OpenTelemetry::Trace::Tracer ] the OpenTelemetry tracer implementation
+        #   used to create spans for MongoDB operations and commands.
+        #
+        # @api private
+        attr_reader :otel_tracer
+
+        # Initializes a new OpenTelemetry tracer.
+        #
+        # @param enabled [ Boolean | nil ] whether OpenTelemetry is enabled or not.
+        #   Defaults to nil, which means it will check the environment variable
+        #   OTEL_RUBY_INSTRUMENTATION_MONGODB_ENABLED (values: true/1/yes). If the
+        #   environment variable is not set, OpenTelemetry will be disabled by default.
+        # @param query_text_max_length [ Integer | nil ] maximum length for captured query text.
+        #   Defaults to nil, which means it will check the environment variable
+        #   OTEL_RUBY_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH. If the environment variable is not set,
+        #   the query text will not be captured.
+        # @param otel_tracer [ OpenTelemetry::Trace::Tracer | nil ] the OpenTelemetry tracer
+        #   implementation to use. Defaults to nil, which means it will use the default tracer
+        #   from OpenTelemetry's tracer provider.
+        def initialize(enabled: nil, query_text_max_length: nil, otel_tracer: nil)
+          @enabled = if enabled.nil?
+                       %w[true 1 yes].include?(ENV['OTEL_RUBY_INSTRUMENTATION_MONGODB_ENABLED']&.downcase)
+                     else
+                       enabled
+                     end
+          check_opentelemetry_loaded
+          @query_text_max_length = if query_text_max_length.nil?
+                                     ENV['OTEL_RUBY_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH'].to_i
+                                   else
+                                     query_text_max_length
+                                   end
+          @otel_tracer = otel_tracer || initialize_tracer
+          @operation_tracer = OperationTracer.new(@otel_tracer, self)
+          @command_tracer = CommandTracer.new(@otel_tracer, self, query_text_max_length: @query_text_max_length)
+        end
+
+        # Whether OpenTelemetry is enabled or not.
+        #
+        # @return [Boolean] true if OpenTelemetry is enabled, false otherwise.
+        def enabled?
+          @enabled
+        end
+
+        # Trace a MongoDB operation.
+        #
+        # @param operation [Mongo::Operation] The MongoDB operation to trace.
+        # @param operation_context [Mongo::Operation::Context] The context of the operation.
+        # @param op_name [String, nil] An optional name for the operation.
+        # @yield The block representing the operation to be traced.
+        # @return [Object] The result of the operation.
+        def trace_operation(operation, operation_context, op_name: nil, &block)
+          return yield unless enabled?
+
+          @operation_tracer.trace_operation(operation, operation_context, op_name: op_name, &block)
+        end
+
+        # Trace a MongoDB command.
+        #
+        # @param message [Mongo::Protocol::Message] The MongoDB command message to trace.
+        # @param operation_context [Mongo::Operation::Context] The context of the operation.
+        # @param connection [Mongo::Server::Connection] The connection used to send the command
+        # @yield The block representing the command to be traced.
+        # @return [Object] The result of the command.
+        def trace_command(message, operation_context, connection, &block)
+          return yield unless enabled?
+
+          @command_tracer.trace_command(message, operation_context, connection, &block)
+        end
+
+        # Start a transaction span and activate its context.
+        #
+        # @param session [Mongo::Session] The session starting the transaction.
+        def start_transaction_span(session)
+          return unless enabled?
+
+          key = transaction_map_key(session)
+          return unless key
+
+          # Create the transaction span with minimal attributes
+          span = @otel_tracer.start_span(
+            'transaction',
+            attributes: { 'db.system' => 'mongodb' },
+            kind: :client
+          )
+
+          # Create a context containing this span
+          context = ::OpenTelemetry::Trace.context_with_span(span)
+
+          # Activate the context and store the token for later detachment
+          token = ::OpenTelemetry::Context.attach(context)
+
+          # Store span, token, and context for later retrieval
+          transaction_span_map[key] = span
+          transaction_token_map[key] = token
+          transaction_context_map[key] = context
+        end
+
+        # Finish a transaction span and deactivate its context.
+        #
+        # @param session [Mongo::Session] The session finishing the transaction.
+        def finish_transaction_span(session)
+          return unless enabled?
+
+          key = transaction_map_key(session)
+          return unless key
+
+          span = transaction_span_map.delete(key)
+          token = transaction_token_map.delete(key)
+          transaction_context_map.delete(key)
+
+          return unless span && token
+
+          begin
+            span.finish
+          ensure
+            ::OpenTelemetry::Context.detach(token)
+          end
+        end
+
+        # Returns the cursor context map for tracking cursor-related OpenTelemetry contexts.
+        #
+        # @return [ Hash ] map of cursor IDs to OpenTelemetry contexts.
+        def cursor_context_map
+          @cursor_context_map ||= {}
+        end
+
+        # Generates a unique key for cursor tracking in the context map.
+        #
+        # @param session [ Mongo::Session ] the session associated with the cursor.
+        # @param cursor_id [ Integer ] the cursor ID.
+        #
+        # @return [ String | nil ] unique key combining session ID and cursor ID, or nil if either is nil.
+        def cursor_map_key(session, cursor_id)
+          return if cursor_id.nil? || session.nil?
+
+          "#{session.session_id['id'].to_uuid}-#{cursor_id}"
+        end
+
+        # Determines the parent OpenTelemetry context for an operation.
+        #
+        # Returns the transaction context if the operation is part of a transaction,
+        # otherwise returns nil. Cursor-based context nesting is not currently implemented.
+        #
+        # @param operation_context [ Mongo::Operation::Context ] the operation context.
+        # @param cursor_id [ Integer ] the cursor ID, if applicable.
+        #
+        # @return [ OpenTelemetry::Context | nil ] parent context or nil.
+        def parent_context_for(operation_context, cursor_id)
+          if (key = transaction_map_key(operation_context.session))
+            transaction_context_map[key]
+          elsif (_key = cursor_map_key(operation_context.session, cursor_id))
+            # We return nil here unless we decide how to nest cursor operations.
+            nil
+          end
+        end
+
+        # Returns the transaction context map for tracking active transaction contexts.
+        #
+        # @return [ Hash ] map of transaction keys to OpenTelemetry contexts.
+        def transaction_context_map
+          @transaction_context_map ||= {}
+        end
+
+        # Returns the transaction span map for tracking active transaction spans.
+        #
+        # @return [ Hash ] map of transaction keys to OpenTelemetry spans.
+        def transaction_span_map
+          @transaction_span_map ||= {}
+        end
+
+        # Returns the transaction token map for tracking context attachment tokens.
+        #
+        # @return [ Hash ] map of transaction keys to OpenTelemetry context tokens.
+        def transaction_token_map
+          @transaction_token_map ||= {}
+        end
+
+        # Generates a unique key for transaction tracking.
+        #
+        # Returns nil for implicit sessions or sessions not in a transaction.
+        #
+        # @param session [ Mongo::Session ] the session.
+        #
+        # @return [ String | nil ] unique key combining session ID and transaction number, or nil.
+        def transaction_map_key(session)
+          return if session.nil? || session.implicit? || !session.in_transaction?
+
+          "#{session.session_id['id'].to_uuid}-#{session.txn_num}"
+        end
+
+        private
+
+        def check_opentelemetry_loaded
+          return unless @enabled
+          return if defined?(::OpenTelemetry)
+
+          Logger.logger.warn('OpenTelemetry tracing for MongoDB is enabled, ' \
+                             'but the OpenTelemetry library is not loaded. ' \
+                             'Disabling tracing.')
+          @enabled = false
+        end
+
+        def initialize_tracer
+          return unless enabled?
+
+          ::OpenTelemetry.tracer_provider.tracer(
+            'mongo-ruby-driver',
+            Mongo::VERSION
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mongo/tracing/open_telemetry.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025-present MongoDB 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 Mongo
+  module Tracing
+    # This module contains OpenTelemetry tracing functionality for MongoDB operations.
+    module OpenTelemetry
+    end
+  end
+end
+
+require 'mongo/tracing/open_telemetry/command_tracer'
+require 'mongo/tracing/open_telemetry/operation_tracer'
+require 'mongo/tracing/open_telemetry/tracer'

data/lib/mongo/tracing.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025-present MongoDB 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 Mongo
+  # Provides OpenTelemetry tracing capabilities for MongoDB operations.
+  module Tracing
+    # Creates a new OpenTelemetry tracer for instrumenting MongoDB operations.
+    #
+    # @param enabled [Boolean, nil] Whether tracing is enabled. Default to nil, which
+    #   means it will check the environment variable OTEL_RUBY_INSTRUMENTATION_MONGODB_ENABLED.
+    #   See +Mongo::Tracing::OpenTelemetry::Tracer+ for details.
+    # @param query_text_max_length [Integer, nil] Maximum length for captured query text. Default to nil,
+    #   which means it will check the environment variable OTEL_RUBY_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH.
+    #   See +Mongo::Tracing::OpenTelemetry::Tracer+ for details.
+    # @param otel_tracer [OpenTelemetry::Trace::Tracer, nil] Custom OpenTelemetry tracer instance.
+    #
+    # @return [Mongo::Tracing::OpenTelemetry::Tracer] Configured tracer instance.
+    def create_tracer(enabled: nil, query_text_max_length: nil, otel_tracer: nil)
+      OpenTelemetry::Tracer.new(
+        enabled: enabled,
+        query_text_max_length: query_text_max_length,
+        otel_tracer: otel_tracer
+      )
+    end
+    module_function :create_tracer
+  end
+end
+
+require 'mongo/tracing/open_telemetry'

data/lib/mongo/uri/srv_protocol.rb

@@ -122,11 +122,13 @@ module Mongo
       end
 
       # Gets the SRV resolver.
+      # If domain verification fails or no SRV records are found,
+      # an error must not be raised per the spec; instead, a warning is logged.
       #
       # @return [ Mongo::Srv::Resolver ]
       def resolver
         @resolver ||= Srv::Resolver.new(
-          raise_on_invalid: true,
+          raise_on_invalid: false,
           resolv_options: options[:resolv_options],
           timeout: options[:connect_timeout],
         )
@@ -149,7 +151,11 @@ module Mongo
 
         log_debug "attempting to resolve #{hostname}"
 
-        @srv_result = resolver.get_records(hostname, uri_options[:srv_service_name], uri_options[:srv_max_hosts])
+        @srv_result = resolver.get_records(
+          hostname,
+          uri_options[:srv_service_name] || options[:srv_service_name],
+          uri_options[:srv_max_hosts] || options[:srv_max_hosts]
+        )
         if srv_result.empty?
           raise Error::NoSRVRecords.new(NO_SRV_RECORDS % hostname)
         end
@@ -168,8 +174,7 @@ module Mongo
       # The hostname cannot include a port.
       #
       # The hostname must not begin with a dot, end with a dot, or have
-      # consecutive dots. The hostname must have a minimum of 3 total
-      # components (foo.bar.tld).
+      # consecutive dots. The hostname must have a minimum of 1 component
       #
       # Raises Error::InvalidURI if validation fails.
       def validate_srv_hostname(hostname)
@@ -185,8 +190,8 @@ module Mongo
         if parts.any?(&:empty?)
           raise_invalid_error!("Hostname cannot have consecutive dots: #{hostname}")
         end
-        if parts.length < 3
-          raise_invalid_error!("Hostname must have a minimum of 3 components (foo.bar.tld): #{hostname}")
+        if parts.length < 1
+          raise_invalid_error!("Hostname cannot be empty: #{hostname}")
         end
       end
 

data/lib/mongo/version.rb

@@ -5,5 +5,5 @@ module Mongo
   #
   # Note that this file is automatically updated via `rake candidate:create`.
   # Manual changes to this file will be overwritten by that rake task.
-  VERSION = '2.22.0'
+  VERSION = '2.23.0'
 end

data/lib/mongo.rb

@@ -42,6 +42,7 @@ require 'mongo/condition_variable'
 require 'mongo/csot_timeout_holder'
 require 'mongo/options'
 require 'mongo/loggable'
+require 'mongo/deprecations'
 require 'mongo/cluster_time'
 require 'mongo/topology_version'
 require 'mongo/monitoring'
@@ -74,6 +75,7 @@ require 'mongo/session'
 require 'mongo/socket'
 require 'mongo/srv'
 require 'mongo/timeout'
+require 'mongo/tracing'
 require 'mongo/uri'
 require 'mongo/version'
 require 'mongo/write_concern'
@@ -100,6 +102,7 @@ module Mongo
     delegate_option Config, :broken_view_aggregate
     delegate_option Config, :broken_view_options
     delegate_option Config, :validate_update_replace
+    delegate_option Config, :csfle_convert_to_ruby_types
   end
 
   # Clears the driver's OCSP response cache.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongo
 version: !ruby/object:Gem::Version
-  version: 2.22.0
+  version: 2.23.0
 platform: ruby
 authors:
 - The MongoDB Ruby Team
@@ -193,6 +193,7 @@ files:
 - lib/mongo/database.rb
 - lib/mongo/database/view.rb
 - lib/mongo/dbref.rb
+- lib/mongo/deprecations.rb
 - lib/mongo/distinguishing_semaphore.rb
 - lib/mongo/error.rb
 - lib/mongo/error/auth_error.rb
@@ -520,6 +521,11 @@ files:
 - lib/mongo/srv/result.rb
 - lib/mongo/timeout.rb
 - lib/mongo/topology_version.rb
+- lib/mongo/tracing.rb
+- lib/mongo/tracing/open_telemetry.rb
+- lib/mongo/tracing/open_telemetry/command_tracer.rb
+- lib/mongo/tracing/open_telemetry/operation_tracer.rb
+- lib/mongo/tracing/open_telemetry/tracer.rb
 - lib/mongo/uri.rb
 - lib/mongo/uri/options_mapper.rb
 - lib/mongo/uri/srv_protocol.rb
@@ -553,7 +559,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.5
 specification_version: 4
 summary: Ruby driver for MongoDB
 test_files: []