mongo 2.0.6 → 2.1.0

data/lib/mongo/monitoring/event/command_failed.rb

@@ -0,0 +1,96 @@
+# Copyright (C) 2015 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
+  class Monitoring
+    module Event
+
+      # Event that is fired when a command operation fails.
+      #
+      # @since 2.1.0
+      class CommandFailed
+
+        # @return [ Server::Address ] address The server address.
+        attr_reader :address
+
+        # @return [ String ] command_name The name of the command.
+        attr_reader :command_name
+
+        # @return [ String ] database_name The name of the database_name.
+        attr_reader :database_name
+
+        # @return [ Float ] duration The duration of the command in seconds.
+        attr_reader :duration
+
+        # @return [ String ] message The error message.
+        attr_reader :message
+
+        # @return [ Integer ] operation_id The operation id.
+        attr_reader :operation_id
+
+        # @return [ Integer ] request_id The request id.
+        attr_reader :request_id
+
+        # Create the new event.
+        #
+        # @example Create the event.
+        #
+        # @param [ String ] command_name The name of the command.
+        # @param [ String ] database_name The database_name name.
+        # @param [ Server::Address ] address The server address.
+        # @param [ Integer ] request_id The request id.
+        # @param [ Integer ] operation_id The operation id.
+        # @param [ String ] message The error message.
+        # @param [ Float ] duration The duration the command took in seconds.
+        #
+        # @since 2.1.0
+        def initialize(command_name, database_name, address, request_id, operation_id, message, duration)
+          @command_name = command_name
+          @database_name = database_name
+          @address = address
+          @request_id = request_id
+          @operation_id = operation_id
+          @message = message
+          @duration = duration
+        end
+
+        # Create the event from a wire protocol message payload.
+        #
+        # @example Create the event.
+        #   CommandFailed.generate(address, 1, payload, duration)
+        #
+        # @param [ Server::Address ] address The server address.
+        # @param [ Integer ] operation_id The operation id.
+        # @param [ Hash ] payload The message payload.
+        # @param [ String ] message The error message.
+        # @param [ Float ] duration The duration of the command in seconds.
+        #
+        # @return [ CommandFailed ] The event.
+        #
+        # @since 2.1.0
+        def self.generate(address, operation_id, payload, message, duration)
+          new(
+            payload[:command_name],
+            payload[:database_name],
+            address,
+            payload[:request_id],
+            operation_id,
+            message,
+            duration
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mongo/monitoring/event/command_started.rb

@@ -0,0 +1,89 @@
+# Copyright (C) 2015 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
+  class Monitoring
+    module Event
+
+      # Event that is fired when a command operation starts.
+      #
+      # @since 2.1.0
+      class CommandStarted
+        include Secure
+
+        # @return [ Server::Address ] address The server address.
+        attr_reader :address
+
+        # @return [ BSON::Document ] command The command arguments.
+        attr_reader :command
+
+        # @return [ String ] command_name The name of the command.
+        attr_reader :command_name
+
+        # @return [ String ] database_name The name of the database_name.
+        attr_reader :database_name
+
+        # @return [ Integer ] operation_id The operation id.
+        attr_reader :operation_id
+
+        # @return [ Integer ] request_id The request id.
+        attr_reader :request_id
+
+        # Create the new event.
+        #
+        # @example Create the event.
+        #
+        # @param [ String ] command_name The name of the command.
+        # @param [ String ] database_name The database_name name.
+        # @param [ Server::Address ] address The server address.
+        # @param [ Integer ] request_id The request id.
+        # @param [ Integer ] operation_id The operation id.
+        # @param [ BSON::Document ] command The command arguments.
+        #
+        # @since 2.1.0
+        def initialize(command_name, database_name, address, request_id, operation_id, command)
+          @command_name = command_name
+          @database_name = database_name
+          @address = address
+          @request_id = request_id
+          @operation_id = operation_id
+          @command = redacted(command_name, command)
+        end
+
+        # Create the event from a wire protocol message payload.
+        #
+        # @example Create the event.
+        #   CommandStarted.generate(address, 1, payload)
+        #
+        # @param [ Server::Address ] address The server address.
+        # @param [ Integer ] operation_id The operation id.
+        # @param [ Hash ] payload The message payload.
+        #
+        # @return [ CommandStarted ] The event.
+        #
+        # @since 2.1.0
+        def self.generate(address, operation_id, payload)
+          new(
+            payload[:command_name],
+            payload[:database_name],
+            address,
+            payload[:request_id],
+            operation_id,
+            payload[:command]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mongo/monitoring/event/command_succeeded.rb

@@ -0,0 +1,118 @@
+# Copyright (C) 2015 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
+  class Monitoring
+    module Event
+
+      # Event that is fired when a command operation succeeds.
+      #
+      # @since 2.1.0
+      class CommandSucceeded
+        include Secure
+
+        # @return [ Server::Address ] address The server address.
+        attr_reader :address
+
+        # @return [ String ] command_name The name of the command.
+        attr_reader :command_name
+
+        # @return [ BSON::Document ] reply The command reply.
+        attr_reader :reply
+
+        # @return [ String ] database_name The name of the database.
+        attr_reader :database_name
+
+        # @return [ Float ] duration The duration of the event.
+        attr_reader :duration
+
+        # @return [ Integer ] operation_id The operation id.
+        attr_reader :operation_id
+
+        # @return [ Integer ] request_id The request id.
+        attr_reader :request_id
+
+        # Create the new event.
+        #
+        # @example Create the event.
+        #
+        # @param [ String ] command_name The name of the command.
+        # @param [ String ] database_name The database name.
+        # @param [ Server::Address ] address The server address.
+        # @param [ Integer ] request_id The request id.
+        # @param [ Integer ] operation_id The operation id.
+        # @param [ BSON::Document ] reply The command reply.
+        # @param [ Float ] duration The duration the command took in seconds.
+        #
+        # @since 2.1.0
+        def initialize(command_name, database_name, address, request_id, operation_id, reply, duration)
+          @command_name = command_name
+          @database_name = database_name
+          @address = address
+          @request_id = request_id
+          @operation_id = operation_id
+          @reply = redacted(command_name, reply)
+          @duration = duration
+        end
+
+        # Create the event from a wire protocol message payload.
+        #
+        # @example Create the event.
+        #   CommandSucceeded.generate(address, 1, command_payload, reply_payload, 0.5)
+        #
+        # @param [ Server::Address ] address The server address.
+        # @param [ Integer ] operation_id The operation id.
+        # @param [ Hash ] command_payload The command message payload.
+        # @param [ Hash ] reply_payload The reply message payload.
+        # @param [ Float ] duration The duration of the command in seconds.
+        #
+        # @return [ CommandCompleted ] The event.
+        #
+        # @since 2.1.0
+        def self.generate(address, operation_id, command_payload, reply_payload, duration)
+          new(
+            command_payload[:command_name],
+            command_payload[:database_name],
+            address,
+            command_payload[:request_id],
+            operation_id,
+            generate_reply(command_payload, reply_payload),
+            duration
+          )
+        end
+
+        private
+
+        def self.generate_reply(command_payload, reply_payload)
+          if reply_payload
+            reply = reply_payload[:reply]
+            if cursor = reply[:cursor]
+              if !cursor.key?(Collection::NS)
+                cursor.merge!(Collection::NS => namespace(command_payload))
+              end
+            end
+            reply
+          else
+            BSON::Document.new(Operation::Result::OK => 1)
+          end
+        end
+
+        def self.namespace(payload)
+          command = payload[:command]
+          "#{payload[:database_name]}.#{command[:collection] || command.values.first}"
+        end
+      end
+    end
+  end
+end

data/lib/mongo/monitoring/event/secure.rb

@@ -0,0 +1,58 @@
+# Copyright (C) 2015 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
+  class Monitoring
+    module Event
+
+      # Provides behaviour to redact sensitive information from commands and
+      # replies.
+      #
+      # @since 2.1.0
+      module Secure
+
+        # The list of commands that has the data redacted for security.
+        #
+        # @since 2.1.0
+        REDACTED_COMMANDS = [
+          'authenticate',
+          'saslStart',
+          'saslContinue',
+          'getnonce',
+          'createUser',
+          'updateUser',
+          'copydbgetnonce',
+          'copydbsaslstart',
+          'copydb'
+        ].freeze
+
+        # Redact secure information from the document if it's command is in the
+        # list.
+        #
+        # @example Get the redacted document.
+        #   secure.redacted(command_name, document)
+        #
+        # @param [ String, Symbol ] command_name The command name.
+        # @param [ BSON::Document ] document The document.
+        #
+        # @return [ BSON::Document ] The redacted document.
+        #
+        # @since 2.1.0
+        def redacted(command_name, document)
+          REDACTED_COMMANDS.include?(command_name.to_s) ? BSON::Document.new : document
+        end
+      end
+    end
+  end
+end

data/lib/mongo/monitoring/event.rb

@@ -0,0 +1,18 @@
+# Copyright (C) 2015 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.
+
+require 'mongo/monitoring/event/secure'
+require 'mongo/monitoring/event/command_started'
+require 'mongo/monitoring/event/command_succeeded'
+require 'mongo/monitoring/event/command_failed'

data/lib/mongo/monitoring/publishable.rb

@@ -0,0 +1,106 @@
+# Copyright (C) 2015 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
+  class Monitoring
+
+    # Defines behaviour for an object that can publish monitoring events.
+    #
+    # @since 2.1.0
+    module Publishable
+
+      # @return [ Monitoring ] monitoring The monitoring.
+      attr_reader :monitoring
+
+      # Publish a command event to the global monitoring.
+      #
+      # @example Publish a command event.
+      #   publish_command do |messages|
+      #     # ...
+      #   end
+      #
+      # @param [ Array<Message> ] messages The messages.
+      #
+      # @return [ Object ] The result of the yield.
+      #
+      # @since 2.1.0
+      def publish_command(messages, operation_id = Monitoring.next_operation_id)
+        start = Time.now
+        message = messages.first
+        message.set_request_id
+        payload = message.payload
+        send_duration = duration(start)
+        command_started(address, operation_id, payload)
+        receive_start = Time.now
+        begin
+          result = yield(messages)
+          total_duration = duration(receive_start) + send_duration
+          command_completed(result, address, operation_id, payload, total_duration)
+          result
+        rescue Exception => e
+          total_duration = duration(receive_start) + send_duration
+          command_failed(address, operation_id, payload, e.message, total_duration)
+          raise e
+        end
+      end
+
+      private
+
+      def command_started(address, operation_id, payload)
+        monitoring.started(
+          Monitoring::COMMAND,
+          Event::CommandStarted.generate(address, operation_id, payload)
+        )
+      end
+
+      def command_completed(result, address, operation_id, payload, duration)
+        document = result ? (result.documents || []).first : nil
+        if error?(document)
+          parser = Error::Parser.new(document)
+          command_failed(address, operation_id, payload, parser.message, duration)
+        else
+          command_succeeded(result, address, operation_id, payload, duration)
+        end
+      end
+
+      def command_succeeded(result, address, operation_id, payload, duration)
+        monitoring.succeeded(
+          Monitoring::COMMAND,
+          Event::CommandSucceeded.generate(
+            address,
+            operation_id,
+            payload,
+            result ? result.payload : nil,
+            duration
+          )
+        )
+      end
+
+      def command_failed(address, operation_id, payload, message, duration)
+        monitoring.failed(
+          Monitoring::COMMAND,
+          Event::CommandFailed.generate(address, operation_id, payload, message, duration)
+        )
+      end
+
+      def duration(start)
+        Time.now - start
+      end
+
+      def error?(document)
+        document && (document['ok'] == 0 || document.key?('$err'))
+      end
+    end
+  end
+end

data/lib/mongo/monitoring.rb

@@ -0,0 +1,195 @@
+# Copyright (C) 2015 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.
+
+require 'mongo/monitoring/event'
+require 'mongo/monitoring/publishable'
+require 'mongo/monitoring/command_log_subscriber'
+
+module Mongo
+
+  # The class defines behaviour for the performance monitoring API.
+  #
+  # @since 2.1.0
+  class Monitoring
+
+    # The command topic.
+    #
+    # @since 2.1.0
+    COMMAND = 'Command'.freeze
+
+    @@operation_id = 0
+    @@operation_id_lock = Mutex.new
+
+    # Used for generating unique operation ids to link events together.
+    #
+    # @example Get the next operation id.
+    #   Monitoring.next_operation_id
+    #
+    # @return [ Integer ] The next operation id.
+    #
+    # @since 2.1.0
+    def self.next_operation_id
+      @@operation_id_lock.synchronize do
+        @@operation_id += 1
+      end
+    end
+
+    # Provides behaviour around global subscribers.
+    #
+    # @since 2.1.0
+    module Global
+      extend self
+
+      # Subscribe a listener to an event topic.
+      #
+      # @example Subscribe to the topic.
+      #   Monitoring::Global.subscribe(QUERY, subscriber)
+      #
+      # @param [ String ] topic The event topic.
+      # @param [ Object ] subscriber The subscriber to handle the event.
+      #
+      # @since 2.1.0
+      def subscribe(topic, subscriber)
+        subscribers_for(topic).push(subscriber)
+      end
+
+      # Get all the global subscribers.
+      #
+      # @example Get all the global subscribers.
+      #   Monitoring::Global.subscribers
+      #
+      # @return [ Hash<String, Object> ] The subscribers.
+      #
+      # @since 2.1.0
+      def subscribers
+        @subscribers ||= {}
+      end
+
+      private
+
+      def subscribers_for(topic)
+        subscribers[topic] ||= []
+      end
+    end
+
+    # Initialize the monitoring.
+    #
+    # @api private
+    #
+    # @example Create the new monitoring.
+    #   Monitoring.new(:monitoring => true)
+    #
+    # @param [ Hash ] options The options.
+    #
+    # @since 2.1.0
+    def initialize(options = {})
+      if options[:monitoring] != false
+        Global.subscribers.each do |topic, subscribers|
+          subscribers.each do |subscriber|
+            subscribe(topic, subscriber)
+          end
+        end
+        subscribe(COMMAND, CommandLogSubscriber.new(options))
+      end
+    end
+
+    # Publish a started event.
+    #
+    # @example Publish a started event.
+    #   monitoring.started(COMMAND, event)
+    #
+    # @param [ String ] topic The event topic.
+    # @param [ Event ] event The event to publish.
+    #
+    # @since 2.1.0
+    def started(topic, event)
+      subscribers_for(topic).each{ |subscriber| subscriber.started(event) }
+    end
+
+    # Publish a succeeded event.
+    #
+    # @example Publish a succeeded event.
+    #   monitoring.succeeded(COMMAND, event)
+    #
+    # @param [ String ] topic The event topic.
+    # @param [ Event ] event The event to publish.
+    #
+    # @since 2.1.0
+    def succeeded(topic, event)
+      subscribers_for(topic).each{ |subscriber| subscriber.succeeded(event) }
+    end
+
+    # Publish a failed event.
+    #
+    # @example Publish a failed event.
+    #   monitoring.failed(COMMAND, event)
+    #
+    # @param [ String ] topic The event topic.
+    # @param [ Event ] event The event to publish.
+    #
+    # @since 2.1.0
+    def failed(topic, event)
+      subscribers_for(topic).each{ |subscriber| subscriber.failed(event) }
+    end
+
+    # Subscribe a listener to an event topic.
+    #
+    # @example Subscribe to the topic.
+    #   monitoring.subscribe(QUERY, subscriber)
+    #
+    # @param [ String ] topic The event topic.
+    # @param [ Object ] subscriber The subscriber to handle the event.
+    #
+    # @since 2.1.0
+    def subscribe(topic, subscriber)
+      subscribers_for(topic).push(subscriber)
+    end
+
+    # Get all the subscribers.
+    #
+    # @example Get all the subscribers.
+    #   monitoring.subscribers
+    #
+    # @return [ Hash<String, Object> ] The subscribers.
+    #
+    # @since 2.1.0
+    def subscribers
+      @subscribers ||= {}
+    end
+
+    # Determine if there are any subscribers for a particular event.
+    #
+    # @example Are there subscribers?
+    #   monitoring.subscribers?(COMMAND)
+    #
+    # @param [ String ] topic The event topic.
+    #
+    # @return [ true, false ] If there are subscribers for the topic.
+    #
+    # @since 2.1.0
+    def subscribers?(topic)
+      !subscribers_for(topic).empty?
+    end
+
+    private
+
+    def initialize_copy(original)
+      @subscribers = original.subscribers.dup
+    end
+
+    def subscribers_for(topic)
+      subscribers[topic] ||= []
+    end
+  end
+end