'''
Performance Data Helper (PDH) Query Classes
Wrapper classes for end-users and high-level access to the PDH query
mechanisms. PDH is a win32-specific mechanism for accessing the
performance data made available by the system. The Python for Windows
PDH module does not implement the "Registry" interface, implementing
the more straightforward Query-based mechanism.
The basic idea of a PDH Query is an object which can query the system
about the status of any number of "counters." The counters are paths
to a particular piece of performance data. For instance, the path
'\\Memory\\Available Bytes' describes just about exactly what it says
it does, the amount of free memory on the default computer expressed
in Bytes. These paths can be considerably more complex than this,
but part of the point of this wrapper module is to hide that
complexity from theenduserprogrammer. import
EXAMPLE: A more complex Path
'\\\\RAISTLIN\\PhysicalDisk(_Total)\\Avg. Disk Bytes/Read'
Raistlin --> Computer Name
PhysicalDisk --> Object Name
_Total --> The particular Instance (in this case, all instances, i.e. all drives)
Avg. Disk Bytes/Read --> The piece of data being monitored.
EXAMPLE: Collecting Data with a Query
As an example, the following code implements a logger which allows the
user to choose what counters they would like to log, and logs those
counters for 30 seconds, at two-second intervals.
query = Query()
query.addcounterbybrowsing()
query.collectdatafor(30,2)
The data is now stored in a list of lists as:
query.curresults
The counters(paths) which were used to collect the data are:
query.curpaths
You can use the win32pdh.ParseCounterPath(path) utility function
to turn the paths into more easily read values for your task, or
write the data to a file, or do whatever you want with it.
OTHER NOTABLE METHODS:
query.collectdatawhile(period) # start a logging thread for collecting data
query.collectdatawhile_stop() # signal the logging thread to stop logging
query.collectdata() # run the query only once
query.addperfcounter(object, counter, machine=None) # add a standard performance counter
query.addinstcounter(object, counter,machine=None,objtype = 'Process',volatile=1,format = win32pdh.PDH_FMT_LONG) # add a possibly volatile counter
### Known bugs and limitations ###
Due to a problem with threading under the PythonWin interpreter, there
will be no data logged if the PythonWin window is not the foreground
application. Workaround: scripts using threading should be run in the
python.exe interpreter.
The volatile-counter handlers are possibly buggy, they haven't been
tested to any extent. The wrapper Query makes it safe to pass invalid
paths (a -1 will be returned, or the Query will be totally ignored,
depending on the missing element), so you should be able to work around
the error by including all possible paths and filtering out the -1's.
There is no way I know of to stop a thread which is currently sleeping,
so you have to wait until the thread in collectdatawhile is activated
again. This might become a problem in situations where the collection
period is multiple minutes (or hours, or whatever).
Should make the win32pdh.ParseCounter function available to the Query
classes as a method or something similar, so that it can be accessed
by programmes that have just picked up an instance from somewhere. import
Should explicitly mention where QueryErrors can be raised, and create a
full test set to see if there are any uncaught win32api.error's still
hanging around.
When using the python.exe interpreter, the addcounterbybrowsing-
generated browser window is often hidden behind other windows. No known
workaround other than Alt-tabing to reach the browser window.
### Other References ###
The win32pdhutil module (which should be in the %pythonroot%/win32/lib
directory) provides quick-and-dirty utilities for one-off access to
variables from thePDH.Almosteverythingthatmodulecanbedone import
with a Query object, but it provides task-oriented functions for a
number of common one-off tasks.
If you can access the MS Developers Network Library, you can find
information about the PDH API as MS describes it. For a background article,
try:
http://msdn.microsoft.com/library/en-us/dnperfmo/html/msdn_pdhlib.asp
The reference guide for the PDH API was last spotted at:
http://msdn.microsoft.com/library/en-us/perfmon/base/using_the_pdh_interface.asp
In general the Python version of the API is just a wrapper around the
Query-based version of this API (as far as I can see), so you can learn what
you need to from there.FromwhatIunderstandtheMSDNOnline import
resources are available for the price of signing up for them. I can't
guarantee how long that's supposed to last. (Or anything for that
matter).
http://premium.microsoft.com/isapi/devonly/prodinfo/msdnprod/msdnlib.idc?theURL=/msdn/library/sdkdoc/perfdata_4982.htm
The eventual plan is for my (Mike Fletcher's) Starship account to include
a section on NT Administration, and the Query is the first project
in this plan. There should be an article describing the creation of
a simple logger there, but the example above is 90% of the work of
that project, so don't sweat it if you don't find anything there.
(currently the account hasn't been set up).
http://starship.skyport.net/crew/mcfletch/
If you need to contact me immediately, (why I can't imagine), you can
email me at mcfletch@golden.net, or just post your question to the
Python newsgroup with a catchy subject line.
news:comp.lang.python
### Other Stuff ###
The Query classes are by Mike Fletcher, with the working code
being corruptions of Mark Hammonds win32pdhutil module.
Use at your own risk, no warranties, no guarantees, no assurances,
if you use it, you accept the risk of using it, etceteras.
'''
# Feb 12, 98 - MH added "rawaddcounter" so caller can get exception details.
import win32pdh, win32api,time, thread,copy
class BaseQuery:
'''
Provides wrapped access to the Performance Data Helper query
objects, generally you should use the child class Query
unless you have need of doing weird things :)
This class supports two major working paradigms. In the first,
you open the query, and run it as many times as you need, closing
the query when you're done with it. This is suitable for static
queries (ones where processes being monitored don't disappear).
In the second, you allow the query to be opened each time and
closed afterward. This causes the base query object to be
destroyed after each call. Suitable for dynamic queries (ones
which watch processes which might be closed while watching.)
'''
def __init__(self,paths=None):
'''
The PDH Query object is initialised with a single, optional
list argument, that must be properly formatted PDH Counter
paths. Generally this list will only be provided by the class
when it is being unpickled (removed from storageNormal import
use is to call the class with no arguments and use the various
addcounter functions (particularly, for end user's, the use of
addcounterbybrowsing is the most common approach) You might
want to provide the list directly if you want to hard-code the
elements with which your query deals (and thereby avoid the
overhead of unpickling the class).
'''
self.counters = []
if paths:
self.paths = paths
else:
self.paths = []
self._base = None
self.active = 0
self.curpaths = []
def addcounterbybrowsing(self, flags = win32pdh.PERF_DETAIL_WIZARD, windowtitle="Python Browser"):
'''
Adds possibly multiple paths to the paths attribute of the query,
does this by calling the standard counter browsing dialogue. Within
this dialogue, find the counter you want to log, and click: Add,
repeat for every path you want to log, then click on close. The
paths are appended to the non-volatile paths list for this class,
subclasses may create a function which parses the paths and decides
(via heuristics) whether to add the path to the volatile or non-volatile
path list.
e.g.:
query.addcounter()
'''
win32pdh.BrowseCounters(None,0, self.paths.append, flags, windowtitle)
def rawaddcounter(self,object, counter, instance = None, inum=-1, machine=None):
'''
Adds a single counter path, without catching any exceptions.
See addcounter for details.
'''
path = win32pdh.MakeCounterPath( (machine,object,instance, None, inum,counter) )
self.paths.append(path)
def addcounter(self,object, counter, instance = None, inum=-1, machine=None):
'''
Adds a single counter path to the paths attribute. Normally
this will be called by a child class' speciality functions,
rather than being called directly by the user. (Though it isn't
hard to call manually, since almost everything is given a default)
This method is only functional when the query is closed (or hasn't
yet been opened). This is to prevent conflict in multi-threaded
query applications).
e.g.:
query.addcounter('Memory','Available Bytes')
'''
if not self.active:
try:
self.rawaddcounter(object, counter, instance, inum, machine)
return 0
except win32api.error:
return -1
else:
return -1
def open(self):
'''
Build the base query object for this wrapper,
then add all of the counters required for the query.
Raise a QueryError if we can't complete the functions.
If we are already open, then do nothing.
'''
if not self.active: # to prevent having multiple open queries
# curpaths are made accessible here because of the possibility of volatile paths
# which may be dynamically altered by subclasses.
self.curpaths = copy.copy(self.paths)
try:
base = win32pdh.OpenQuery()
for path in self.paths:
try:
self.counters.append(win32pdh.AddCounter(base, path))
except win32api.error: # we passed a bad path
self.counters.append(0)
pass
self._base = base
self.active = 1
return 0 # open succeeded
except: # if we encounter any errors, kill the Query
try:
self.killbase(base)
except NameError: # failed in creating query
pass
self.active = 0
self.curpaths = []
raise QueryError(self)
return 1 # already open
def killbase(self,base=None):
'''
### This is not a public method
Mission critical function to kill the win32pdh objects held
by this object. User's should generally use the close method
instead of this method, in case a sub-class has overridden
close to provide some special functionality.
'''
# Kill Pythonic references to the objects in this object's namespace
self._base = None
counters = self.counters
self.counters = []
# we don't kill the curpaths for convenience, this allows the
# user to close a query and still access the last paths
self.active = 0
# Now call the delete functions on all of the objects
try:
map(win32pdh.RemoveCounter,counters)
except:
pass
try:
win32pdh.CloseQuery(base)
except:
pass
del(counters)
del(base)
def close(self):
'''
Makes certain that the underlying query object has been closed,
and that all counters have been removed from it.This import
important for reference counting.
You should only need to call close if you have previously called
open. The collectdata methods all can handle opening and
closing the query. Calling close multiple times is acceptable.
'''
try:
self.killbase(self._base)
except AttributeError:
self.killbase()
__del__ = close
def collectdata(self,format = win32pdh.PDH_FMT_LONG):
'''
Returns the formatted current values for the Query
'''
if self._base: # we are currently open, don't change this
return self.collectdataslave(format)
else: # need to open and then close the _base, should be used by one-offs and elements tracking application instances
self.open() # will raise QueryError if couldn't open the query
temp = self.collectdataslave(format)
self.close() # will always close
return temp
def collectdataslave(self,format = win32pdh.PDH_FMT_LONG):
'''
### Not a public method
Called only when the Query is known to be open, runs over
the whole set of counters, appending results to the temp,
returns the values as a list.
'''
try:
win32pdh.CollectQueryData(self._base)
temp = []
for counter in self.counters:
ok = 0
try:
if counter:
temp.append(win32pdh.GetFormattedCounterValue(counter, format)[1])
ok = 1
except win32api.error:
pass
if not ok:
temp.append(-1) # a better way to signal failure???
return temp
except win32api.error: # will happen if, for instance, no counters are part of the query and we attempt to collect data for it.
return [-1] * len(self.counters)
# pickle functions
def __getinitargs__(self):
'''
### Not a public method
'''
return (self.paths,)
class Query(BaseQuery):
'''
Performance Data Helper(PDH) Query object:
Provides a wrapper around the native PDH query object which
allows for query reuse, query storage, and general maintenance
functions (adding counter paths in various ways being the most
obvious ones).
'''
def __init__(self,*args,**namedargs):
'''
The PDH Query object is initialised with a single, optional
list argument, that must be properly formatted PDH Counter
paths. Generally this list will only be provided by the class
when it is being unpickled (removed from storageNormal import
use is to call the class with no arguments and use the various
addcounter functions (particularly, for end user's, the use of
addcounterbybrowsing is the most common approach) You might
want to provide the list directly if you want to hard-code the
elements with which your query deals (and thereby avoid the
overhead of unpickling the class).
'''
self.volatilecounters = []
BaseQuery.__init__(*(self,)+args, **namedargs)
def addperfcounter(self, object, counter, machine=None):
'''
A "Performance Counter" is a stable, known, common counter,
such as Memory, or Processor. The use of addperfcounter by
end-users is deprecated, since the use of
addcounterbybrowsing is considerably more flexible and general.
It is provided here to allow the easy development of scripts
which need to access variables so common we know them by name
(such as Memory|Available Bytes), and to provide symmetry with
the add inst counter method.
usage:
query.addperfcounter('Memory', 'Available Bytes')
It is just as easy to access addcounter directly, the following
has an identicle effect.
query.addcounter('Memory', 'Available Bytes')
'''
BaseQuery.addcounter(self, object=object, counter=counter, machine=machine)
def addinstcounter(self, object, counter,machine=None,objtype = 'Process',volatile=1,format = win32pdh.PDH_FMT_LONG):
'''
The purpose of using an instcounter is to track particular
instances of a counter object (e.g. a single processor, a single
running copy of a process). For instance, to track all python.exe
instances, you would need merely to ask:
query.addinstcounter('python','Virtual Bytes')
You can find the names of the objects and their available counters
by doing an addcounterbybrowsing() call on a query object (or by
looking in performance monitor's add dialog.)
Beyond merely rearranging the call arguments to make more sense,
if the volatile flag is true, the instcounters also recalculate
the paths of the available instances on every call to open the
query.
'''
if volatile:
self.volatilecounters.append((object,counter,machine,objtype,format))
else:
self.paths[len(self.paths):] = self.getinstpaths(object,counter,machine,objtype,format)
def getinstpaths(self,object,counter,machine=None,objtype='Process',format = win32pdh.PDH_FMT_LONG):
'''
### Not an end-user function
Calculate the paths for an instance object. Should alter
to allow processing for lists of object-counter pairs.
'''
items, instances = win32pdh.EnumObjectItems(None,None,objtype, -1)
# find out how many instances of this element we have...
instances.sort()
try:
cur = instances.index(object)
except ValueError:
return [] # no instances of this object
temp = [object]
try:
while instances[cur+1] == object:
temp.append(object)
cur = cur+1
except IndexError: # if we went over the end
pass
paths = []
for ind in range(len(temp)):
# can this raise an error?
paths.append(win32pdh.MakeCounterPath( (machine,'Process',object,None,ind,counter) ) )
return paths # should also return the number of elements for naming purposes
def open(self,*args,**namedargs):
'''
Explicitly open a query:
When you are needing to make multiple calls to the same query,
it is most efficient to open the query, run all of the calls,
then close the query, instead of having the collectdata method
automatically open and close the query each time it runs.
There are currently no arguments to open.
'''
# do all the normal opening stuff, self._base is now the query object
BaseQuery.open(*(self,)+args, **namedargs)
# should rewrite getinstpaths to take a single tuple
paths = []
for tup in self.volatilecounters:
paths[len(paths):] = self.getinstpaths(*tup)
for path in paths:
try:
self.counters.append(win32pdh.AddCounter(self._base, path))
self.curpaths.append(path) # if we fail on the line above, this path won't be in the table or the counters
except win32api.error:
pass # again, what to do with a malformed path???
def collectdatafor(self, totalperiod, period=1):
'''
Non-threaded collection of performance data:
This method allows you to specify the total period for which you would
like to run the Query, and the time interval between individual
runs. The collected data is stored in query.curresults at the
_end_ of the run. The pathnames for the query are stored in
query.curpaths.
e.g.:
query.collectdatafor(30,2)
Will collect data for 30seconds at 2 second intervals
'''
tempresults = []
try:
self.open()
for ind in xrange(totalperiod/period):
tempresults.append(self.collectdata())
time.sleep(period)
self.curresults = tempresults
finally:
self.close()
def collectdatawhile(self, period=1):
'''
Threaded collection of performance data:
This method sets up a simple semaphor system for signalling
when you would like to start and stop a threaded data collection
method. The collection runs every period seconds until the
semaphor attribute is set to a non-true value (which normally
should be done by calling query.collectdatawhile_stop() .)
e.g.:
query.collectdatawhile(2)
# starts the query running, returns control to the caller immediately
# is collecting data every two seconds.
# do whatever you want to do while the thread runs, then call:
query.collectdatawhile_stop()
# when you want to deal with the data. It is generally a good idea
# to sleep for period seconds yourself, since the query will not copy
# the required data until the next iteration:
time.sleep(2)
# now you can access the data from the attributes of the query
query.curresults
query.curpaths
'''
self.collectdatawhile_active = 1
thread.start_new_thread(self.collectdatawhile_slave,(period,))
def collectdatawhile_stop(self):
'''
Signals the collectdatawhile slave thread to stop collecting data
on the next logging iteration.
'''
self.collectdatawhile_active = 0
def collectdatawhile_slave(self, period):
'''
### Not a public function
Does the threaded work of collecting the data and storing it
in an attribute of the class.
'''
tempresults = []
try:
self.open() # also sets active, so can't be changed.
while self.collectdatawhile_active:
tempresults.append(self.collectdata())
time.sleep(period)
self.curresults = tempresults
finally:
self.close()
# pickle functions
def __getinitargs__(self):
return (self.paths,)
def __getstate__(self):
return self.volatilecounters
def __setstate__(self, volatilecounters):
self.volatilecounters = volatilecounters
class QueryError:
def __init__(self, query):
self.query = query
def __repr__(self):
return '<Query Error in %s>'%repr(self.query)
__str__ = __repr__
|