Merge pull request #1372 from caphrim007/feature.add-low-level-api-call-tracing-property

Adds debug call tracing to the sdk

Author: f5-rahm

docs/userguide/debugging_api_calls.rst

@@ -0,0 +1,94 @@
+Debugging API calls
+===================
+
+New in version 3.0.10.
+
+.. toctree::
+
+The F5 SDK provides an abstraction on top of the actual F5 REST API. We've discussed in
+other pages, however, that this is a rather loose abstraction. In reality, it follows the
+actual API design a lot more than would be typical of other SDKs.
+
+Despite this close adherence to the API, there may come a time where users of the SDK
+(or tools built on top of it) need a more familiar set of information than method calls
+to debug a problem. For this purpose we've made available the `cURL` command equivalents
+that the F5 SDK makes.
+
+When the F5 SDK is used to make an API call, it will keep track of these calls and make
+them available to the user in an attribute of the ``ManagementRoot`` called `_debug`.
+
+Let's look at an example of how to trigger this tracing.
+
+Tracing calls
+-------------
+
+API tracing **always** happens. The trace information is available to you regardless of
+whether you ask for it or not. It is discarded, however, if you destroy the ``ManagementRoot``
+object.
+
+Consider the following SDK usage
+
+.. code-block:: python
+
+   from f5.bigip import ManagementRoot
+   mgmt = ManagementRoot('localhost', 'admin', 'admin', port=10443, token=True)
+   resource = mgmt.tm.ltm.pools.pool.create(name='foobar')
+
+This SDK call communicates with a BIG-IP to create an LTM pool. What if you needed to recreate
+this API call in a more familiar tool like cURL? How would you know what exactly the API
+called so that you could re-create the exact cURL command.
+
+Tools like Postman have a handy "Code" link to give you your actual API calls. The F5 SDK
+has a very similar feature that happens automatically under the hood for you.
+
+You can view the commands generated by the code above by printing the ``._debug`` property
+of the ``mgmt`` object. This property contains a list of items. Therefore, for readability,
+let's print each of them.
+
+.. code-block:: python
+
+   for x in mgmt._debug:
+       print(x)
+
+When this is done, we will be presented with output that resembles the following (printed for readability).
+
+.. code-block:: python
+
+   curl -k -X GET \
+     https://localhost:10443/mgmt/tm/sys/ \
+     -H 'Connection: keep-alive' \
+     -H 'Accept-Encoding: gzip, deflate' \
+     -H 'Accept: */*' \
+     -H 'User-Agent: python-requests/2.18.4 f5-icontrol-rest-python/1.3.4' \
+     -H 'Content-Type: application/json' \
+     -H 'X-F5-Auth-Token: 2PXGGMT4QR3Y3PAQEEURAPB5DJ'
+
+   curl -k -X POST \
+     https://localhost:10443/mgmt/tm/ltm/pool/ \
+     -H 'Connection: keep-alive' \
+     -H 'Accept-Encoding: gzip, deflate' \
+     -H 'Accept: */*' \
+     -H 'User-Agent: python-requests/2.18.4 f5-icontrol-rest-python/1.3.4' \
+     -H 'Content-Type: application/json' \
+     -H 'Content-Length: 18' \
+     -H 'X-F5-Auth-Token: 2PXGGMT4QR3Y3PAQEEURAPB5DJ' \
+     -d '{"name": "foobar"}'
+
+As you can see, there are a couple of commands there. In particular, the second command is the command that
+created the pool in the above SDK code.
+
+What about the first item in the list though. What is its relevance? This is an implementation detail of the
+SDK. To provide the functionality that it does, the SDK needs to know what version of the REST API is
+being used. This is accomplished by the first command there. From the response of that command, we get the
+version of the REST API.
+
+.. note::
+
+   The commands shown in the trace are only a convenient illustration of what the SDK is doing. The SDK
+   is **not** using cURL for the work it does.
+
+These commands are useful in exploring how the SDK actually behaves. One area where they come in particularly
+handy is in the process of debugging errors, or, in implementing new functionality.
+
+You can copy and paste the commands as they are printed and use them to issue the same API calls the the
+equivalent SDK code does.

f5/bigip/__init__.py

@@ -140,6 +140,13 @@ def tmos_version(self):
             self._meta_data['tmos_version'] = self._get_tmos_version()
         return self._meta_data['tmos_version']
 
+    @property
+    def _debug(self):
+        result = []
+        if self.icrs._debug:
+            result += self.icrs._debug
+        return result
+
 
 class ManagementRoot(BaseManagement):
     """An interface to a single BIG-IP"""

f5/bigip/test/functional/test__init__.py

@@ -42,3 +42,9 @@ def test_hard_timeout():
     with pytest.raises(TimeoutError) as ex:
         ManagementRoot('10.255.255.1', 'foo', 'bar', port=81, timeout=1)
     assert str(ex.value) == 'Timed out waiting for response'
+
+
+def test_icontrol_debug_tracing(opt_bigip, opt_username, opt_password, opt_port):
+    m = ManagementRoot(opt_bigip, opt_username, opt_password, port=opt_port)
+    m._debug
+    assert len(m._debug) > 0

f5/bigiq/__init__.py

@@ -75,3 +75,10 @@ def _get_os_version(self):
         response = connect.get(base_uri)
         version = response.json()['version']
         self._meta_data['tmos_version'] = version
+
+    @property
+    def _debug(self):
+        result = []
+        if self.icrs._debug:
+            result += self.icrs._debug
+        return result

requirements.test.txt

@@ -14,4 +14,4 @@ q
 pytest-xdist
 pycodestyle
 jinja2
-tox
+tox

setup_requirements.txt

@@ -2,4 +2,4 @@
 six>=1.9.0
 six<2.0.0
 f5-icontrol-rest>=1.3.2
-f5-icontrol-rest<2.0.0
+f5-icontrol-rest<2.0.0

tox.ini

@@ -25,6 +25,7 @@ setenv =
     PYTHONDONTWRITEBYTECODE = 1
 deps =
     -rrequirements.test.txt
+    git+https://github.com/F5Networks/f5-icontrol-rest-python.git@1.0
 
 # Used for whitelisting virtualenvs in different locations
 whitelist_externals=*
@@ -65,4 +66,4 @@ max-line-length = 160
 [pycodestyle]
 exclude = docs/conf.py,docs/userguide/code_example.py,docs/conf.py,.tox,.git,__pycache__,build,*.pyc,docs,devtools,*.tmpl
 ignore = E226,W503,E123,H304
-max-line-length = 160
+max-line-length = 160