NAME

Win32::Process::Perf: Shows Performance counter for a given process

VERSION


This document describes version 1.00 of Win32::Process::Perf, released
in April, 2005.

SYNOPSIS


  use Win32::Process::Perf;
  my $PERF = Win32::Process::Perf->new(<computer name>, <process name>);
  # The computer name have to be used without the \\
  # e.g. my $PERF = Win32::Process::Perf->new("taifun", "explorer");
  # check if success:
  if(!$PERF)
  {
          die;
  }

  my $anz = $PERF->GetNumberofCounterNames();
  print "$anz Counters available\n";
  my %counternames = $PERF->GetCounterNames();
  print "Avilable Counternames:\n";
  foreach (1 .. $anz)
  {
          print $counternames{$_} . "\n";
  }
  my $status = $PERF->PAddCounter();    # add all available counters to the query
  if($status == 0) {
          my $error = $PERF->GetErrorText();
          print $error . "\n";
          exit;
  }
  while(1)
  {
          $status = $PERF->PCollectData();
          if($status == 0) {
                  my $error = $PERF->GetErrorText();
                  print $error . "\n";
                  exit;
          }
          my %val = $PERF->PGetCounterValues($status);
          # now you can also get the CPU Time:
          my $cputime = $PERF->PGetCPUTime();
          # and also the username which started the process:
          my $username = $PERF->PGetUserName();
          foreach  (1..$anz)
          {
           if(!$val{$_}) { exit; }
                   my $key = $counternames{$_};
                   print "$key=" . $val{$_} . "\n";
          }
          sleep(1);
          print "\n";
  }

ABSTRACT

The Win32::Process::Perf provides an interface to the performance data of a specific running process. It uses the PDH library.

DESCRIPTION

  The module provide an Interface to the performance data of a specific running process.
  It uses the PDH library.
  The modul uses Win32::Locale to get the language of the operating system. To add the support
  for your language please look in the site/lib/Win32/Process/Perf directory. There are samples
  for the counter definition. The counter data files have to be only in the directory 
  site/lib/Win32/Process/Perf.
  
  NOTE: The first line have to be the name for process in YOUR language. e.g. in german is it
  Prozess.
  The second line have to be the for the process ID in your language.
  At this time I have only support for Windows with en-us, de-at, de-ch. Maybe someone can 
  provide me with data files for his language.
  
  Sample for en-us (english US):
  Process
  ID Process
  
  Sample for de-at (german Austria,Germany):
  Prozess
  Prozesskennung
  
  Sample for spain: 
  (please provide me with one)

FUNCTIONS

NOTE

All funcitons return a non zero value if successful, and zero is they fail, excpet GetCounterValue() which will return -1 if it fails.

new($ServerName,$ProcessName)

The constructor. The required parameters are the PC name and the process which has to be captured. Please check if the initialising of the module was successfull.

$PERF->GetErrorText()

Returns the error message from the last failed function call.

        my $err = $PERF->GetErrorText();

$PERF->PAddCounter()

This function add all process counters to the query.

    my $err = $PERF->PAddCounter();

The return code is 0 on failur.

$PERF->PCollectData()

PCollectData() collects the current raw data value for all counters in the specified query

   my $err $PERF->PCollectData();
        
On failur the return code is 0.

$PERF->PGetCounterValues();

This function retrives the data of all added counters.

   my %val = $PERF->PGetCounterValues();
        
To check if the process ended check if the value of the hash exist.
The last value of %val is the CPU time in seconds of the process.
Please take a look in test.pl

PGetCPUTime()

   With this function the time the process used on the CPU can be retrived.
   
   my $cputime=$PERF->PGetCPUTime()
   
   The function returns the CPU time in seconds on success. If the function fails -1 will be returned
   NOTE: Use it only after the call to $PERF->PGetCounterValues();
   
=item PGetUserName()

   This function returns the username which started the process.
   
   my $username = $PERF->PGetUserName();
   
   On success the function returns the username and if it fails -1.
   NOTE: Use it only after the call to $PERF->PGetCounterValues();
   Use $PERF->GetErrorText(); to get the error ocured if the function was called.

PGetPid()


        This function returns the process id on success and undef if it fails.

PREREQUISITE

Perl Modules: the File::Basename manpage <Win32::Locale> Win32 dll's pdh.dll and now Advapi32.lib

TODO

1) Better handling of the conter names provided in the *.dat files.

AUTHOR

Reinhard Pagitsch <rpirpag@gmx.at>

SPECIAL THANKS

I want to give Glen Small my special thank, because without his module Win32::PerfMon the implementation would taken much longer.