1 martin 1.2 //%LICENSE////////////////////////////////////////////////////////////////

  2 martin 1.3 //

  3 martin 1.2 // Licensed to The Open Group (TOG) under one or more contributor license
  4            // agreements.  Refer to the OpenPegasusNOTICE.txt file distributed with
  5            // this work for additional information regarding copyright ownership.
  6            // Each contributor licenses this file to you under the OpenPegasus Open
  7            // Source License; you may not use this file except in compliance with the
  8            // License.

  9 martin 1.3 //

 10 martin 1.2 // Permission is hereby granted, free of charge, to any person obtaining a
 11            // copy of this software and associated documentation files (the "Software"),
 12            // to deal in the Software without restriction, including without limitation
 13            // the rights to use, copy, modify, merge, publish, distribute, sublicense,
 14            // and/or sell copies of the Software, and to permit persons to whom the
 15            // Software is furnished to do so, subject to the following conditions:

 16 martin 1.3 //

 17 martin 1.2 // The above copyright notice and this permission notice shall be included
 18            // in all copies or substantial portions of the Software.

 19 martin 1.3 //

 20 martin 1.2 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS

 21 martin 1.3 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 22 martin 1.2 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 23            // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 24            // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 25            // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 26            // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 27 martin 1.3 //

 28 martin 1.2 //////////////////////////////////////////////////////////////////////////

 29 karl   1.1 
 30            README - Using the PEGASUS CIMSERVER STATISTICS
 31            
 32            Author: Karl Schopmeyer <k.schopmeyer@opengroup.org> 
 33            
 34            Date: 14 March 2006
 35            
 36            The OpenPegasus CIMServer provides for gathering statistics on the CIM
 37            operations executed by the server based on the CIM_CIMOMStatisticalData class
 38            defined in the DMTF CIM_Interop model.
 39            
 40            Statistics are gathered on all CIM Operations executed by the server when the
 41            statistics are enabled.
 42            
 43            When the statistics are enabled, the server gathers times and request and
 44            response counts on each operation executed and maintains these counts and times
 45            from the time the statistics were started.  For each operation executed the
 46            following are gathered.
 47            
 48                * request size 
 49                * response size 
 50 karl   1.1     * time spent in the server 
 51                * time spent in the providers
 52            
 53            For each operation type defined (ex getclass, etc.) an instance of the
 54            CIM_CIMOMStatisticalData class provides the following properties:
 55            
 56                * OperationType Enum (Value/Valuemap) defining the CIM operation
 57                type.
 58            
 59                * NumberOfOperations - Number of operations executed for this
 60                OperationType since the server was started or the statistics were
 61                turned on whichever occurred later.
 62            
 63                * CimomElapsedTime - Total time spent in the CIMServer for this
 64                operation in microseconds. This does not include time spent in the
 65                providers. That is defined by the ProviderResponseTime. This includes
 66                http processing, authentication, xml parsing and validation, routing,
 67                etc time that is common to all requests.
 68            
 69                * ProviderElapsedTime - Total time spent in the targeted providers for
 70                this operation. Note that for class and qualifier operations (ex.
 71 karl   1.1     getclass) this is the time spent in the Pegasus Class repository.
 72                Further, if repository requests (ex getclass) are required in the
 73                server infrastructure to process an operation, that time is included as
 74                part of the server time, not provider time. The goal of providing this
 75                number is to measure times in the providers that are the support for
 76                the class(s) that represent the target of this operation.
 77            
 78                * RequestSize - Total size of the requests for this operation type in
 79                bytes.
 80            
 81                * ResponseSize - Total size of the responses for this operation type in
 82                bytes.
 83            
 84            At any time, the statistics gathered by an OpenPegasus CIMServer can be
 85            requested by a CIM client by enumerating the instances of the
 86            CIM_CIMOMStatisticalData class from a client to the Pegasus server in the
 87            PG/Interop namespace.  Note that there is no reset of statistics. They are
 88            continuously gathered and accumulated and, the counts wrap when they exceed the
 89            size of the property.
 90            
 91            The client tool (cimperf) reports on averages for the times and byte sizes from
 92 karl   1.1 the totals provided by the CIM_CIMOMStatisticalData instances.
 93            
 94            ENABLING AND DISABLING STATISTICS GATHERING
 95            
 96            The statistics are normally disabled when the server environment is compiled.
 97            The enabled/disabled status of statistics gathering is controlled through a
 98            property in the CIM_ObjectManager instance (GatherStatisticalData)  maintained
 99            by the server and persisted through the life of the instance repository.
100            
101            The test client CLI includes a special set of operations (son and soff) that
102            directly set the GatherStatisticalData property true or false effectively
103            enabling/disabling statistics gathering.
104            
105            ex. CLI son      - turns the statistics gathering on. CLI soff     
106                             - turns the statistics gathering off.
107            
108            Once statistics gathering is enabled or disabled this state is maintained
109            through cimserver or system restarts until either changed again or if the
110            repository is removed or the instance of the CIM_ObjectManager class is reset
111            or removed.
112            
113 karl   1.1 The cimserver does not maintain gathered statistics information if the erver is
114            stopped. Each startup of the server restarts all statistics counts from zero.
115            
116            Disabling the statistics gathering also causes all of the statistics counts to
117            be reset to zero in the server.
118            
119            CLIENT OPERATIONS STATISTICS REPORTING
120            
121            In addition to the statistics reported through the CIM_CIMOMStatisticalData the
122            OpenPegasus server is capable of reporting operation execution time to the
123            client as part of each operation executed.  This function also is only active
124            when the statistics gathering capability has been enabled. The passage of this
125            information is defined in the DMTF CIMOperations specification (Version 1.2,
126            3.3.16. WBEMServerResponseTime).  Within the OpenPegasus Client API there is a
127            specific operation to request this information as part of each CIM operation.
128            This reports the total time spent in the CIMServer (server plus providers) for
129            the last operation executed. As an example, this is implemented in CLI.
130            
131            LIMITATIONS
132            
133            Currently no statistics are maintained on indications processed.  Provision is
134 karl   1.1 made in the DMTF CIM_CIMOMStatisticalData class for gathering of indication
135            statistics but the exact form of the information is in question because this
136            differs from operations so this has not been implemented to date.
137            
138            The client statistics test tool cimperf only prints out the current statistics
139            each time it is executed.  There are no client tools in the current pegasus
140            environment to maintain statistics history, show trends, etc.
141            
142            If statistics are disabled, the statistics instances will still be output by
143            the cimserver  but will show zero for all values.
144            
145            There are no automated tests today for the numbers accumulated by the
146            statistics gathering components.  The validity of the numbers produced in the
147            CIM_CIMOMStatisticalData instances has been verified by manual inspection
148            However, Currently there are no automated test to programatically verify the
149            statistics are correct.