README
¶
Windows Performance Counters Input Plugin
This document presents the input plugin to read Performance Counters on Windows operating systems.
The configuration is parsed and then tested for validity, such as whether the Object, Instance and Counter exist on Telegraf startup.
Counter paths are refreshed periodically, see the CountersRefreshInterval configuration parameter for more info.
In case of query for all instances ["*"], the plugin does not return the
instance _Total by default. See IncludeTotal for more info.
Basics
The examples contained in this file have been found on the internet as counters used when performance monitoring Active Directory and IIS in particular. There are a lot of other good objects to monitor, if you know what to look for. This file is likely to be updated in the future with more examples for useful configurations for separate scenarios.
For more information on concepts and terminology including object, counter, and instance names, see the help in the Windows Performance Monitor app.
Plugin wide
Plugin wide entries are underneath [[inputs.win_perf_counters]].
PrintValid
Bool, if set to true will print out all matching performance objects.
Example:
PrintValid=true
UseWildcardsExpansion
If UseWildcardsExpansion is true, wildcards can be used in the
instance name and the counter name. Instance indexes will also be
returned in the instance name.
Partial wildcards (e.g. chrome*) are supported only in the instance
name on Windows Vista and newer.
If disabled, wildcards (not partial) in instance names can still be used, but instance indexes will not be returned in the instance names.
Example:
UseWildcardsExpansion=true
LocalizeWildcardsExpansion
LocalizeWildcardsExpansion selects whether object and counter names
are localized when UseWildcardsExpansion is true and Telegraf is
running on a localized installation of Windows.
When LocalizeWildcardsExpansion is true, Telegraf produces metrics
with localized tags and fields even when object and counter names are
in English.
When LocalizeWildcardsExpansion is false, Telegraf expects object
and counter names to be in English and produces metrics with English
tags and fields.
When LocalizeWildcardsExpansion is false, wildcards can only be used
in instances. Object and counter names must not have wildcards.
Example:
LocalizeWildcardsExpansion=true
CountersRefreshInterval
Configured counters are matched against available counters at the interval
specified by the CountersRefreshInterval parameter. The default value is 1m
(1 minute).
If wildcards are used in instance or counter names, they are expanded at this
point, if the UseWildcardsExpansion param is set to true.
Setting the CountersRefreshInterval too low (order of seconds) can cause
Telegraf to create a high CPU load.
Set it to 0s to disable periodic refreshing.
Example:
CountersRefreshInterval=1m
PreVistaSupport
(Deprecated in 1.7; Necessary features on Windows Vista and newer are checked dynamically)
Bool, if set to true, the plugin will use the localized PerfCounter interface
that has been present since before Vista for backwards compatibility.
It is recommended NOT to use this on OSes starting with Vista and newer because it requires more configuration to use this than the newer interface present since Vista.
Example for Windows Server 2003, this would be set to true:
PreVistaSupport=true
UsePerfCounterTime
Bool, if set to true will request a timestamp along with the PerfCounter data.
If se to false, current time will be used.
Supported on Windows Vista/Windows Server 2008 and newer
Example:
UsePerfCounterTime=true
IgnoredErrors
IgnoredErrors accepts a list of PDH error codes which are defined in pdh.go, if this error is encountered it will be ignored. For example, you can provide "PDH_NO_DATA" to ignore performance counters with no instances, but by default no errors are ignored. You can find the list of possible errors here: PDH errors.
Example:
IgnoredErrors=["PDH_NO_DATA"]
Object
See Entry below.
Entry
A new configuration entry consists of the TOML header starting with,
[[inputs.win_perf_counters.object]].
This must follow before other plugin configurations,
beneath the main win_perf_counters entry, [[inputs.win_perf_counters]].
Following this are 3 required key/value pairs and three optional parameters and their usage.
ObjectName
(Required)
ObjectName is the Object to query for, like Processor, DirectoryServices, LogicalDisk or similar.
Example: ObjectName = "LogicalDisk"
Instances
(Required)
The instances key (this is an array) declares the instances of a counter you would like returned, it can be one or more values.
Example: Instances = ["C:","D:","E:"]
This will return only for the instances C:, D: and E: where relevant. To get all
instances of a Counter, use ["*"] only. By default any results containing
_Total are stripped, unless this is specified as the wanted instance.
Alternatively see the option IncludeTotal below.
It is also possible to set partial wildcards, eg. ["chrome*"], if the
UseWildcardsExpansion param is set to true
Some Objects do not have instances to select from at all.
Here only one option is valid if you want data back,
and that is to specify Instances = ["------"].
Counters
(Required)
The Counters key (this is an array) declares the counters of the ObjectName you would like returned, it can also be one or more values.
Example: Counters = ["% Idle Time", "% Disk Read Time", "% Disk Write Time"]
This must be specified for every counter you want the results of, or use
["*"] for all the counters of the object, if the UseWildcardsExpansion param
is set to true.
Measurement
(Optional)
This key is optional. If it is not set it will be win_perf_counters. In
InfluxDB this is the key underneath which the returned data is stored. So for
ordering your data in a good manner, this is a good key to set with a value when
you want your IIS and Disk results stored separately from Processor results.
Example: Measurement = "win_disk"
UseRawValues
(Optional)
This key is optional. It is a simple bool. If set to true, counter values
will be provided in the raw, integer, form. This is in contrast with the default
behavior, where values are returned in a formatted, displayable, form
as seen in the Windows Performance Monitor.
A field representing raw counter value has the _Raw suffix. Raw values should
be further used in a calculation,
e.g. 100-(non_negative_derivative("Percent_Processor_Time_Raw",1s)/100000
Note: Time based counters (i.e. % Processor Time) are reported in hundredths
of nanoseconds.
Example: UseRawValues = true
IncludeTotal
(Optional)
This key is optional. It is a simple bool.
If it is not set to true or included it is treated as false.
This key only has effect if the Instances key is set to ["*"]
and you would also like all instances containing _Total to be returned,
like _Total, 0,_Total and so on where applicable
(Processor Information is one example).
WarnOnMissing
(Optional)
This key is optional. It is a simple bool. If it is not set to true or included it is treated as false. This only has effect on the first execution of the plugin. It will print out any ObjectName/Instance/Counter combinations asked for that do not match. Useful when debugging new configurations.
FailOnMissing
(Internal)
This key should not be used. It is for testing purposes only. It is a simple bool. If it is not set to true or included this is treated as false. If this is set to true, the plugin will abort and end prematurely if any of the combinations of ObjectName/Instances/Counters are invalid.
Configuration
# # Input plugin to counterPath Performance Counters on Windows operating systems
# [[inputs.win_perf_counters]]
# ## By default this plugin returns basic CPU and Disk statistics.
# ## See the README file for more examples.
# ## Uncomment examples below or write your own as you see fit. If the system
# ## being polled for data does not have the Object at startup of the Telegraf
# ## agent, it will not be gathered.
# ## Settings:
# # PrintValid = false # Print All matching performance counters
# # Whether request a timestamp along with the PerfCounter data or just use current time
# # UsePerfCounterTime=true
# # If UseWildcardsExpansion params is set to true, wildcards (partial wildcards in instance names and wildcards in counters names) in configured counter paths will be expanded
# # and in case of localized Windows, counter paths will be also localized. It also returns instance indexes in instance names.
# # If false, wildcards (not partial) in instance names will still be expanded, but instance indexes will not be returned in instance names.
# #UseWildcardsExpansion = false
# # When running on a localized version of Windows and with UseWildcardsExpansion = true, Windows will
# # localize object and counter names. When LocalizeWildcardsExpansion = false, use the names in object.Counters instead
# # of the localized names. Only Instances can have wildcards in this case. ObjectName and Counters must not have wildcards when this
# # setting is false.
# #LocalizeWildcardsExpansion = true
# # Period after which counters will be reread from configuration and wildcards in counter paths expanded
# CountersRefreshInterval="1m"
# ## Accepts a list of PDH error codes which are defined in pdh.go, if this error is encountered it will be ignored
# ## For example, you can provide "PDH_NO_DATA" to ignore performance counters with no instances
# ## By default no errors are ignored
# ## You can find the list here: https://github.com/influxdata/telegraf/blob/master/plugins/inputs/win_perf_counters/pdh.go
# ## e.g.: IgnoredErrors = ["PDH_NO_DATA"]
# # IgnoredErrors = []
#
# [[inputs.win_perf_counters.object]]
# # Processor usage, alternative to native, reports on a per core.
# ObjectName = "Processor"
# Instances = ["*"]
# Counters = [
# "% Idle Time",
# "% Interrupt Time",
# "% Privileged Time",
# "% User Time",
# "% Processor Time",
# "% DPC Time",
# ]
# Measurement = "win_cpu"
# # Set to true to include _Total instance when querying for all (*).
# # IncludeTotal=false
# # Print out when the performance counter is missing from object, counter or instance.
# # WarnOnMissing = false
# # Gather raw values instead of formatted. Raw value is stored in the field name with the "_Raw" suffix, e.g. "Disk_Read_Bytes_sec_Raw".
# # UseRawValues = true
#
# [[inputs.win_perf_counters.object]]
# # Disk times and queues
# ObjectName = "LogicalDisk"
# Instances = ["*"]
# Counters = [
# "% Idle Time",
# "% Disk Time",
# "% Disk Read Time",
# "% Disk Write Time",
# "% User Time",
# "% Free Space",
# "Current Disk Queue Length",
# "Free Megabytes",
# ]
# Measurement = "win_disk"
#
# [[inputs.win_perf_counters.object]]
# ObjectName = "PhysicalDisk"
# Instances = ["*"]
# Counters = [
# "Disk Read Bytes/sec",
# "Disk Write Bytes/sec",
# "Current Disk Queue Length",
# "Disk Reads/sec",
# "Disk Writes/sec",
# "% Disk Time",
# "% Disk Read Time",
# "% Disk Write Time",
# ]
# Measurement = "win_diskio"
#
# [[inputs.win_perf_counters.object]]
# ObjectName = "Network Interface"
# Instances = ["*"]
# Counters = [
# "Bytes Received/sec",
# "Bytes Sent/sec",
# "Packets Received/sec",
# "Packets Sent/sec",
# "Packets Received Discarded",
# "Packets Outbound Discarded",
# "Packets Received Errors",
# "Packets Outbound Errors",
# ]
# Measurement = "win_net"
#
#
# [[inputs.win_perf_counters.object]]
# ObjectName = "System"
# Counters = [
# "Context Switches/sec",
# "System Calls/sec",
# "Processor Queue Length",
# "System Up Time",
# ]
# Instances = ["------"]
# Measurement = "win_system"
#
# [[inputs.win_perf_counters.object]]
# # Example counterPath where the Instance portion must be removed to get data back,
# # such as from the Memory object.
# ObjectName = "Memory"
# Counters = [
# "Available Bytes",
# "Cache Faults/sec",
# "Demand Zero Faults/sec",
# "Page Faults/sec",
# "Pages/sec",
# "Transition Faults/sec",
# "Pool Nonpaged Bytes",
# "Pool Paged Bytes",
# "Standby Cache Reserve Bytes",
# "Standby Cache Normal Priority Bytes",
# "Standby Cache Core Bytes",
# ]
# Instances = ["------"] # Use 6 x - to remove the Instance bit from the counterPath.
# Measurement = "win_mem"
#
# [[inputs.win_perf_counters.object]]
# # Example query where the Instance portion must be removed to get data back,
# # such as from the Paging File object.
# ObjectName = "Paging File"
# Counters = [
# "% Usage",
# ]
# Instances = ["_Total"]
# Measurement = "win_swap"
Generic Queries
[[inputs.win_perf_counters]]
[[inputs.win_perf_counters.object]]
# Processor usage, alternative to native, reports on a per core.
ObjectName = "Processor"
Instances = ["*"]
Counters = ["% Idle Time", "% Interrupt Time", "% Privileged Time", "% User Time", "% Processor Time"]
Measurement = "win_cpu"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# Disk times and queues
ObjectName = "LogicalDisk"
Instances = ["*"]
Counters = ["% Idle Time", "% Disk Time","% Disk Read Time", "% Disk Write Time", "% User Time", "Current Disk Queue Length"]
Measurement = "win_disk"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
ObjectName = "System"
Counters = ["Context Switches/sec","System Calls/sec", "Processor Queue Length"]
Instances = ["------"]
Measurement = "win_system"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# Example query where the Instance portion must be removed to get data back, such as from the Memory object.
ObjectName = "Memory"
Counters = ["Available Bytes","Cache Faults/sec","Demand Zero Faults/sec","Page Faults/sec","Pages/sec","Transition Faults/sec","Pool Nonpaged Bytes","Pool Paged Bytes"]
Instances = ["------"] # Use 6 x - to remove the Instance bit from the query.
Measurement = "win_mem"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# more counters for the Network Interface Object can be found at
# https://msdn.microsoft.com/en-us/library/ms803962.aspx
ObjectName = "Network Interface"
Counters = ["Bytes Received/sec","Bytes Sent/sec","Packets Received/sec","Packets Sent/sec"]
Instances = ["*"] # Use 6 x - to remove the Instance bit from the query.
Measurement = "win_net"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
Active Directory Domain Controller
[[inputs.win_perf_counters]]
[inputs.win_perf_counters.tags]
monitorgroup = "ActiveDirectory"
[[inputs.win_perf_counters.object]]
ObjectName = "DirectoryServices"
Instances = ["*"]
Counters = ["Base Searches/sec","Database adds/sec","Database deletes/sec","Database modifys/sec","Database recycles/sec","LDAP Client Sessions","LDAP Searches/sec","LDAP Writes/sec"]
Measurement = "win_ad" # Set an alternative measurement to win_perf_counters if wanted.
#Instances = [""] # Gathers all instances by default, specify to only gather these
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
ObjectName = "Security System-Wide Statistics"
Instances = ["*"]
Counters = ["NTLM Authentications","Kerberos Authentications","Digest Authentications"]
Measurement = "win_ad"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
ObjectName = "Database"
Instances = ["*"]
Counters = ["Database Cache % Hit","Database Cache Page Fault Stalls/sec","Database Cache Page Faults/sec","Database Cache Size"]
Measurement = "win_db"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
DFS Namespace + Domain Controllers
[[inputs.win_perf_counters]]
[[inputs.win_perf_counters.object]]
# AD, DFS N, Useful if the server hosts a DFS Namespace or is a Domain Controller
ObjectName = "DFS Namespace Service Referrals"
Instances = ["*"]
Counters = ["Requests Processed","Requests Failed","Avg. Response Time"]
Measurement = "win_dfsn"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
#WarnOnMissing = false # Print out when the performance counter is missing, either of object, counter or instance.
DFS Replication + Domain Controllers
[[inputs.win_perf_counters]]
[[inputs.win_perf_counters.object]]
# AD, DFS R, Useful if the server hosts a DFS Replication folder or is a Domain Controller
ObjectName = "DFS Replication Service Volumes"
Instances = ["*"]
Counters = ["Data Lookups","Database Commits"]
Measurement = "win_dfsr"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
#WarnOnMissing = false # Print out when the performance counter is missing, either of object, counter or instance.
DNS Server + Domain Controllers
[[inputs.win_perf_counters]]
[[inputs.win_perf_counters.object]]
ObjectName = "DNS"
Counters = ["Dynamic Update Received","Dynamic Update Rejected","Recursive Queries","Recursive Queries Failure","Secure Update Failure","Secure Update Received","TCP Query Received","TCP Response Sent","UDP Query Received","UDP Response Sent","Total Query Received","Total Response Sent"]
Instances = ["------"]
Measurement = "win_dns"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
IIS / ASP.NET
[[inputs.win_perf_counters]]
[[inputs.win_perf_counters.object]]
# HTTP Service request queues in the Kernel before being handed over to User Mode.
ObjectName = "HTTP Service Request Queues"
Instances = ["*"]
Counters = ["CurrentQueueSize","RejectedRequests"]
Measurement = "win_http_queues"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# IIS, ASP.NET Applications
ObjectName = "ASP.NET Applications"
Counters = ["Cache Total Entries","Cache Total Hit Ratio","Cache Total Turnover Rate","Output Cache Entries","Output Cache Hits","Output Cache Hit Ratio","Output Cache Turnover Rate","Compilations Total","Errors Total/Sec","Pipeline Instance Count","Requests Executing","Requests in Application Queue","Requests/Sec"]
Instances = ["*"]
Measurement = "win_aspnet_app"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# IIS, ASP.NET
ObjectName = "ASP.NET"
Counters = ["Application Restarts","Request Wait Time","Requests Current","Requests Queued","Requests Rejected"]
Instances = ["*"]
Measurement = "win_aspnet"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# IIS, Web Service
ObjectName = "Web Service"
Counters = ["Get Requests/sec","Post Requests/sec","Connection Attempts/sec","Current Connections","ISAPI Extension Requests/sec"]
Instances = ["*"]
Measurement = "win_websvc"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# Web Service Cache / IIS
ObjectName = "Web Service Cache"
Counters = ["URI Cache Hits %","Kernel: URI Cache Hits %","File Cache Hits %"]
Instances = ["*"]
Measurement = "win_websvc_cache"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
Process
[[inputs.win_perf_counters]]
[[inputs.win_perf_counters.object]]
# Process metrics, in this case for IIS only
ObjectName = "Process"
Counters = ["% Processor Time","Handle Count","Private Bytes","Thread Count","Virtual Bytes","Working Set"]
Instances = ["w3wp"]
Measurement = "win_proc"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
.NET Monitoring
[[inputs.win_perf_counters]]
[[inputs.win_perf_counters.object]]
# .NET CLR Exceptions, in this case for IIS only
ObjectName = ".NET CLR Exceptions"
Counters = ["# of Exceps Thrown / sec"]
Instances = ["w3wp"]
Measurement = "win_dotnet_exceptions"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# .NET CLR Jit, in this case for IIS only
ObjectName = ".NET CLR Jit"
Counters = ["% Time in Jit","IL Bytes Jitted / sec"]
Instances = ["w3wp"]
Measurement = "win_dotnet_jit"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# .NET CLR Loading, in this case for IIS only
ObjectName = ".NET CLR Loading"
Counters = ["% Time Loading"]
Instances = ["w3wp"]
Measurement = "win_dotnet_loading"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# .NET CLR LocksAndThreads, in this case for IIS only
ObjectName = ".NET CLR LocksAndThreads"
Counters = ["# of current logical Threads","# of current physical Threads","# of current recognized threads","# of total recognized threads","Queue Length / sec","Total # of Contentions","Current Queue Length"]
Instances = ["w3wp"]
Measurement = "win_dotnet_locks"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# .NET CLR Memory, in this case for IIS only
ObjectName = ".NET CLR Memory"
Counters = ["% Time in GC","# Bytes in all Heaps","# Gen 0 Collections","# Gen 1 Collections","# Gen 2 Collections","# Induced GC","Allocated Bytes/sec","Finalization Survivors","Gen 0 heap size","Gen 1 heap size","Gen 2 heap size","Large Object Heap size","# of Pinned Objects"]
Instances = ["w3wp"]
Measurement = "win_dotnet_mem"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
[[inputs.win_perf_counters.object]]
# .NET CLR Security, in this case for IIS only
ObjectName = ".NET CLR Security"
Counters = ["% Time in RT checks","Stack Walk Depth","Total Runtime Checks"]
Instances = ["w3wp"]
Measurement = "win_dotnet_security"
#IncludeTotal=false #Set to true to include _Total instance when querying for all (*).
Troubleshooting
If you are getting an error about an invalid counter, use the typeperf command
to check the counter path on the command line. E.g. typeperf "Process(chrome*)\% Processor Time"
If no metrics are emitted even with the default config, you may need to repair your performance counters.
- Launch the Command Prompt as Administrator (right click Runs As Administrator).
- Drop into the C:\WINDOWS\System32 directory by typing
C:thencd \Windows\System32 - Rebuild your counter values, which may take a few moments so please be patient, by running:
lodctr /r
Documentation
Source Files