Merge pull request #437 from splunk/DVPL-10608

added setup_logging() method in splunklib for logging and updated README.md files

Author: akaila-splunk

README.md

@@ -230,6 +230,19 @@ class GeneratorTest(GeneratingCommand):
         checkpoint_dir = inputs.metadata["checkpoint_dir"]
 ```
 
+#### Optional:Set up logging for splunklib
++ The default level is WARNING, which means that only events of this level and above will be visible
++ To change a logging level we can call setup_logging() method and pass the logging level as an argument.
++ Optional: we can also pass log format and date format string as a method argument to modify default format
+
+```python
+import logging
+from splunklib import setup_logging
+
+# To see debug and above level logs
+setup_logging(logging.DEBUG)
+```
+
 ### Changelog
 
 The [CHANGELOG](CHANGELOG.md) contains a description of changes for each version of the SDK. For the latest version, see the [CHANGELOG.md](https://github.com/splunk/splunk-sdk-python/blob/master/CHANGELOG.md) on GitHub.

examples/searchcommands_app/README.md

@@ -35,7 +35,7 @@ The app is tested on Splunk 5 and 6. Here is its manifest:
     └── default.meta ............. Permits the search assistant to use searchbnf.conf[6]
 ```
 **References**  
-[1] [app.conf](https://docs.splunk.com/Documentation/Splunk/latest/Admin/Appconf app.conf)  
+[1] [app.conf](https://docs.splunk.com/Documentation/Splunk/latest/Admin/Appconf)  
 [2] [commands.conf](https://docs.splunk.com/Documentation/Splunk/latest/Admin/Commandsconf)  
 [3] [Python Logging HOWTO](https://docs.python.org/2/howto/logging.html)  
 [4] [ConfigParser—Configuration file parser](https://docs.python.org/2/library/configparser.html)
@@ -110,6 +110,15 @@ word_counts |
 :-----|
 4497.0 |
 
+## Optional:Set up logging using logging.conf file
++ Inside the **default** directory of our app, we have a [logging.conf](https://github.com/splunk/splunk-sdk-python/blob/master/examples/searchcommands_app/package/default/logging.conf) file.
++ In logging.conf file we can define loggers, handlers and formatters for our app. refer [this doc](https://docs.python.org/2/library/logging.config.html#configuration-file-format) for more details
++ Logs will be written in the files specified in the handlers defined for the respective loggers
+  + For **'searchcommands_app'** app logs will be written in **searchcommands_app.log** and **splunklib.log** files defined in respective handlers, and are present at $SPLUNK_HOME/etc/apps/searchcommands_app/ dir
+  + By default logs will be written in the app's root directory, but it can be overriden by specifying the absolute path for the logs file in the conf file
++ By default, logging level is set to WARNING
++ To see debug and above level logs, Set level to DEBUG in logging.conf file
+
 ## License
 
 This software is licensed under the Apache License 2.0. Details can be found in

examples/searchcommands_app/package/default/logging.conf

@@ -96,3 +96,4 @@ keys = searchcommands
 
 [formatter_searchcommands]
 format = %(asctime)s, Level=%(levelname)s, Pid=%(process)s, Logger=%(name)s, File=%(filename)s, Line=%(lineno)s, %(message)s
+datefmt = %Y-%m-%d %H:%M:%S %Z

splunklib/__init__.py

@@ -16,5 +16,20 @@
 
 from __future__ import absolute_import
 from splunklib.six.moves import map
+import logging
+
+DEFAULT_LOG_FORMAT = '%(asctime)s, Level=%(levelname)s, Pid=%(process)s, Logger=%(name)s, File=%(filename)s, ' \
+                 'Line=%(lineno)s, %(message)s'
+DEFAULT_DATE_FORMAT = '%Y-%m-%d %H:%M:%S %Z'
+
+
+# To set the logging level of splunklib
+# ex. To enable debug logs, call this method with parameter 'logging.DEBUG'
+# default logging level is set to 'WARNING'
+def setup_logging(level, log_format=DEFAULT_LOG_FORMAT, date_format=DEFAULT_DATE_FORMAT):
+    logging.basicConfig(level=level,
+                        format=log_format,
+                        datefmt=date_format)
+
 __version_info__ = (1, 6, 18)
 __version__ = ".".join(map(str, __version_info__))

splunklib/binding.py

@@ -47,6 +47,7 @@
 except ImportError as e:
     from xml.parsers.expat import ExpatError as ParseError
 
+logger = logging.getLogger(__name__)
 
 __all__ = [
     "AuthenticationError",
@@ -68,7 +69,7 @@ def new_f(*args, **kwargs):
         start_time = datetime.now()
         val = f(*args, **kwargs)
         end_time = datetime.now()
-        logging.debug("Operation took %s", end_time-start_time)
+        logger.debug("Operation took %s", end_time-start_time)
         return val
     return new_f
 
@@ -616,7 +617,7 @@ def delete(self, path_segment, owner=None, app=None, sharing=None, **query):
         """
         path = self.authority + self._abspath(path_segment, owner=owner,
                                               app=app, sharing=sharing)
-        logging.debug("DELETE request to %s (body: %s)", path, repr(query))
+        logger.debug("DELETE request to %s (body: %s)", path, repr(query))
         response = self.http.delete(path, self._auth_headers, **query)
         return response
 
@@ -679,7 +680,7 @@ def get(self, path_segment, owner=None, app=None, headers=None, sharing=None, **
 
         path = self.authority + self._abspath(path_segment, owner=owner,
                                               app=app, sharing=sharing)
-        logging.debug("GET request to %s (body: %s)", path, repr(query))
+        logger.debug("GET request to %s (body: %s)", path, repr(query))
         all_headers = headers + self.additional_headers + self._auth_headers
         response = self.http.get(path, all_headers, **query)
         return response
@@ -757,7 +758,7 @@ def post(self, path_segment, owner=None, app=None, sharing=None, headers=None, *
             headers = []
 
         path = self.authority + self._abspath(path_segment, owner=owner, app=app, sharing=sharing)
-        logging.debug("POST request to %s (body: %s)", path, repr(query))
+        logger.debug("POST request to %s (body: %s)", path, repr(query))
         all_headers = headers + self.additional_headers + self._auth_headers
         response = self.http.post(path, all_headers, **query)
         return response
@@ -826,7 +827,7 @@ def request(self, path_segment, method="GET", headers=None, body={},
                             app=app, sharing=sharing)
 
         all_headers = headers + self.additional_headers + self._auth_headers
-        logging.debug("%s request to %s (headers: %s, body: %s)",
+        logger.debug("%s request to %s (headers: %s, body: %s)",
                       method, path, str(all_headers), repr(body))
 
         if body:

splunklib/client.py

@@ -75,6 +75,8 @@
                       namespace)
 from .data import record
 
+logger = logging.getLogger(__name__)
+
 __all__ = [
     "connect",
     "NotSupportedError",
@@ -1476,7 +1478,7 @@ def iter(self, offset=0, count=None, pagesize=None, **kwargs):
             if pagesize is None or N < pagesize:
                 break
             offset += N
-            logging.debug("pagesize=%d, fetched=%d, offset=%d, N=%d, kwargs=%s", pagesize, fetched, offset, N, kwargs)
+            logger.debug("pagesize=%d, fetched=%d, offset=%d, N=%d, kwargs=%s", pagesize, fetched, offset, N, kwargs)
 
     # kwargs: count, offset, search, sort_dir, sort_key, sort_mode
     def list(self, count=None, **kwargs):
@@ -2545,9 +2547,9 @@ def list(self, *kinds, **kwargs):
             kinds = self.kinds
         if len(kinds) == 1:
             kind = kinds[0]
-            logging.debug("Inputs.list taking short circuit branch for single kind.")
+            logger.debug("Inputs.list taking short circuit branch for single kind.")
             path = self.kindpath(kind)
-            logging.debug("Path for inputs: %s", path)
+            logger.debug("Path for inputs: %s", path)
             try:
                 path = UrlEncoded(path, skip_encode=True)
                 response = self.get(path, **kwargs)