diff --git a/docs/changelog.rst b/docs/changelog.rst index 5422f113..58d7f272 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -6,6 +6,8 @@ Changelog Development =========== - (Fill this out as you fix issues and develop your features). +- Documentation improvements: + - Documented how `pymongo.monitoring` can be used to log all queries issued by MongoEngine to the driver. - BREAKING CHANGE: ``class_check`` and ``read_preference`` keyword arguments are no longer available when filtering a ``QuerySet``. #2112 - Instead of ``Doc.objects(foo=bar, read_preference=...)`` use ``Doc.objects(foo=bar).read_preference(...)``. - Instead of ``Doc.objects(foo=bar, class_check=False)`` use ``Doc.objects(foo=bar).clear_cls_query(...)``. diff --git a/docs/guide/index.rst b/docs/guide/index.rst index 46eb7af2..a0364ec1 100644 --- a/docs/guide/index.rst +++ b/docs/guide/index.rst @@ -13,4 +13,5 @@ User Guide gridfs signals text-indexes + logging-monitoring mongomock diff --git a/docs/guide/logging-monitoring.rst b/docs/guide/logging-monitoring.rst new file mode 100644 index 00000000..9f523b79 --- /dev/null +++ b/docs/guide/logging-monitoring.rst @@ -0,0 +1,80 @@ +================== +Logging/Monitoring +================== + +It is possible to use `pymongo.monitoring `_ to monitor +the driver events (e.g: queries, connections, etc). This can be handy if you want to monitor the queries issued by +MongoEngine to the driver. + +To use `pymongo.monitoring` with MongoEngine, you need to make sure that you are registering the listeners +**before** establishing the database connection (i.e calling `connect`): + +The following snippet provides a basic logging of all command events: + +.. code-block:: python + + import logging + from pymongo import monitoring + from mongoengine import * + + log = logging.getLogger() + log.setLevel(logging.DEBUG) + logging.basicConfig(level=logging.DEBUG) + + + class CommandLogger(monitoring.CommandListener): + + def started(self, event): + log.debug("Command {0.command_name} with request id " + "{0.request_id} started on server " + "{0.connection_id}".format(event)) + + def succeeded(self, event): + log.debug("Command {0.command_name} with request id " + "{0.request_id} on server {0.connection_id} " + "succeeded in {0.duration_micros} " + "microseconds".format(event)) + + def failed(self, event): + log.debug("Command {0.command_name} with request id " + "{0.request_id} on server {0.connection_id} " + "failed in {0.duration_micros} " + "microseconds".format(event)) + + monitoring.register(CommandLogger()) + + + class Jedi(Document): + name = StringField() + + + connect() + + + log.info('GO!') + + log.info('Saving an item through MongoEngine...') + Jedi(name='Obi-Wan Kenobii').save() + + log.info('Querying through MongoEngine...') + obiwan = Jedi.objects.first() + + log.info('Updating through MongoEngine...') + obiwan.name = 'Obi-Wan Kenobi' + obiwan.save() + + +Executing this prints the following output:: + + INFO:root:GO! + INFO:root:Saving an item through MongoEngine... + DEBUG:root:Command insert with request id 1681692777 started on server ('localhost', 27017) + DEBUG:root:Command insert with request id 1681692777 on server ('localhost', 27017) succeeded in 562 microseconds + INFO:root:Querying through MongoEngine... + DEBUG:root:Command find with request id 1714636915 started on server ('localhost', 27017) + DEBUG:root:Command find with request id 1714636915 on server ('localhost', 27017) succeeded in 341 microseconds + INFO:root:Updating through MongoEngine... + DEBUG:root:Command update with request id 1957747793 started on server ('localhost', 27017) + DEBUG:root:Command update with request id 1957747793 on server ('localhost', 27017) succeeded in 455 microseconds + +More details can of course be obtained by checking the `event` argument from the `CommandListener`.