4.8. WBEM operation statistics

New in pywbem 0.11 as experimental and finalized in 0.12.

Pywbem supports measuring the elapsed times of the WBEM operations that were performed in context of a connection, and maintaining a statistics over these times.

This capability is disabled by default and can be enabled in either of these ways:

The Statistics class maintains statistics over the measured elapsed times of the WBEM operations and is the interface for accessing the statistics. The statistics of a WBEMConnection object are accessible via its statistics instance attribute.

The OperationStatistic class is a helper class that contains the actual measurement data for one operation name. There will be one OperationStatistic object each operation name (see the table of WBEMConnection methods in the WBEM operations section for the operation names). The OperationStatistic objects are under control of the Statistics class.

The statistics support maintains two kinds of times for each kind of WBEM operation:

  • Client times: The elapsed times for the WBEMConnection operation methods from call to return. This is measured in pywbem pretty close to the API the pywbem user is calling.

  • Server times: The elapsed times for processing the WBEM operations in the WBEM server from receiving the CIM-XML request message to sending back the CIM-XML response message. The server times are not measured by pywbem, but are taken from the WBEMServerResponseTime HTTP header field of a CIM-XML response, if present. See DSP0200 for a description of this header field.

    The WBEMServerResponseTime HTTP header field is optionally implemented by WBEM servers. The following WBEM servers are known to implement this header field:

    • OpenPegasus

    Because the interpretation of the calculated average and min/max server times becomes incorrect if only a subset of the operations return the server response time, the statistics counting for the server time is suspended if one or more operations do not return the server response time. Resetting the statistics via reset() clears this condition again.

The difference between client time and server time is the time spent in the pywbem client, plus the time spent on the network between client and server.

The statistics support also maintains the size of the HTTP body in the CIM-XML request and response messages, in Bytes.

These times and sizes are maintained as average, minimum and maximum values for each kind of operation in a connection.

Finally, the statistics support maintains the total count of operations and the count of operations that failed, for each kind of operation.

All data in the statistics applies to WBEM operations performed during periods of time where the statistics are enabled on a connection. Operations performed during periods of time where the statistics are disabled on a connection, are simply ignored in the statistics.

For the Iter methods of WBEMConnection (e.g. IterEnumerateInstances()), the WBEM operations performed on behalf of them are subject of the statistics, but the Iter methods themselves do not show up in the statistics.

The following example shows how statistics are enabled, and how statistics values are accessed individually using the get_op_statistic() method:

conn = pywbem.WBEMConnection(..., stats_enabled=True)

# Perform some operations on this connection
insts_1 = conn.EnumerateInstances('CIM_Foo1', 'root/cimv2')
insts_2 = conn.EnumerateInstances('CIM_Foo2', 'root/cimv2')
insts_3 = conn.EnumerateInstances('CIM_Foo3', 'root/cimv2')
inst_paths_1 = conn.EnumerateInstanceNames('CIM_Foo1', 'root/cimv2')

# Access statistics values for EnumerateInstances
ei_stats = conn.statistics.get_op_statistic('EnumerateInstances')
ei_count = ei_stats.count
ei_avg_client_time = ei_stats.avg_time
ei_avg_server_time = ei_stats.avg_server_time

In the previous example, the values in ei_stats are “live”, i.e. they continue to be updated as operations are performed. If a snapshot is needed at a certain point in time that remains unaffected by further operations, this can be achieved using the snapshot() method:

# Take snapshot and access statistics values for EnumerateInstances
stats_snapshot = dict(conn.statistics.snapshot())
ei_stats = stats_snapshot['EnumerateInstances']
ei_count = ei_stats.count
ei_avg_client_time = ei_stats.avg_time
ei_avg_server_time = ei_stats.avg_server_time

It is also possible to simply print the current statistics of a connection as a formatted table, using the formatted() method:

# Print statistics values for all operations
print(conn.statistics.formatted())

The output could look like this, if the WBEM server returns WBEM server response times:

Statistics (times in seconds, lengths in Bytes):
Count Excep         ClientTime              ServerTime             RequestLen                ReplyLen       Operation
        Cnt     Avg     Min     Max     Avg     Min     Max    Avg    Min    Max      Avg      Min      Max
    3     0   0.234   0.100   0.401   0.204   0.080   0.361   1233   1000   1500    26667    20000    35000 EnumerateInstances
    1     0   0.100   0.100   0.100   0.080   0.080   0.080   1200   1200   1200    22000    22000    22000 EnumerateInstanceNames
class pywbem.Statistics(enable=False)[source]

New in pywbem 0.11 as experimental and finalized in 0.12.

The statistics of a connection, that captures and provides statistics data about the WBEM operations performed on the connection.

This class contains an operation statistic object (of class OperationStatistic) for each kind of WBEM operation.

A Statistics object can be in a state of enabled or disabled. If enabled, it accumulates the elapsed times between subsequent calls to the start_timer() and stop_timer() methods of class OperationStatistic. If disabled, calls to these methods do not accumulate any time. Initially, the statistics container is disabled.

The enablement state of the Statistics object is controlled by the statistics enablement state of the connection it belongs to (see pywbem.WBEMConnection.stats_enabled())

This class can also be used as a context manager.

Parameters:enable (bool) – Initial enablement status for this statistics container.

Methods

disable Disable the statistics container.
enable Enable the statistics container.
formatted Return a human readable string with the statistics for this container.
get_op_statistic Get the OperationStatistic object for an operation name or create a new object if an object for that name does not exist.
reset Reset all statistics and clear any statistic names.
snapshot Return a snapshot of the time statistics of this container.
start_timer This method is called by pywbem to start the timer for a particular operation execution.

Attributes

enabled Indicates whether the statistics container is enabled.

Details

__enter__()[source]

Enter method when the class is used as a context manager.

Starts the operation statistics for the name that was previously set via a call:

stats = Statistics()
with stats(name='bla'):
    # do something

The class supports nesting of context managers:

stats = Statistics()
with stats(name='bla1'):
    # do something
    for i in ...:
        with stats(name='bla2'):
            # do something
__exit__(exc_type, exc_value, traceback)[source]

Exit method when the class is used as a context manager.

Stops the operation statistics that was started in the enter method.

__call__(name)[source]

This allows the name parameter to be passed when the class is used as a context manager.

enabled

Indicates whether the statistics container is enabled.

enable()[source]

Enable the statistics container.

disable()[source]

Disable the statistics container.

start_timer(name)[source]

This method is called by pywbem to start the timer for a particular operation execution. It returns the corresponding OperationStatistic object, creating one if needed.

The timer is subsequently stopped by pywbem by calling the stop_timer() method on the returned OperationStatistic object.

Parameters:name (string) – Name of the operation.
Returns:The operation statistic for the specified name. If this statistics container is disabled, a dummy operation statistic object is returned.
Return type:OperationStatistic
get_op_statistic(name)[source]

Get the OperationStatistic object for an operation name or create a new object if an object for that name does not exist.

Parameters:name (string) – Name of the operation.
Returns:The operation statistic for the specified operation name. If this statistics container is disabled, a dummy operation statistic object is returned.
Return type:OperationStatistic
snapshot()[source]

Return a snapshot of the time statistics of this container.

The snapshot represents the statistics data at the time this method is called, and remains unchanged even if the statistics of this container continues to be updated.

Returns:A list of tuples (name, stats) with:
__repr__()[source]

Return a human readable display of the contents, for debug purposes.

formatted()[source]

Return a human readable string with the statistics for this container. The operations are sorted by decreasing average time.

The three columns for ServerTime are included only if the WBEM server has returned WBEM server response times for all operations.

The six columns for RequestLen and ReplyLen are included only if they are non-zero (this allows using this class for other purposes).

Example if statistics are enabled:

Statistics:
Count ExcCnt         Time [s]             ServerTime [s]        RequestLen [B]            ReplyLen [B]      Operation
                Avg     Min     Max     Avg     Min     Max    Avg    Min    Max      Avg      Min      Max
    3     0   0.234   0.100   0.401   0.204   0.080   0.361   1233   1000   1500    26667    20000    35000 EnumerateInstances
    1     0   0.100   0.100   0.100   0.080   0.080   0.080   1200   1200   1200    22000    22000    22000 EnumerateInstanceNames
    . . .

Example if statistics are disabled:

Statistics:
Disabled
reset()[source]

Reset all statistics and clear any statistic names. All statistics must be inactive before a reset will execute

Returns: True if reset, False if not

class pywbem.OperationStatistic(container, name)[source]

New in pywbem 0.11 as experimental and finalized in 0.12.

A statistics data keeper for the executions of all operations with the same operation name.

Objects of this class are created by the Statistics class and can be accessed by pywbem users through its get_op_statistic() and snapshot() methods.

Parameters:
  • container (Statistics) – The statistics container that holds this operation statistic object.
  • name (string) – Name of the operation.

Methods

formatted Return a formatted one-line string with the statistics values for the operation for which this statistics object maintains data.
formatted_header Return a two-line header.
reset Reset the statistics data for this object.
start_timer This is a low-level method that is called by pywbem at the begin of an operation.
stop_timer This is a low-level method is called by pywbem at the end of an operation.

Attributes

avg_reply_len The average size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
avg_request_len The average size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
avg_server_time The average elapsed server time for execution of the measured operations, in seconds.
avg_time The average elapsed client time for execution of the measured operations, in seconds.
container The statistics container that holds this statistics object.
count The number of measured operations.
exception_count The number of measured operations that resulted in an exception returned to the pywbem user (for example because a failure was indicated in the operation response of the WBEM server, or because pywbem itself detected a failure before sending the request or after receiving the response).
max_reply_len The maximum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
max_request_len The maximum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
max_server_time The maximum elapsed server time for execution of the measured operations, in seconds.
max_time The maximum elapsed client time for execution of the measured operations, in seconds.
min_reply_len The minimum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.
min_request_len The minimum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.
min_server_time The minimum elapsed server time for execution of the measured operations, in seconds.
min_time The minimum elapsed client time for execution of the measured operations, in seconds.
name Name of the operation for which this statistics object maintains data.
stat_start_time Point in time when the first statistic was taken since this object was either created or reset, in seconds since the epoch (for details, see time.time()).

Details

stat_start_time

Point in time when the first statistic was taken since this object was either created or reset, in seconds since the epoch (for details, see time.time()).

Type:float
name

Name of the operation for which this statistics object maintains data.

Type:string
container

The statistics container that holds this statistics object.

Type:Statistics
count

The number of measured operations.

Type:integer
exception_count

The number of measured operations that resulted in an exception returned to the pywbem user (for example because a failure was indicated in the operation response of the WBEM server, or because pywbem itself detected a failure before sending the request or after receiving the response).

Type:integer
avg_time

The average elapsed client time for execution of the measured operations, in seconds.

Type:float
min_time

The minimum elapsed client time for execution of the measured operations, in seconds.

Type:float
max_time

The maximum elapsed client time for execution of the measured operations, in seconds.

Type:float
avg_server_time

The average elapsed server time for execution of the measured operations, in seconds.

This time is 0 if the WBEM server did not return the WBEM server response time.

Type:float
min_server_time

The minimum elapsed server time for execution of the measured operations, in seconds.

This time is 0 if the WBEM server did not return the WBEM server response time.

Type:float
max_server_time

The maximum elapsed server time for execution of the measured operations, in seconds.

This time is 0 if the WBEM server did not return the WBEM server response time.

Type:float
avg_request_len

The average size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.

Type:float
min_request_len

The minimum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.

Type:float
max_request_len

The maximum size of the HTTP body in the CIM-XML requests of the measured operations, in Bytes.

Type:float
avg_reply_len

The average size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.

Type:float
min_reply_len

The minimum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.

Type:float
max_reply_len

The maximum size of the HTTP body in the CIM-XML responses of the measured operations, in Bytes.

Type:float
reset()[source]

Reset the statistics data for this object.

start_timer()[source]

This is a low-level method that is called by pywbem at the begin of an operation. It starts the measurement for that operation, if statistics is enabled for the connection.

A subsequent invocation of stop_timer() will complete the measurement for that operation and will update the statistics data.

stop_timer(request_len=None, reply_len=None, server_time=None, exception=False)[source]

This is a low-level method is called by pywbem at the end of an operation. It completes the measurement for that operation by capturing the needed data, and updates the statistics data, if statistics is enabled for the connection.

Parameters:
  • request_len (integer) – Size of the HTTP body of the CIM-XML request message, in Bytes.
  • reply_len (integer) – Size of the HTTP body of the CIM-XML response message, in Bytes.
  • exception (bool) – Boolean that specifies whether an exception was raised while processing the operation.
  • server_time (bool) –

    Time in seconds that the server optionally returns to the client in the HTTP response defining the time from when the server received the request to when it started sending the response.

    If None, the server did not report server response time. Since this can happen in the middle of a statistics measurement interval if the corresponding config setting of the server was changed, the server time is then reset to 0 and no longer maintained during the remainder of the current statistics measurement interval. A reset of the statistics clears that condition again.

Returns:

The elapsed time for the operation that just ended, or None if the statistics container holding this object is not enabled.

Return type:

float

__repr__()[source]

Return a human readable string with the statistics values, for debug purposes.

static formatted_header(include_server_time, include_lengths)[source]

Return a two-line header.

formatted(include_server_time, include_lengths)[source]

Return a formatted one-line string with the statistics values for the operation for which this statistics object maintains data.

This is a low-level method that is called by pywbem.Statistics.formatted().