1 karl  1.1.2.2 //%2006////////////////////////////////////////////////////////////////////////
  2               //
  3               // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
  4               // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
  5               // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
  6               // IBM Corp.; EMC Corporation, The Open Group.
  7               // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
  8               // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
  9               // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 10               // EMC Corporation; VERITAS Software Corporation; The Open Group.
 11               // Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 12               // EMC Corporation; Symantec Corporation; The Open Group.
 13               //
 14               // Permission is hereby granted, free of charge, to any person obtaining a copy
 15               // of this software and associated documentation files (the "Software"), to
 16               // deal in the Software without restriction, including without limitation the
 17               // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 18               // sell copies of the Software, and to permit persons to whom the Software is
 19               // furnished to do so, subject to the following conditions:
 20               //
 21               // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 22 karl  1.1.2.2 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 23               // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 24               // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 25               // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 26               // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 27               // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 28               // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 29               //
 30               //==============================================================================
 31               
 32               README - Using the PEGASUS CIMSERVER STATISTICS
 33               
 34               Author: Karl Schopmeyer <k.schopmeyer@opengroup.org> 
 35               
 36               Date: 14 March 2006
 37               
 38               The OpenPegasus CIMServer provides for gathering statistics on the CIM
 39               operations executed by the server based on the CIM_CIMOMStatisticalData class
 40               defined in the DMTF CIM_Interop model.
 41               
 42               Statistics are gathered on all CIM Operations executed by the server when the
 43 karl  1.1.2.2 statistics are enabled.
 44               
 45               When the statistics are enabled, the server gathers times and request and
 46               response counts on each operation executed and maintains these counts and times
 47               from the time the statistics were started.  For each operation executed the
 48               following are gathered.
 49               
 50                   * request size 
 51                   * response size 
 52                   * time spent in the server 
 53                   * time spent in the providers
 54               
 55               For each operation type defined (ex getclass, etc.) an instance of the
 56               CIM_CIMOMStatisticalData class provides the following properties:
 57               
 58                   * OperationType Enum (Value/Valuemap) defining the CIM operation
 59                   type.
 60               
 61                   * NumberOfOperations - Number of operations executed for this
 62                   OperationType since the server was started or the statistics were
 63                   turned on whichever occurred later.
 64 karl  1.1.2.2 
 65                   * CimomElapsedTime - Total time spent in the CIMServer for this
 66                   operation in microseconds. This does not include time spent in the
 67                   providers. That is defined by the ProviderResponseTime. This includes
 68                   http processing, authentication, xml parsing and validation, routing,
 69                   etc time that is common to all requests.
 70               
 71                   * ProviderElapsedTime - Total time spent in the targeted providers for
 72                   this operation. Note that for class and qualifier operations (ex.
 73                   getclass) this is the time spent in the Pegasus Class repository.
 74                   Further, if repository requests (ex getclass) are required in the
 75                   server infrastructure to process an operation, that time is included as
 76                   part of the server time, not provider time. The goal of providing this
 77                   number is to measure times in the providers that are the support for
 78                   the class(s) that represent the target of this operation.
 79               
 80                   * RequestSize - Total size of the requests for this operation type in
 81                   bytes.
 82               
 83                   * ResponseSize - Total size of the responses for this operation type in
 84                   bytes.
 85 karl  1.1.2.2 
 86               At any time, the statistics gathered by an OpenPegasus CIMServer can be
 87               requested by a CIM client by enumerating the instances of the
 88               CIM_CIMOMStatisticalData class from a client to the Pegasus server in the
 89               PG/Interop namespace.  Note that there is no reset of statistics. They are
 90               continuously gathered and accumulated and, the counts wrap when they exceed the
 91               size of the property.
 92               
 93               The client tool (cimperf) reports on averages for the times and byte sizes from
 94               the totals provided by the CIM_CIMOMStatisticalData instances.
 95               
 96               ENABLING AND DISABLING STATISTICS GATHERING
 97               
 98               The statistics are normally disabled when the server environment is compiled.
 99               The enabled/disabled status of statistics gathering is controlled through a
100               property in the CIM_ObjectManager instance (GatherStatisticalData)  maintained
101               by the server and persisted through the life of the instance repository.
102               
103               The test client CLI includes a special set of operations (son and soff) that
104               directly set the GatherStatisticalData property true or false effectively
105               enabling/disabling statistics gathering.
106 karl  1.1.2.2 
107               ex. CLI son      - turns the statistics gathering on. CLI soff     
108                                - turns the statistics gathering off.
109               
110               Once statistics gathering is enabled or disabled this state is maintained
111               through cimserver or system restarts until either changed again or if the
112               repository is removed or the instance of the CIM_ObjectManager class is reset
113               or removed.
114               
115               The cimserver does not maintain gathered statistics information if the erver is
116               stopped. Each startup of the server restarts all statistics counts from zero.
117               
118               Disabling the statistics gathering also causes all of the statistics counts to
119               be reset to zero in the server.
120               
121               CLIENT OPERATIONS STATISTICS REPORTING
122               
123               In addition to the statistics reported through the CIM_CIMOMStatisticalData the
124               OpenPegasus server is capable of reporting operation execution time to the
125               client as part of each operation executed.  This function also is only active
126               when the statistics gathering capability has been enabled. The passage of this
127 karl  1.1.2.2 information is defined in the DMTF CIMOperations specification (Version 1.2,
128               3.3.16. WBEMServerResponseTime).  Within the OpenPegasus Client API there is a
129               specific operation to request this information as part of each CIM operation.
130               This reports the total time spent in the CIMServer (server plus providers) for
131               the last operation executed. As an example, this is implemented in CLI.
132               
133               LIMITATIONS
134               
135               Currently no statistics are maintained on indications processed.  Provision is
136               made in the DMTF CIM_CIMOMStatisticalData class for gathering of indication
137               statistics but the exact form of the information is in question because this
138               differs from operations so this has not been implemented to date.
139               
140               The client statistics test tool cimperf only prints out the current statistics
141               each time it is executed.  There are no client tools in the current pegasus
142               environment to maintain statistics history, show trends, etc.
143               
144               If statistics are disabled, the statistics instances will still be output by
145               the cimserver  but will show zero for all values.
146               
147               There are no automated tests today for the numbers accumulated by the
148 karl  1.1.2.2 statistics gathering components.  The validity of the numbers produced in the
149               CIM_CIMOMStatisticalData instances has been verified by manual inspection
150               However, Currently there are no automated test to programatically verify the
151               statistics are correct.