windows_exporter/docs/collector.performancecounter.md

performancecounter collector

The performancecounter collector exposes any configured metric.

Metric name prefix	performancecounter
Data source	Performance Data Helper
Enabled by default?	No

Flags

--collector.performancecounter.objects

Objects is a list of objects to collect metrics from. The value takes the form of a JSON array of objects. YAML is supported.

The collector supports only English-named counter. Localized counter-names aren’t supported.

Caution

If you are using a configuration file, the value must be kept as a string.

Use a |- to keep the value as a string.

Example

collector:
  performancecounter:
    objects: |-
      - name: memory
        object: "Memory"
        counters:
          - name: "Cache Faults/sec"
            metric: windows_performancecounter_memory_cache_faults_total # optional
            type: "counter" # optional

Schema

YAML:

Click to expand YAML schema

- name: cpu # free text name
  object: "Processor Information" # Performance counter object name
  instances: ["*"]
  instance_label: "core"
  counters:
    - name: "% User Time"
      metric: windows_performancecounter_processor_information_processor_time_total # optional
      labels:
        state: user
    - name: "% Privileged Time"
      metric: windows_performancecounter_processor_information_processor_time_total # optional
      labels:
        state: privileged
    - name: "% Idle Time"
      metric: windows_performancecounter_processor_information_processor_time_total # optional
      labels:
        state: idle
- name: memory
  object: "Memory"
  type: "formatted"
  counters:
    - name: "Cache Faults/sec"
      metric: windows_performancecounter_memory_cache_faults_per_second # optional
      type: "gauge" # optional
      multiplier: 1 # optional

Click to expand JSON schema

[
  {
    "name": "cpu",
    "object": "Processor Information",
    "instances": [
      "*"
    ],
    "instance_label": "core",
    "counters": [
      {
        "name": "% User Time",
        "metric": "windows_performancecounter_processor_information_processor_time_total",
        "labels": {
          "state": "user"
        }
      },
      {
        "name": "% Privileged Time",
        "metric": "windows_performancecounter_processor_information_processor_time_total",
        "labels": {
          "state": "privileged"
        }
      },
      {
        "name": "% Idle Time",
        "metric": "windows_performancecounter_processor_information_processor_time_total",
        "labels": {
          "state": "idle"
        }
      }
    ]
  },
  {
    "name": "memory",
    "object": "Memory",
    "type": "formatted",
    "counters": [
      {
        "name": "Cache Faults/sec",
        "metric": "windows_performancecounter_memory_cache_faults_per_second",
        "type": "gauge",
        "multiplier": 1
      }
    ]
  }
]

name

The name is used to identify the object in the logs and metrics. Must unique across all objects.

object

ObjectName is the Object to query for, like Processor, DirectoryServices, LogicalDisk or similar.

The collector supports only english named counter. Localized counter-names are not supported.

type

The counter-type. The value can be raw or formatted. Optional and defaults to raw.

• raw returns the raw value of the counter. This is the default.
• formatted returns the formatted value of the counter. This is useful for counters like Processor Information where the value is a percentage.

The difference between a raw Windows Performance Counter and a formatted Windows Performance Counter is about how the data is presented and processed:

1. Raw Windows Performance Counter:

   This provides the counter's data in its basic, unprocessed form. The values may represent cumulative counts, time intervals, or other uncalibrated metrics. Interpreting these values often requires more calculations or context, such as calculating deltas or normalizing values over time.

2. Formatted Windows Performance Counter:

   This presents data that has already been processed and interpreted according to the counter type (e.g., rates per second, averages, percentages). Formatted counters are easier to understand directly since the necessary calculations have been applied. These are often what monitoring tools display to users because they are meaningful at a glance.

For example:

• A raw counter for CPU time might give the total number of clock ticks used since the system started.
• A formatted counter would convert this into a percentage of CPU utilization over a specific time interval.

instances

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.

Some Objects like Memory do not have instances to select from at all. In this case, the instances key can be omitted.

instance_label

The name of the label that holds the instance name. Optional and defaults to object_instance. Do not use instance: it collides with the target label that Prometheus adds.

The label is only added if instances is set.

Some objects report the same instance name more than once in a sample, for example Process reports every svchost process as svchost. The first instance keeps its name, later ones get the suffix #1, #2 and so on, skipping names that Windows reported itself, such as a network adapter Ethernet#2. The suffix depends on the order of the sample and does not identify an instance across scrapes.

counters

List of counters to collect from the object. See the counters sub-schema for more information.

counters Sub-Schema

name

The name of the counter to collect.

metric

It indicates the name of the metric to be exposed. If not specified, the metric name will be generated based on the object name and the counter name.

This key is optional.

type

It indicates the type of the counter. The value can be counter or gauge. If not specified, the windows_exporter will try to determine the type based on the counter type.

This key is optional.

multiplier

A factor that the value is multiplied by before it is exported, to convert it to the base unit the Prometheus naming conventions ask for. For example, 0.001 converts milliseconds to seconds, 0.01 percent to a ratio and 3600 hours to seconds. It must be a positive number, so counters keep counting up. If the multiplier is the reciprocal of an integer, like 0.001, the value is divided by that integer instead, which avoids rounding artifacts such as 0.009000000000000001. If not specified, the value is exported as is.

With the object type raw, the default, time counters are already converted to seconds, so do not scale them again:

• the 100 ns timers (PERF_100NSEC_TIMER, PERF_100NSEC_TIMER_INV, PERF_100NSEC_MULTI_TIMER, PERF_100NSEC_MULTI_TIMER_INV and PERF_PRECISION_100NS_TIMER), such as % Idle Time;
• PERF_COUNTER_100NS_QUEUELEN_TYPE counters, such as Avg. Data Queue Length of SMB Client Shares, as queue length times seconds, so their rate is the average queue length;
• PERF_AVERAGE_TIMER counters, such as Avg. Disk sec/Read, as the summed duration in seconds, using the time base of the counter. Their second value is the number of operations;
• PERF_ELAPSED_TIME counters, such as Process\Elapsed Time, as seconds since the start.

The raw value of an _INV counter is the inactive time: for % Processor Time, that is the idle time, not the busy time. MULTI_TIMER values are summed over all units of the counter, so they can grow faster than wall time.

This key is optional.

labels

Labels is a map of key-value pairs that will be added as labels to the metric.

Counters of the same object that share a metric name must differ in their labels, like state in the schema example above. Otherwise, they would produce identical series and the collector fails to start.

Example

# HELP windows_performancecounter_memory_cache_faults_per_second windows_exporter: custom Performance Counter metric
# TYPE windows_performancecounter_memory_cache_faults_per_second gauge
windows_performancecounter_memory_cache_faults_per_second 0
# HELP windows_performancecounter_processor_information_processor_time_total windows_exporter: custom Performance Counter metric
# TYPE windows_performancecounter_processor_information_processor_time_total counter
windows_performancecounter_processor_information_processor_time_total{core="0,0",state="idle"} 92831.8125
windows_performancecounter_processor_information_processor_time_total{core="0,0",state="privileged"} 28957.421875
windows_performancecounter_processor_information_processor_time_total{core="0,0",state="user"} 12147.921875
windows_performancecounter_processor_information_processor_time_total{core="0,1",state="idle"} 92790.4375
windows_performancecounter_processor_information_processor_time_total{core="0,1",state="privileged"} 26724.78125
windows_performancecounter_processor_information_processor_time_total{core="0,1",state="user"} 14421.8125
windows_performancecounter_processor_information_processor_time_total{core="0,2",state="idle"} 91185.484375
windows_performancecounter_processor_information_processor_time_total{core="0,2",state="privileged"} 27029.34375
windows_performancecounter_processor_information_processor_time_total{core="0,2",state="user"} 15722.203125

The memory gauge reads 0 here because the output comes from a single scrape: a formatted rate such as Cache Faults/sec needs two samples, so it reports a value from the second scrape on.

Note

If you are using a configuration file, the value must be keep as string.

Example:

collector:
  performancecounter:
    objects: |

Metrics

The perfdata collector returns metrics based on the user configuration. The metrics are named based on the object name and the counter name. The instance name is added as a label to the metric.

In addition, the collector exposes the following metrics for each configured object:

Name	Description	Type	Labels
windows_performancecounter_collector_success	Whether a performancecounter child collector was successful.	gauge	collector
windows_performancecounter_collector_duration_seconds	Duration of an performancecounter child collection.	gauge	collector

The collector label contains the configured object name.

Examples

thermalzone collector

collector:
  performancecounter:
    objects: |-
      - name: thermalzone
        object: "Thermal Zone Information"
        instances: ["*"]
        type: formatted
        counters:
          - name: "Temperature"
            type: "gauge"
            metric: windows_thermalzone_temperature_kelvin
          - name: "% Passive Limit"
            type: "gauge"
            metric: windows_thermalzone_percent_passive_limit
          - name: "Throttle Reasons"
            type: "gauge"
            metric: windows_thermalzone_throttle_reasons