Skip to content

Commit

Permalink
Merge pull request #2675 from tseaver/logging-snippets
Browse files Browse the repository at this point in the history
Convert logging doctest examples to testable snippets.
  • Loading branch information
tseaver authored Nov 7, 2016
2 parents 9c68fdf + 42ecc7e commit 8b899d1
Show file tree
Hide file tree
Showing 4 changed files with 570 additions and 321 deletions.
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@
logging-entries
logging-metric
logging-sink
logging-stdlib-usage
logging-handlers
logging-transports-sync
logging-transports-thread
Expand Down
71 changes: 71 additions & 0 deletions docs/logging-stdlib-usage.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
Integration with Python logging module
--------------------------------------


It's possible to tie the Python :mod:`logging` module directly into Google Cloud Logging. To use it,
create a :class:`CloudLoggingHandler <google.cloud.logging.CloudLoggingHandler>` instance from your
Logging client.

.. code-block:: python
>>> import logging
>>> import google.cloud.logging # Don't conflict with standard logging
>>> from google.cloud.logging.handlers import CloudLoggingHandler
>>> client = google.cloud.logging.Client()
>>> handler = CloudLoggingHandler(client)
>>> cloud_logger = logging.getLogger('cloudLogger')
>>> cloud_logger.setLevel(logging.INFO) # defaults to WARN
>>> cloud_logger.addHandler(handler)
>>> cloud_logger.error('bad news')
.. note::

This handler by default uses an asynchronous transport that sends log entries on a background
thread. However, the API call will still be made in the same process. For other transport
options, see the transports section.

All logs will go to a single custom log, which defaults to "python". The name of the Python
logger will be included in the structured log entry under the "python_logger" field. You can
change it by providing a name to the handler:

.. code-block:: python
>>> handler = CloudLoggingHandler(client, name="mycustomlog")
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, as well as any other loggers created. However,
you must avoid infinite recursion from the logging calls the client itself makes. A helper
method :meth:`setup_logging <google.cloud.logging.handlers.setup_logging>` is provided to configure
this automatically:

.. code-block:: python
>>> import logging
>>> import google.cloud.logging # Don't conflict with standard logging
>>> from google.cloud.logging.handlers import CloudLoggingHandler, setup_logging
>>> client = google.cloud.logging.Client()
>>> handler = CloudLoggingHandler(client)
>>> logging.getLogger().setLevel(logging.INFO) # defaults to WARN
>>> setup_logging(handler)
>>> logging.error('bad news')
You can also exclude certain loggers:

.. code-block:: python
>>> setup_logging(handler, excluded_loggers=('werkzeug',)))
Python logging handler transports
==================================

The Python logging handler can use different transports. The default is
:class:`google.cloud.logging.handlers.BackgroundThreadTransport`.

1. :class:`google.cloud.logging.handlers.BackgroundThreadTransport` this is the default. It writes
entries on a background :class:`python.threading.Thread`.

1. :class:`google.cloud.logging.handlers.SyncTransport` this handler does a direct API call on each
logging statement to write the entry.

Loading

0 comments on commit 8b899d1

Please sign in to comment.