Add configurable logging functionality (#20)

Add configurable logging functionality

Author: BenRKarl

README.rst

@@ -70,6 +70,51 @@ retrieve the corresponding service client instance:
 
   google_ads_service = client.get_service('GoogleAdsService')
 
+Enabling and Configuring logging
+################################
+The library uses Python's built in logging framework. You can specify your
+configuration via the configuration file; see `google-ads.yaml`_
+for an example. The library logs to ``stderr`` by default. You can easily pipe
+log messages to a file; when running an example:
+
+.. code-block:: bash
+
+  python example.py args 2> example.log
+
+It's also possible to configure logging programmatically using `Python's
+built-in logging library`_ by setting a logging configuration *before*
+initializing the client. You can retrieve the client logger instance and
+configure it with the following example:
+
+.. code-block:: python
+
+  logging.basicConfig(level=logging.INFO, format='[%(asctime)s - %(levelname)s] %(message).5000s')
+  logging.getLogger('google.ads.google_ads.client').setLevel(logging.INFO)
+
+**NOTE:** The client logger is configured when the client is initialized, so if
+you have logger configurations in your google-ads.yaml file and you want to
+override them programmatically, you will need to call the above lines _before_
+initializing the client, otherwise the configuration from yaml will take
+precedent as it's provided first.
+
+The client generates logs at a few different levels and you can set your
+configuration to see some or all of the below:
+
++-------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------+
+| Level       | Successful Request                                                 | Failed Request                                                                        |
++=============+====================================================================+=======================================================================================+
+| ``DEBUG``   | A detailed log with complete request and response objects as JSON. | None                                                                                  |
++-------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------+
+| ``INFO``    | A concise summary with specific request and response fields.       | A detailed log with complete request and exception objects as JSON.                   |
++-------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------+
+| ``WARNING`` | None                                                               | A concise summary with specific request information, the exception state and message. |
++-------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------+
+
+Since the Python logging framework ignores log messages that are less severe
+than the configured level, setting to ``WARNING`` means you will only see
+concise messages related to failed requests, but setting to ``DEBUG`` means
+you will see all possible types of logs in the above table.
+
 Miscellaneous
 -------------
 
@@ -83,16 +128,19 @@ Authors
 
 * `Mark Saniscalchi`_
 * `David Wihl`_
+* `Ben Karl`_
 
 .. _pip: https://pip.pypa.io/en/stable/installing
 .. _template: https://github.com/googleads/google-ads-python/blob/master/google-ads.yaml
 .. _Authorization guide: https://developers.google.com/google-ads/api/docs/oauth/overview
 .. _authentication samples: https://github.com/googleads/google-ads-python/blob/master/examples/authentication
 .. _Obtain your developer token: https://developers.google.com/google-ads/api/docs/first-call/dev-token
+.. _google-ads.yaml: https://github.com/googleads/google-ads-python/blob/master/google-ads.yaml
+.. _Python's built-in logging library: https://docs.python.org/2/library/logging.html
 .. _Wiki: https://github.com/googleads/google-ads-python/wiki
 .. _Issue tracker: https://github.com/googleads/google-ads-python/issues
 .. _API documentation: https://developers.google.com/google-ads/api/
 .. _API Support: https://developers.google.com/adwords/api/community/
 .. _Mark Saniscalchi: https://github.com/msaniscalchi
 .. _David Wihl: https://github.com/wihl
-
+.. _Ben Karl: https://github.com/BenRKarl

google-ads.yaml

@@ -8,3 +8,28 @@ refresh_token: INSERT_REFRESH_TOKEN_HERE
 # instead of 123-456-7890. You can also specify this later in code if your
 # application uses multiple manager account + OAuth pairs.
 login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
+
+# Logging configuration
+###############################################################################
+# Below you may specify the logging configuration. This will be provided as   #
+# an input to logging.config.dictConfig. Use the "level" block under the root #
+# logger configuration to adjust the logging level. Note in the "format"      #
+# field that log messages are truncated to 5000 characters by default. You    #
+# can change this to any length by removing the ".5000" portion or changing   #
+# it to a different number.                                                   #
+# #############################################################################
+# logging:
+  # version: 1
+  # disable_existing_loggers: False
+  # formatters:
+    # default_fmt:
+      # format: '[%(asctime)s - %(levelname)s] %(message).5000s'
+      # datefmt: '%Y-%m-%d %H:%M:%S'
+  # handlers:
+    # default_handler:
+      # class: logging.StreamHandler
+      # formatter: default_fmt
+  # loggers:
+    # "":
+      # handlers: [default_handler]
+      # level: INFO