Add Logging Handler

Author: Bill Prin

docs/index.rst

@@ -109,6 +109,7 @@
   logging-entries
   logging-metric
   logging-sink
+  logging-handlers
 
 .. toctree::
   :maxdepth: 0

docs/logging-handlers.rst

@@ -0,0 +1,7 @@
+Logger
+======
+
+.. automodule:: gcloud.logging.handlers
+  :members:
+  :show-inheritance:
+

docs/logging-usage.rst

@@ -314,3 +314,32 @@ Delete a sink:
    >>> sink.delete()  # API call
    >>> sink.exists()  # API call
    False
+
+Python Logging Integration:
+
+It's possible to tie the Python `logging` module directly into Google Cloud Logging. To use it, create a :class:`CloudLoggingAPIHandler <gcloud.logging.CloudLoggingAPIHandler` instance from your Logging client.
+
+.. doctest::
+    >>> import logging
+    >>> import gcloud.logging # Don't conflict with standard logging
+    >>> from gcloud.logging.handlers import CloudLoggingAPIHandler
+    >>> client = logging.Client()
+    >>> handler = CloudLoggingAPIHandler(client)
+    >>> cloud_logger = logging.getLogger('cloudLogger')
+    >>> cloud_logger.setLevel(logging.INFO) # defaults to WARN
+    >>> cloud_logger.addHandler(handler)
+    >>> cloud_logger.error('bad news') # API call
+
+Note that this handler currently only supports a synchronous API call, which means each logging statement that uses this handler will require an API call.
+
+It is also possible to attach the handler to the root Python logger, so that for example a plain `logging.warn` call would be sent to Cloud Logging. However, you must avoid infinite recursion from the logging calls the client itself makes. A helper method :meth:`setup_logging <gcloud.logging.handlers.setup_logging` is provided to configure this automatically: 
+
+.. doctest::
+    >>> import logging
+    >>> import gcloud.logging # Don't conflict with standard logging 
+    >>> from gcloud.logging.handlers import CloudLoggingAPIHandler, setup_logging
+    >>> client = gcloud.logging.Client()
+    >>> handler = CloudLoggingAPIHandler(client)
+    >>> logging.getLogger().setLevel(logging.INFO) # defaults to WARN
+    >>> setup_logging(handler)
+    >>> logging.error('bad news') # API call

gcloud/logging/handlers.py

@@ -0,0 +1,102 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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.
+
+"""Google Cloud Logging API Logging handlers."""
+
+import logging
+
+EXCLUDE_LOGGER_DEFAULTS = (
+    'gcloud',
+    'oauth2client.client'
+)
+
+
+class CloudLoggingAPIHandler(logging.StreamHandler):
+    """Python standard logging handler to log messages to the Google Cloud
+    Logging API.
+
+    This handler can be used to route Python standard logging messages to
+    Google Cloud logging.
+
+    Note that this handler currently only supports a synchronous API call,
+    which means each logging statement that uses this handler will require
+    an API call.
+
+    :type client: :class:`gcloud.logging.client`
+    :param client: the authenticated gcloud logging client for this handler
+                   to use
+
+    Example:
+        import gcloud.logging
+        from gcloud.logging.handlers import CloudLoggingAPIHandler
+
+        client = gcloud.logging.Client()
+        handler = CloudLoggingAPIHandler(client)
+
+        cloud_logger = logging.getLogger('cloudLogger')
+        cloud_logger.setLevel(logging.INFO)
+        cloud_logger.addHandler(handler)
+
+        cloud.logger.error("bad news") # API call
+    """
+
+    def __init__(self, client):
+        logging.StreamHandler.__init__(self)
+        self.client = client
+
+    def emit(self, record):
+        """
+        Overrides the default emit behavior of StreamHandler.
+
+        See: https://docs.python.org/2/library/logging.html#handler-objects
+        """
+        message = logging.StreamHandler.format(self, record)
+        logger = self.client.logger(record.name)
+        logger.log_struct({"message": message},
+                          severity=record.levelname)
+
+
+def setup_logging(handler, excluded_loggers=EXCLUDE_LOGGER_DEFAULTS):
+    """Helper function to attach the CloudLoggingAPI handler to the Python
+    root logger, while excluding loggers this library itself uses to avoid
+    infinite recursion
+
+    :type handler: :class:`logging.handler`
+    :param handler: the handler to attach to the global handler
+
+    :type excluded_loggers: list
+    :param excluded_loggers: the loggers to not attach the handler to. At a
+                             minimum this should include loggers that the
+                             handlers itself will call to avoid infinite
+                             recursion.
+
+    Example:
+        import logging
+        import gcloud.logging
+        from gcloud.logging.handlers import CloudLoggingAPIHandler
+
+        client = gcloud.logging.Client()
+        handler = CloudLoggingAPIHandler(client)
+        setup_logging(handler)
+        logging.getLogger().setLevel(logging.DEBUG)
+
+        logging.error("bad news") # API call
+    """
+    logger = logging.getLogger()
+    logger.addHandler(handler)
+    logger.addHandler(logging.StreamHandler())
+    for logger_name in excluded_loggers:
+        logger = logging.getLogger(logger_name)
+        logger.propagate = False
+        logger.addHandler(logging.StreamHandler())

gcloud/logging/test_handlers.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python
+# Copyright 2016 Google Inc. All Rights Reserved.
+#
+# 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.
+
+import logging
+
+import unittest2
+
+
+class TestHandler(unittest2.TestCase):
+
+    PROJECT = 'PROJECT'
+
+    def _getTargetClass(self):
+        from gcloud.logging.handlers import CloudLoggingAPIHandler
+        return CloudLoggingAPIHandler
+
+    def _makeOne(self, *args, **kw):
+        return self._getTargetClass()(*args, **kw)
+
+    def test_ctor(self):
+        client = _Client(self.PROJECT)
+        handler = self._makeOne(client)
+        self.assertEqual(handler.client, client)
+
+    def test_emit(self):
+        client = _Client(self.PROJECT)
+        handler = self._makeOne(client)
+        LOGNAME = 'loggername'
+        MESSAGE = 'hello world'
+        record = _Record(LOGNAME, logging.INFO, MESSAGE)
+        handler.emit(record)
+        self.assertEqual(client.logger(LOGNAME).log_struct_called_with,
+                         ({'message': MESSAGE}, logging.INFO))
+
+
+class TestSetupLogging(unittest2.TestCase):
+
+    def _callFUT(self, handler, excludes=None):
+        from gcloud.logging.handlers import setup_logging
+        if excludes:
+            return setup_logging(handler, excluded_loggers=excludes)
+        else:
+            return setup_logging(handler)
+
+    def test_setup_logging(self):
+        handler = _Handler(logging.INFO)
+        self._callFUT(handler)
+
+        root_handlers = logging.getLogger().handlers
+        self.assertIn(handler, root_handlers)
+
+    def test_setup_logging_excludes(self):
+        INCLUDED_LOGGER_NAME = 'includeme'
+        EXCLUDED_LOGGER_NAME = 'excludeme'
+
+        handler = _Handler(logging.INFO)
+        self._callFUT(handler, [EXCLUDED_LOGGER_NAME])
+
+        included_logger = logging.getLogger(INCLUDED_LOGGER_NAME)
+        self.assertTrue(included_logger.propagate)
+
+        excluded_logger = logging.getLogger(EXCLUDED_LOGGER_NAME)
+        self.assertNotIn(handler, excluded_logger.handlers)
+        self.assertFalse(excluded_logger.propagate)
+
+    def tearDown(self):
+        # cleanup handlers
+        root_handlers = logging.getLogger().handlers
+        for handler in root_handlers:
+            logging.getLogger().removeHandler(handler)
+
+
+class _Handler(object):
+
+    def __init__(self, level):
+        self.level = level
+
+    def acquire(self):
+        pass  # pragma: NO COVER
+
+    def release(self):
+        pass  # pragma: NO COVER
+
+
+class _Logger(object):
+
+    def log_struct(self, message, severity=None):
+        self.log_struct_called_with = (message, severity)
+
+
+class _Client(object):
+
+    def __init__(self, project):
+        self.project = project
+        self.logger_ = _Logger()
+
+    def logger(self, _):  # pylint: disable=unused-argument
+        return self.logger_
+
+
+class _Record(object):
+
+    def __init__(self, name, level, message):
+        self.name = name
+        self.levelname = level
+        self.message = message
+        self.exc_info = None
+        self.exc_text = None
+        self.stack_info = None
+
+    def getMessage(self):
+        return self.message