4.10. WBEM operation recording¶
The WBEM client library API provides the possibility to record the WBEM operations that are executed on a connection. WBEM Operation recording uses the classes and subclasses defined in WBEM operation recorders.
This is disabled by default and can be enabled by adding recorders to a
WBEMConnection
object with the method
add_operation_recorder()
.
Typical usage scenarios for various operation recorders are the tracing of WBEM operations, tracing of interactions with a WBEM server, or the generation of test cases.
Please note that the method of activating operation recorders changed starting
with pywbem 0.11.0 and the addition of a second recorder. See
add_operation_recorder()
for more information.
This adds the recorder defined in the method call to a list of active recorders
in the WBEMConnection
object. All active recorders are called
for each WBEM operation on a connection.
A recorder can be be disabled with
disable()
method and enabled with
enable()
method.
The following example activates the TestClientRecorder
recorder for a connection:
conn = WBEMConnection(...)
# Add a TestClientRecorder to the connection
yamlfp = TestClientRecorder.open_file(self.yamlfile, 'a')
tc_recorder = TestClientRecorder(yamlfp)
conn.add_operation_recorder(tc_recorder)
# TestClientRecorder is now active and will record WBEM operations
# on that connection.
. . .
# Disable the TestClientRecorder
tc_recorder.disable()
Note that the LogOperationRecorder
is dealt with through
the logging functions described in WBEM operation logging, and should
not be added to a conneciton by pywbem users.
Activated recorders can be computing-wise expensive so it is best not to activate a recorder unless it is to be used for that specific WBEMConnection.
The enable()
and
disable()
methods simply set
flags to bypass creating the final recorder output so activating and disabling
is still more compute-wise expensive than not activating a recorder at all.
4.10.1. WBEM operation recorders¶
The WBEM client library API includes the abstract base class
BaseOperationRecorder
from which operation recorders can be
written that perform specific recording tasks.
Users can write their own operation recorder classes based upon the
abstract base class BaseOperationRecorder
.
The WBEM client library API provides the following operation recorder classes:
Class | Purpose |
---|---|
TestClientRecorder |
Generate test cases for the test_client unit test module. |
LogOperationRecorder |
Generate logs using the Python logging
facility for
WBEMConnection
methods that communicate with a
WBEM server. |
-
class
pywbem.
BaseOperationRecorder
[source]¶ Abstract base class defining the interface to an operation recorder, that records the WBEM operations executed in a connection to a WBEM server.
Experimental: New in pywbem 0.9 as experimental.
An operation recorder can be added to a connection via the
add_operation_recorder()
method. The operation recorders of a connection can be retrieved via theoperation_recorders
property.Each operation that is executed on a connection will cause the
record()
method of those operation recorders of the connection to be called, that are enabled.After being added to a connection, an operation recorder is enabled. It can be disabled and re-enabled using the
disable()
andenable()
methods, respectively. This can be used to temporarily pause the recorder.Methods
disable
Disable the recorder. enable
Enable the recorder. open_file
A static convenience function that performs the open of the recorder file correctly for different versions of Python. record
Function that is called to record a single WBEM operation, i.e. record_staged
Encode staged information on request and result to output reset
Reset all the attributes in the class. stage_http_request
Set request HTTP information including url, headers, etc. stage_http_response1
Set response http info including headers, status, etc. stage_http_response2
Stage second part of http response, the payload stage_pywbem_args
Set requst method and all args. stage_pywbem_result
Set Result return info or exception info stage_wbem_connection
Stage information about the connection. Attributes
enabled
Indicate whether the recorder is enabled. Details
-
enabled
¶ Indicate whether the recorder is enabled.
New in pywbem 0.10.
-
static
open_file
(filename, file_mode='w')[source]¶ A static convenience function that performs the open of the recorder file correctly for different versions of Python.
New in pywbem 0.10.
This covers the issue where the file should be opened in text mode but that is done differently in Python 2 and Python 3.
The returned file-like object must be closed by the caller.
Parameters: Returns: File-like object.
Example:
recorder = TestClientRecorder(...) recorder_file = recorder.open_file('recorder.log') . . . # Perform WBEM operations using the recorder recorder_file.close()
-
reset
(pull_op=None)[source]¶ Reset all the attributes in the class. This also allows setting the pull_op attribute that defines whether the operation is to be a traditional or pull operation. This does NOT reset _conn.id as that exists through the life of the connection.
-
stage_wbem_connection
(wbem_connection)[source]¶ Stage information about the connection. Used only by LogOperationRecorder.
-
stage_pywbem_args
(method, **kwargs)[source]¶ Set requst method and all args. Normally called before the cmd is executed to record request parameters
-
stage_http_request
(conn_id, version, url, target, method, headers, payload)[source]¶ Set request HTTP information including url, headers, etc.
-
stage_http_response1
(conn_id, version, status, reason, headers)[source]¶ Set response http info including headers, status, etc. conn_id unused here. Used in log
-
record
(pywbem_args, pywbem_result, http_request, http_response)[source]¶ Function that is called to record a single WBEM operation, i.e. the invocation of a single
WBEMConnection
method.This function is called only when the recorder is enabled, i.e. it does not need to check for recorder enablement.
Parameters: - pywbem_args (
OpArgs
) – The name and input arguments of theWBEMConnection
method that is recorded. - pywbem_result (
OpResult
) – The result (return value or exception) of theWBEMConnection
method that is recorded. - http_request (
HttpRequest
) –The HTTP request sent by the
WBEMConnection
method that is recorded.None, if no HTTP request had been sent (e.g. because an exception was raised before getting there).
- http_response (
HttpResponse
) –The HTTP response received by the
WBEMConnection
method that is recorded.None, if no HTTP response had been received (e.g. because an exception was raised before getting there).
- pywbem_args (
-
-
class
pywbem.
OpArgs
[source]¶ A named tuple representing the name and input arguments of the invocation of a
WBEMConnection
method.Experimental: New in pywbem 0.9 as experimental.
Variables: - method (unicode string) – Name of the
WBEMConnection
method. - args (
dict
) – Dictionary of input arguments (both positional and keyword-based).
Create new instance of OpArgsTuple(method, args)
- method (unicode string) – Name of the
-
class
pywbem.
OpResult
[source]¶ A named tuple representing the result of the invocation of a
WBEMConnection
method.Experimental: New in pywbem 0.9 as experimental.
Variables: - ret (
object
) –Return value, if the method returned. None, if the method raised an exception.
Note that None may be a legitimate return value, so the test for exceptions should be done based upon the
exc
variable. - exc (
Exception
) – Exception object, if the method raised an exception. None, if the method returned.
Create new instance of OpResultTuple(ret, exc)
- ret (
-
class
pywbem.
HttpRequest
[source]¶ A named tuple representing the HTTP request sent by the WBEM client.
Experimental: New in pywbem 0.9 as experimental.
Variables: - version (number) – HTTP version from the request line (10 for HTTP/1.0, 11 for HTTP/1.1).
- url (unicode string) – URL of the WBEM server (e.g. ‘https://myserver.acme.com:15989’).
- target (unicode string) – Target URL segment as stated in request line (e.g. ‘/cimom’).
- method (unicode string) – HTTP method as stated in the request line (e.g. “POST”).
- headers (
dict
) –A dictionary of all HTTP header fields:
- key (unicode string): Name of the header field
- value (unicode string): Value of the header field
- payload (unicode string) – HTTP payload, i.e. the CIM-XML string.
Create new instance of HttpRequestTuple(version, url, target, method, headers, payload)
-
class
pywbem.
HttpResponse
[source]¶ A named tuple representing the HTTP response received by the WBEM client.
Experimental: New in pywbem 0.9 as experimental.
Variables: - version (number) – HTTP version from the response line (10 for HTTP/1.0, 11 for HTTP/1.1).
- status (number) – HTTP status code from the response line (e.g. 200).
- reason (unicode string) – HTTP reason phrase from the response line (e.g. “OK”).
- headers (
dict
) –A dictionary of all HTTP header fields:
- key (unicode string): Name of the header field
- value (unicode string): Value of the header field
- payload (unicode string) – HTTP payload, i.e. the CIM-XML string.
Create new instance of HttpResponseTuple(version, status, reason, headers, payload)
-
class
pywbem.
TestClientRecorder
(fp)[source]¶ An operation recorder that generates test cases for each recorded operation.
Experimental: New in pywbem 0.9 as experimental.
The test cases are in the YAML format suitable for the test_client unit test module of the pywbem project.
Parameters: fp (file) – An open file that each test case will be written to. This file should have been opened in text mode.
Since there are differences between python 2 and 3 in opening files in text mode, the static method
open_file()
can be used to open the file or python 2/3 compatible open:from io import open f = open('blah.log', encoding='utf-8')
Example:
recorder = TestClientRecorder( BaseOperationRecorder.open_file('recorder.log'))
Methods
disable
Disable the recorder. enable
Enable the recorder. open_file
A static convenience function that performs the open of the recorder file correctly for different versions of Python. record
Function that records the invocation of a single WBEMConnection
method, by appending a corresponding test case to the file.record_staged
Encode staged information on request and result to output reset
Reset all the attributes in the class. stage_http_request
Set request HTTP information including url, headers, etc. stage_http_response1
Set response http info including headers, status, etc. stage_http_response2
Stage second part of http response, the payload stage_pywbem_args
Set requst method and all args. stage_pywbem_result
Set Result return info or exception info stage_wbem_connection
Stage information about the connection. toyaml
Convert any allowable input argument to or return value from an operation method to an object that is ready for serialization into test_client yaml format. Attributes
EXCLUDE_REQUEST_HEADERS
EXCLUDE_RESPONSE_HEADERS
TESTCASE_PASSWORD
TESTCASE_URL
TESTCASE_USER
enabled
Indicate whether the recorder is enabled. Details
-
record
(pywbem_args, pywbem_result, http_request, http_response)[source]¶ Function that records the invocation of a single
WBEMConnection
method, by appending a corresponding test case to the file.Parameters: See
pywbem.BaseOperationRecorder.record()
.
-
-
class
pywbem.
LogOperationRecorder
(conn_id, detail_levels=None)[source]¶ A recorder that logs certain aspects of the WBEM operations driven by pywbem users to Python loggers.
Experimental: New in pywbem 0.11 and redesigned in pywbem 0.12 as experimental.
This recorder supports two Python loggers:
- API logger (Python logger name: ‘pywbem.api’) - Logs API calls and
returns, for the
WBEMConnection
methods that drive WBEM operations (see WBEM operations). This logs the API parameters and results, including CIM objects/exceptions. It also logs the creation ofWBEMConnection
objects to capture connection information in order to determine the connection to which a particular log record belongs. - HTTP logger (Python logger name: ‘pywbem.http’) - Logs HTTP requests and responses between the pywbem client and WBEM server. This logs the HTTP request data and response data including HTTP headers and CIM-XML payload.
All logging calls are at the
logging.DEBUG
logging level.Parameters: - conn_id (connection id) – String that represents an id for a particular connection that is used to build the name of each logger. The logger names are uniqueqly idenfified by the conn_id suffix to the logger name (ex.pywbem.ops.1-2343) so that each WBEMConnection could be logged with a separate logger.
- detail_levels (
dict
) – Dictionary identifying the detail level for one or both of the loggers. Key: Simple logger name (e.g. ‘api’). Value: Detail level, either a string fromLOG_DETAIL_LEVELS
, or an integer that specifies the maximum size of each log record.
Methods
disable
Disable the recorder. enable
Enable the recorder. open_file
A static convenience function that performs the open of the recorder file correctly for different versions of Python. record
Not used for logging record_staged
Not used for logging. reset
Reset all the attributes in the class. set_detail_level
Sets the detail levels from the input dictionary in detail_levels. stage_http_request
Log request HTTP information including url, headers, etc. stage_http_response1
Set response http info including headers, status, etc. stage_http_response2
Log complete http response, including response1 and payload stage_pywbem_args
Log request method and all args. stage_pywbem_result
Log result return or exception parameter. stage_wbem_connection
Log connection information. Attributes
enabled
Indicate whether the recorder is enabled. Details
-
set_detail_level
(detail_levels)[source]¶ Sets the detail levels from the input dictionary in detail_levels.
-
stage_wbem_connection
(wbem_connection)[source]¶ Log connection information. This includes the connection id (conn_id) that is output with the log entry. This entry is logged if either http or api loggers are enable. It honors both the logger and detail level of either api logger if defined or http logger if defined. If the api logger does not exist, the output shows this as an http loggger output since we do not want to create an api logger for this specific output
-
stage_pywbem_args
(method, **kwargs)[source]¶ Log request method and all args. Normally called before the cmd is executed to record request parameters. This method does not support the summary detail_level because that seems to add little info to the log that is not also in the response.
-
stage_pywbem_result
(ret, exc)[source]¶ Log result return or exception parameter. This method provides varied type of formatting based on the detail_level parameter and the data in ret.
-
stage_http_request
(conn_id, version, url, target, method, headers, payload)[source]¶ Log request HTTP information including url, headers, etc.
-
stage_http_response1
(conn_id, version, status, reason, headers)[source]¶ Set response http info including headers, status, etc.
- API logger (Python logger name: ‘pywbem.api’) - Logs API calls and
returns, for the