Windowsperfcounters Receiver

Available in: contrib Maintainers: @dashpole, @alxbl, @pjanotti Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

This receiver is based on the Telegraf Windows Performance Counters Input Plugin. If one of the specified performance counters cannot be loaded on startup, a warning will be printed, but the application will not fail fast. It is expected that some performance counters may not exist on some systems due to different OS configuration.

Configuration

The collection interval and the list of performance counters to be scraped can be configured:

windows_perf_counters:
  collection_interval: <duration> # default = "1m"
  initial_delay: <duration> # default = "1s"
  metrics:
    <metric name>:
      description: <description>
      unit: <unit type>
      gauge:
    <metric name>:
      description: <description>
      unit: <unit type>
      sum:
        aggregation: <cumulative or delta>
        monotonic: <true or false>
  perfcounters:
    - object: <object name>
      instances: [<instance name>]*
      aggregation_name: <aggregation instance name> # default = "_Total"
      counters:
        - name: <counter name>
          metric: <metric name>
          attributes:
            <key>: <value>
          recreate_query: <true or false>

Understanding the `instances` configuration option

Value	Interpretation
Not specified	This is the only valid value if the counter has no instances.
`"*"`	All instances, excluding the configured aggregation instance (`_Total` by default).
`["*", "_Total"]`	All instances, including `_Total`, with the `instance` attribute preserved.
`"_Total"`	The “total” instance, that aggregates the values of all other instances. See below for its special treatment.
`"instance1"`	A single instance.
`["instance1", "instance2", ...]`	A set of instances.

Aggregation instances

By default, the receiver treats _Total as the aggregation instance. When a query returns _Total with other instances, _Total is omitted because it can be derived in the backend. When _Total is collected by itself, its instance attribute is omitted. Set aggregation_name to change which instance receives this treatment. For example, aggregation_name: "_Global_" omits _Global_ instead of _Total. To retain the aggregation instance alongside the wildcard results, explicitly include its name in instances. This still creates one wildcard query:

windows_perf_counters:
  metrics:
    processor.time:
      description: CPU active and idle time
      unit: "%"
      gauge:
  collection_interval: 30s
  perfcounters:
    - object: "Processor"
      instances: ["*", "_Total"]
      counters:
        - name: "% Processor Time"
          metric: processor.time

For a counter whose aggregation instance has a different name, configure that name consistently in both fields. For example:

perfcounters:
  - object: "Custom Object"
    instances: ["*", "_Global_"]
    aggregation_name: "_Global_"
    counters:
      - name: "Custom Counter"

[!WARNING] Retaining an aggregation instance alongside its component instances can cause double-counting. Prefer deriving aggregate values in the backend when possible.

Recreating the query on every scrape

On some versions of Windows, Counters are sometimes corrupted and continuously return invalid data after the first scrape. When/If this happens, it is possible to set the counter setting recreate_query to true (defaults to false) to tell the receiver to recreate the PDH query on every scrape. This has slight performance implications but should be inconsequential unless collection_interval is very aggressive. If re-creating the query fails, the previous query will be re-used and an error will be logged.

Scraping at different frequencies

If you would like to scrape some counters at a different frequency than others, you can configure multiple windows_perf_counters receivers with different collection_interval values. For example:

receivers:
  windows_perf_counters/memory:
    metrics:
      bytes.committed:
        description: the number of bytes committed to memory
        unit: By
        gauge:
    collection_interval: 30s
    perfcounters:
      - object: Memory
        counters:
          - name: Committed Bytes
            metric: bytes.committed

  windows_perf_counters/processor:
    collection_interval: 1m
    metrics:
      processor.time:
        description: active and idle time of the processor
        unit: "%"
        gauge:
    perfcounters:
      - object: "Processor"
        instances: "*"
        counters:
          - name: "% Processor Time"
            metric: processor.time
            attributes:
              state: active
      - object: "Processor"
        instances: ["1", "2"]
        counters:
          - name: "% Idle Time"
            metric: processor.time
            attributes:
              state: idle

service:
  pipelines:
    metrics:
      receivers: [windows_perf_counters/memory, windows_perf_counters/processor]

Defining metric format

To report metrics in the desired output format, define a metric and reference it in the corresponding counter, along with any applicable attributes. The metric’s data type can either be gauge (default) or sum.

Field Name	Description	Value	Default
name	The key for the metric.	string	Counter Name
description	definition of what the metric measures.	string
unit	what is being measured.	string	`1`
sum	representation of a sum metric.	Sum Config
gauge	representation of a gauge metric.	Gauge Config

Sum Config

Field Name	Description	Value	Default
aggregation	The type of aggregation temporality for the metric.	[`cumulative` or `delta`]
monotonic	whether or not the metric value can decrease.	false

Gauge Config

A gauge config currently accepts no settings. It is specified as an object for forwards compatibility. e.g. To output the Memory/Committed Bytes counter as a metric with the name bytes.committed:

receivers:
  windows_perf_counters:
    metrics:
      bytes.committed:
        description: the number of bytes committed to memory
        unit: By
        gauge:
    collection_interval: 30s
    perfcounters:
    - object: Memory
      counters:
        - name: Committed Bytes
          metric: bytes.committed

service:
  pipelines:
    metrics:
      receivers: [windows_perf_counters]

Known Limitation

The network interface is not available inside the container. Hence, the metrics for the object Network Interface aren’t generated in that scenario. In the case of sub-process, it captures Network Interface metrics. There is a similar open issue in GitHub and Docker forum.
The counter category Process is unreliable with multiple instances of the same process. On Windows 11 and later, it is recommended to use Process V2 instead as it includes the process ID in the instance name. For versions prior to Windows 11 it is possible to configure the Process counter category to include the PID in the instance name.

Configuration

Example Configuration

windows_perf_counters:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
  perfcounters:
    - object: "object"
      counters:
        - name: counter1
          metric: metric

windows_perf_counters/customname:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
    metric2:
      description: desc
      unit: "1"
      gauge:
  collection_interval: 30s
  perfcounters:
    - object: object1
      instances: ["*", "_Global_"]
      aggregation_name: "_Global_"
      counters:
        - name: counter1
          metric: metric
    - object: object2
      counters:
        - name: counter1
          metric: metric
        - name: counter2
          metric: metric2

windows_perf_counters/nometricspecified:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
  perfcounters:
    - object: "object"
      counters:
        - name: counter1

windows_perf_counters/unspecifiedmetrictype:
  metrics:
    metric:
      description: desc
      unit: "1"
  perfcounters:
    - object: "object"
      counters:
        - name: counter1
          metric: metric

windows_perf_counters/summetric:
  metrics:
    metric:
      description: desc
      unit: "1"
      sum:
        aggregation: cumulative
  perfcounters:
    - object: "object"
      counters:
        - name: counter1
          metric: metric

windows_perf_counters/nometrics:
  perfcounters:
    - object: "object"
      counters:
        - name: counter1

windows_perf_counters/allerrors:
  collection_interval: -1m
  perfcounters:
    -
    - object: "object"
      instances: [ "instance", "", "*" ]

windows_perf_counters/emptyinstance:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
  perfcounters:
    - object: "object"
      instances: [ "" ]
      counters:
        - name: counter
          metric: metric

windows_perf_counters/negative-collection-interval:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
  collection_interval: -1m
  perfcounters:
    - object: "object"
      counters:
        - name: counter1
          metric: metric

windows_perf_counters/nocounters:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
  perfcounters:
    - object: "object"

windows_perf_counters/noobjectname:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
  perfcounters:
    - counters:

windows_perf_counters/noperfcounters:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:

Last generated: 2026-08-24

​Windowsperfcounters Receiver

​Supported Telemetry

​Overview

​Configuration

​Understanding the instances configuration option

​Aggregation instances

​Recreating the query on every scrape

​Scraping at different frequencies

​Defining metric format

​Sum Config

​Gauge Config

​Known Limitation

​Configuration

​Example Configuration

Windowsperfcounters Receiver

Supported Telemetry

Overview

Configuration

Understanding the `instances` configuration option

Aggregation instances

Recreating the query on every scrape

Scraping at different frequencies

Defining metric format

Sum Config

Gauge Config

Known Limitation

Configuration

Example Configuration