UsageMonitor plugin


Plugin=UsageMonitor retrieves infromation from the Windows Performance Monitor.

The Windows Performance Monitor exposes counters, which monitor various kinds of system metrics in different categories, and tracks their usage. All available counters can be viewed using the Performance Monitor application. To open it, run Perfmon.exe.

Counters in Windows Performance Monitor have the following hierarchy:

  • Category - Counters are organized into related categories like "Process" or "PhysicalDisk". This is also referred to as Object in Perfmon.exe
  • Counter - Categories have individual counters like "%Processor Time" or "Bytes Read/sec"
  • Instance - Counters may have individual instances like "Rainmeter" or "C:"

The UsageMonitor plugin will allow you to define instance in the measure in one of two ways:

  • Name
    This will be the specific (case sensitive) text name of a single given instance, and will return the current value for that specific instance of a counter.
  • Index
    This will be either Index=0, which will always return the current total of all instances for a given counter, Index=-1, which will always return the current average of all instances for a given counter,or Index=N, which will return the instance at the defined point in a sorted list of all instances, with their values ordered from most to least. So for example, Index=1 would return the current value and name of the instance with the highest value for that counter.

The measure will return the current number value of the instance, and the current string value of the name of the instance. So each measure will have distinct number and string values.

The UsageMonitor plugin will optionally allow you to select common counters with a single Alias, rather than the specific, case-sensitive Category and Counter names. Additional Alias values may be supported over time.

Options

General measure options

All general measure options are valid.

AliasDefault: None

Alias or "shortcut" for a particular Category and Counter combination. This may optionally be used in place of specific Category and Counter options on the measure.


The currently supported Alias names and what they reference are:


Alias=CPU
Category: Process | Counter: % Processor Time
CPU usage of each process, across all cores, as a percentage of total CPU.

Alias=RAM
Category: Process | Counter: Working Set - Private
Bytes of Private Working Set RAM used by each process.

Alias=RAMSHARED
Category: Process | Counter: Working Set
Bytes of shared Working Set RAM used by each process.

Alias=IO
Category: Process | Counter: IO Data Bytes/sec
Bytes per second of read and write usage by each process, across all disks.

Alias=IOREAD
Category: Process | Counter: IO Read Bytes/sec
Bytes per second of read usage by each process, across all disks.

Alias=IOWRITE
Category: Process | Counter: IO Write Bytes/sec
Bytes per second of write usage by each process, across all disks.

Alias=GPU
Category: GPU Engine | Counter: Utilization Percentage
Percentage of GPU usage of each process, across all GPU engines.
Note: Requires Windows 10 Fall Creators Update or later.

Alias=VRAM
Category: GPU Process Memory | Counter: Dedicated Usage
Bytes of private video RAM usage of each process, across all GPU engines.
Note: Requires Windows 10 Fall Creators Update or later.

Alias=VRAMSHARED
Category: GPU Process Memory | Counter: Shared Usage
Bytes of shared video RAM usage of each process, across all GPU engines.
Note: Requires Windows 10 Fall Creators Update or later.

CategoryDefault: None

The Category name from Perfmon.exe for the desired counter. This is case-sensitive.

Note: If Category is defined, then Counter must also be defined, and any Alias is ignored.


Examples: Category=Process, Category=PhysicalDisk

CounterDefault: None

The Counter name from Perfmon.exe for the desired counter. This is case-sensitive.

Note: If Counter is defined, then Category must also be defined, and any Alias is ignored.


Examples: Counter=%Processor Time, Counter=Bytes Read/sec

Index Default: 0

All instances for the counter are evaluated, totaled and sorted in an indexed list from highest value to lowest value. Index is used to return the total, or one of these indexed values based on the position in the list. This list will include all instances that are not excluded by a Blacklist on the measure.


Index=0
This will always return the total of all instances, and the string "Total". This is the default for Index.

Index=-1
This will always return the average of all instances, and the string "Average".

Index=1, Index=2 etc.
This will return the value of the instance in that position in the sorted list, and the name of the corresponding instance as the string value.


Note: Any Index which returns a current value of 0 will return an empty string as the string value. An instance without a value can't be sorted, and can't exist in this indexed list, as it is indistinguishable from all other instances that are 0.

Name Default: None

Returns the current value of a specifically named instance in the counter. This is case-sensitive.

Note: If Name is defined, then any Index option is ignored.


Examples: Name=Rainmeter, Name=chrome

Blacklist Default: _Total|Idle

A list of specific instance names to be ignored by the measure. Instance names are separated with the | (pipe) character. All other instances will be used. This is case-sensitive.

Note: The instance names _Total and Idle are in the Blacklist by default. If you want to define other names, be sure to add these back in as well. Setting any Blacklist replaces the default.


Example: Blacklist=_Total|Idle|dwm|csrss|svchost|lsass|system|spoolsv

Whitelist Default: None

A list of specific instance names to be used by the measure. Instance names are separated with the | (pipe) character. All other instances will be ignored. This is case-sensitive.

Note: If Whitelist is defined, then any Blacklist option is ignored.


Example: Whitelist=Rainmeter|firefox|hexchat

Rollup Default: 1

When set to the default 1, this will cause a process that spawns multiple copies of itself to be rolled-up into a single process, rather than the individual processName#1, processName#2 etc. If set to 0, the separate processes are treated an individuals.


This will be common with applications like chrome, firefox, or dropbox, and some internal Windows processes like explorer, RunTimeBroker, or svchost.

Percent Default: 0

This should be set to 1 when the counter you are getting does not return the value as a percentage from 0-100, and it has a _Total instance, and you want to return the value as a percentage of the _Total instance.


It will not work, and should not be used, if the counter has no _Total instance, or already returns the value as a percentage value from 0-100 in the perfmon GUI.


Note: This is automatically set to 1 when Alias=CPU is used, but may be manually forced to 0 if desired.

RawValue Default: 0

When set to 1, this will return the raw value from the Perfmon database, instead of the "human readable" format shown in the Perfmon.exe GUI.

PIDToName Default: 0

When set to 1, this will lookup and return the text name of the process associated with any PID returned as the value of an instance.


Note: This is automatically set to 1 when Alias=GPU, Alias=VRAM, or Alias=VRAMSHARED is used, but may be manually forced to 0 if desired.

A note on number value vs. string value

UsageMonitor will return both the current number value of the instance, and the string value of the name of the instance. There will always be distinct number and string values for the measure.

This should be kept in mind when you use the values in a String meter, as the MeasureName option on a String meter will always use the string value of the measure in the meter.

If you want to use the number value in the meter, you can use [MyMeasure:] as a section variable to display the number value in the Text option. Be sure to set DynamicVariables=1 on the meter.

Be aware though, that when [MyMeasure:] is used in the Text option, number formatting options on the meter like NumOfDecimals or AutoScale are not used. Those only apply to values obtained by MeasureName, and used with %1 in the Text option.

NumOfDecimals can be obtained by defining the number of decimals you want in the section variable. [MyMeasure:2] will display the number value with two decimal places.

AutoScale can be obtained by creating a second Calc measure that uses the number value of the measure in question, with that measure name as the Formula option of the Calc measure. Then you can use MeasureName on the String meter, and AutoScale (and NumOfDecimals) will be obeyed.

[MeasureHighestUsedRAM]
Measure=Plugin
Plugin=UsageMonitor
Alias=RAM
Index=1

[MeasureRAMforScaling]
Measure=Calc
Formula=MeasureHighestUsedRAM

[MeterHighestUsedRAM]
Meter=String
MeasureName=MeasureHighestUsedRAM
MeasureName2=MeasureRAMforScaling
AutoScale=1
NumOfDecimals=1
DynamicVariables=1
Text=%1 : %2B

Note that other meter types, like Bar, Line, Roundline, Rotator, and other math-based meters will always use the number value of the measure, and nothing special needs to be done with those.

A note on performance

UsageMonitor is very much more efficient in its use of CPU than the PerfMon and AdvancedCPU plugins. It is strongly recommended that this plugin be used exclusively in place of them. The difference in the CPU used, and how smoothly other things in Rainmeter work when this is running, is dramatic.

The way UsageMonitor works is to spawn a single separate thread, independent of Rainmeter, for each Category that is asked for by any measures in any skin, in all of Rainmeter. The plugin is then gathering information for that Category, once a second, and is not dependent on, nor reacts to, any setting for Update on the skin, or UpdateDivider on the measure. UpdateDivider should only be used on the measure if you want to control how often actions like OnChangeAction or OnUpdateAction are executed, or how often comparisons like IfCondition or IfMatch are done.

The plugin is always gathering data, and the measure is simply used to retrieve a single element of data from it. The plugin is not told "when to do its work" by the measure.

Individual Category threads are disposed of when no plugin measures in any skins are using them, and the plugin is entirely unloaded when no running skins have measures using it.

A note on localization

UsageMonitor is fully localized for Category and Counter names, and should work without problems on any language used by Windows.

However, the way this works is that if you define the names of Category and Counter in English, they will automatically work with those names, no matter what language Perfmon is in on your system. This should be done with any skin you expect to distribute, so it will work without issue on any user's computer. If you define the names for Category and Counter in your language other than English, it will only work on your computer, or another computer using your language.

If you need a reference to the Category and Counter names in English, it can be found on any Windows system in the Windows Registry, at:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\009\Counter

Examples

Some common uses for the UsageMonitor plugin might be:

Total CPU used

[MeasureCPU]
Measure=Plugin
Plugin=UsageMonitor
Alias=CPU
Index=0

Top process CPU usage and name

[MeasureTop]
Measure=Plugin
Plugin=UsageMonitor
Alias=CPU
Index=1

CPU usage for a given process name

[MeasureRainmeter]
Measure=Plugin
Plugin=UsageMonitor
Alias=CPU
Name=Rainmeter

Various other examples

[Rainmeter]
Update=1000
DynamicWindowSize=1
AccurateText=1
SkinWidth=360
BackgroundMode=2
SolidColor=0,0,0,1

[Variables]
Browser=firefox
;Browser=chrome

[MeasureCPU]
Measure=Plugin
Plugin=UsageMonitor
Alias=CPU
Index=0

[MeasureMyApps]
Measure=Plugin
Plugin=UsageMonitor
Alias=CPU
Index=1
Whitelist=Rainmeter|#Browser#|hexchat|CCleaner64

[MeasureTop1byAlias]
Measure=Plugin
Plugin=UsageMonitor
Alias=CPU
Index=1
Blacklist=_Total|Idle|dwm|wmpnetwk|csrss|svchost|lsass|System|system|Memory Compression|wininit|RemindersServer|spoolsv|IpOverUsbSvc

[MeasureTop1byCounter]
Measure=Plugin
Plugin=UsageMonitor
Category=Process
Counter=% Processor Time
Index=1
Percent=1
Blacklist=_Total|Idle|dwm|wmpnetwk|csrss|svchost|lsass|System|system|Memory Compression|wininit|RemindersServer|spoolsv|IpOverUsbSvc

[MeasureRainmeter]
Measure=Plugin
Plugin=UsageMonitor
Alias=CPU
Name=Rainmeter

[MeasureBrowser]
Measure=Plugin
Plugin=UsageMonitor
Alias=CPU
Name=#Browser#

[TotalThreads]
Measure=Plugin
Plugin=UsageMonitor
Category=System
Counter=Threads
Index=0

[Core0Usage]
Measure=Plugin
Plugin=UsageMonitor
Category=Processor
Counter=% Processor Time
Name=0
MinValue=0
MaxValue=100

[Core1Usage]
Measure=Plugin
Plugin=UsageMonitor
Category=Processor
Counter=% Processor Time
Name=1
MinValue=0
MaxValue=100

[TopGPU]
Measure=Plugin
Plugin=UsageMonitor
Alias=GPU
Index=1
MinValue=0
MaxValue=100
Blacklist=dwm|csrss

[TotalVRAM]
Measure=Plugin
Plugin=UsageMonitor
Alias=VRAM
Index=0
MinValue=0
MaxValue=4831838208

[TotalVRAMScaled]
Measure=Calc
Formula=TotalVRAM

[RainmeterIO]
Measure=Plugin
Plugin=UsageMonitor
Alias=IO
Name=Rainmeter

[RainmeterIOScaled]
Measure=Calc
Formula=RainmeterIO

[TopIORead]
Measure=Plugin
Plugin=UsageMonitor
Alias=IO
Index=1

[TopIOReadScaled]
Measure=Calc
Formula=TopIORead

[BrowserIOWrite]
Measure=Plugin
Plugin=UsageMonitor
Alias=IOWrite
Name=#Browser#

[BrowserIOWriteScaled]
Measure=Calc
Formula=BrowserIOWrite

[BrowserRAM]
Measure=Plugin
Plugin=UsageMonitor
Alias=RAM
Name=#Browser#

[BrowserRAMScaled]
Measure=Calc
Formula=BrowserRAM

[NetworkIn]
Measure=Plugin
Plugin=UsageMonitor
Category=Network Adapter
Counter=Bytes Received/sec
Index=1

[NetworkInScaled]
Measure=Calc
Formula=NetworkIn
IfAboveValue=0
IfAboveAction=[!SetOption MeterNetworkName Text "[NetworkIn]"][!UpdateMeter *][!Redraw]

[NetworkOut]
Measure=Plugin
Plugin=UsageMonitor
Category=Network Adapter
Counter=Bytes Sent/sec
Index=1

[NetworkOutScaled]
Measure=Calc
Formula=NetworkOut
IfAboveValue=0
IfAboveAction=[!SetOption MeterNetworkName Text "[NetworkOut]"][!UpdateMeter *][!Redraw]

; Meters

[AllStyle]
FontSize=11
FontWeight=400
FontColor=255,255,255,255
AntiAlias=1
DynamicVariables=1

[RightStyle]
X=360
StringAlign=Right

[MeterCPULabel]
Meter=String
MeterStyle=AllStyle
Text=Total CPU Usage

[MeterCPUValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Text=[MeasureCPU] : [MeasureCPU:1]%

[MeterMyAppsLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Top MyApps

[MeterMyAppsValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[MeasureMyApps] : [MeasureMyApps:1]%

[MeterTop1byAliasLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Top Process by Alias

[MeterTop1byAliasValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[MeasureTop1byAlias] : [MeasureTop1byAlias:1]%

[MeterTop1byCounterLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Top Process by Counter

[MeterTop1byCounterValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[MeasureTop1byCounter] : [MeasureTop1byCounter:1]%

[MeterRainmeterLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Rainmeter CPU

[MeterRainmeterValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[MeasureRainmeter] : [MeasureRainmeter:1]%

[MeterBrowserLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Browser CPU

[MeterBrowserValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[MeasureBrowser] : [MeasureBrowser:1]%

[MeterTotalThreadsLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Total Threads

[MeterTotalThreadsValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[TotalThreads] : [TotalThreads:0]

[MeterCore0UsageLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=CPU Core 0 Usage

[MeterCore0UsageValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[Core0Usage] : [Core0Usage:1]%

[MeterCore1UsageLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=CPU Core 1 Usage

[MeterCore1UsageValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[Core1Usage] : [Core1Usage:1]%

[MeterTopGPULabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Top GPU Usage

[MeterTopGPUValues]
Meter=String
MeterStyle=AllStyle | RightStyle
Y=0r
Text=[TopGPU] : [TopGPU:1]%

[MeterTotalVRAMLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Total VRAM Usage

[MeterTotalVRAMValues]
Meter=String
MeterStyle=AllStyle | RightStyle
MeasureName=TotalVRAMScaled
Y=0r
AutoScale=1
NumOfDecimals=1
Text=[TotalVRAM] : %1B

[MeterRainmeterIOLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Rainmeter IO

[MeterRainmeterIOValues]
Meter=String
MeterStyle=AllStyle | RightStyle
MeasureName=RainmeterIOScaled
Y=0r
AutoScale=1
NumOfDecimals=1
Text=[RainmeterIO] : %1B

[MeterTopIOReadLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Top IO Read

[MeterTopIOReadValues]
Meter=String
MeterStyle=AllStyle | RightStyle
MeasureName=TopIOReadScaled
Y=0r
AutoScale=1
NumOfDecimals=1
Text=[TopIORead] : %1B

[MeterBrowserIOWriteLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Browser IO Write

[MeterBrowserIOWriteValues]
Meter=String
MeterStyle=AllStyle | RightStyle
MeasureName=BrowserIOWriteScaled
Y=0r
AutoScale=1
NumOfDecimals=1
Text=[BrowserIOWrite] : %1B

[MeterBrowserRAMLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Browser RAM Usage

[MeterBrowserRAMValues]
Meter=String
MeterStyle=AllStyle | RightStyle
MeasureName=BrowserRAMScaled
Y=0r
AutoScale=1
NumOfDecimals=1
Text=[BrowserRAM] : %1B

[MeterNetworkInLabel]
Meter=String
MeterStyle=AllStyle
Y=15R
Text=Net IN

[MeterNetworkInValues]
Meter=String
MeterStyle=AllStyle | RightStyle
MeasureName=NetworkInScaled
Y=0r
AutoScale=1
NumOfDecimals=1
Text=%1B

[MeterNetworkOutLabel]
Meter=String
MeterStyle=AllStyle
Y=3R
Text=Net OUT

[MeterNetworkOutValues]
Meter=String
MeterStyle=AllStyle | RightStyle
MeasureName=NetworkOutScaled
Y=0r
AutoScale=1
NumOfDecimals=1
Text=%1B

[MeterNetworkName]
Meter=String
MeterStyle=AllStyle
Y=3R
ClipString=1

Note:

While rare, it is possible for the database of counters that is maintained by Performance Monitor in Windows to become damaged, which will cause the UsageMonitor plugin to stop functioning correctly.

In many cases, this can be corrected by "rebuilding" the database from the Windows command line.

Run cmd.exe, being sure to run "As administrator". At the command line, enter the following commands in order:

cd c:\windows\system32
lodctr /R
cd c:\windows\sysWOW64
lodctr /R

You should see the following results:

Info: Successfully rebuilt performance counter setting from system backup store