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 the operation_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() and enable() 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

enable()[source]

Enable the recorder.

New in pywbem 0.10.

disable()[source]

Disable the recorder.

New in pywbem 0.10.

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:
  • filename (string) – Name of the file where the recorder output will be written
  • file_mode (string) – Optional file mode. The default is ‘w’ which overwrites any existing file. if ‘a’ is used, the data is appended to any existing file.
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_pywbem_result(ret, exc)[source]

Set Result return info or exception info

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

stage_http_response2(payload)[source]

Stage second part of http response, the payload

record_staged()[source]

Encode staged information on request and result to output

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 the WBEMConnection method that is recorded.
  • pywbem_result (OpResult) – The result (return value or exception) of the WBEMConnection 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).

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:

Create new instance of OpArgsTuple(method, args)

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)

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:

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:

  • 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().

toyaml(obj)[source]

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.

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 of WBEMConnection 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 from LOG_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.

stage_http_response2(payload)[source]

Log complete http response, including response1 and payload

record_staged()[source]

Not used for logging. The logs are output in the various stage… methods methods

record(pywbem_args, pywbem_result, http_request, http_response)[source]

Not used for logging