Generic PDH plug-in

Using the Generic PDH plug-in of SSC Serv allows you to collect arbitrary “Performance Counter” from Windows using the Performance Data Handles (PDH) interface.

Configuration

To configure the Generic PDH plug-in, open the SSC Serv Configuration applet in the Control Panel and open the Generic PDH tab.

Click on the “Add …” button to add a new Performance Counter. This will open the Add / Edit PDH counter window.

First, select which Performance Counter to monitor. To do that, click on the “Select …” button. This will open the Select PDH counter dialog. Because this is a system dialog, the exact layout depends on your version of Windows. The following dialog is from Windows XP:

Select the Performance Object (e.g. “Processor”) and Performance Counter (e.g. “DPCs Queues/sec”) you're interested in. Please note that you can select only one Performance Counter (see Caveat below). Then either select one Instance or select the All instances radio button to select all available instances, e.g. all processors. Confirm and close the dialog by clicking on “OK”.

If you have selected All instances, you now need to specify whether to assign the instance name to the Plugin Instance or the Type Instance. The appropriate field will be disabled and show an asterisk (“*”). Please refer to the Naming schema page in the collectd wiki for an explanation of Plugin Instance and Type Instance.

Select an appropriate Type. Pay special attention to the Data Source type, most likely Derive or Gauge. Which one you need depends on the type of data returned by the Performance Counter: Derive is used for increasing counters, such as the number of bytes sent by a network card. Gauge is used for absolute numbers, such as the number of bytes stored on a partition.

Host, Plugin and Plugin Instance and/or Type Instance can be filled to fit the structure of other metrics. When you're done, click “OK” finish setting up this counter and return to the SSC Serv Configuration.

Registry

The configured counters are stored in the Windows Registry. Since configuring metrics via the GUI may be a bit slow and repetitive if you have to set up multiple similar servers, we recommend to export the appropriate Registry keys into a .reg file and import it on the target machines. Potentially, this can be done as part of your roll-out procedure. This section described the layout of the Registry keys for the Generic PDH plug-in.

The configuration of the Generic PDH plugin is based at the follwing Registry key:

HKEY_LOCAL_MACHINE\Software\octo\SSC Serv\
  Generic_PDH\
    {6c164744-d104-11e3-885d-0019d10dfc65}\
      PDHCounterPath  "\Process(*)\Handles"
      Plugin          "generic_pdh"
      PluginInstance  "process"
      Type            "files"
      TypeInstance    ""
      SetInstance     "type"

Within this Registry key, there are one or more subkeys, one for each “value definition”, i.e. PDH counter to SSC Serv metric mapping. The name of the subkey is not relevant, by default the configuration utility will use a GUID, for example {6c164744-d104-11e3-885d-0019d10dfc65}. Each subkey has the following values:

PDHCounterPath [REG_SZ]
Path of the Performance Counter. For example \Process(explorer)\Handles. Here, “Process” is the Performance Object, “Handles” is the Performance Counter and “explorer” is the Instance. For more information about PDH counter paths please refer to Specifying a Counter Path in the MSDN. The Instance may be a wild-card, in which case each Instance will be collected. For example: \Process(*)\Handles will collect the number of open handles for each process on the system. See also SetInstance below.
Plugin [REG_SZ]
Plugin to set in the value list. If unsure, set this to “generic_pdh”.
PluginInstance [REG_SZ]
Plugin Instance to set in the value list. If SetInstance is set to plugin this value is ignored.
Type [REG_SZ]
The Type or Data Set of this metric. There must be a matching entry in the TypesDB registry key and on the collectd server, if you're using one.
TypeInstance [REG_SZ]
Type Instance to set in the value list. If SetInstance is set to type this value is ignored.
SetInstance [REG_SZ]
If your PDHCounterPath contains the wild-card Instance, the values for all Instances will be collected. This setting controls whether the Instance name of the Performance Counter is copied into the Plugin Instance (if set to plugin) or the Type Instance (if set to type). If the PDHCounterPath does not contain a wild-card instance, set this value to none.

Caveats

Windows Vista, Windows 7 and likely Windows 8 come with a new version of the “PDH Browse” dialog box, which has multiple bugs. One of these bugs is that setting the bSingleCounterPerAdd flag will result in broken behavior. The Generic PDH plugin therefore doesn't set this flag on Windows systems with the major version 6, i.e. the aforementioned versions. The result is that you can select multiple Performance Counters in the dialog; Generic PDH will ignore all but one.

Another bug is that pre-selecting a specific Performance Object and Performance Counter is broken. There's no work-around for this problem, sorry!

See also