> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Windowsperfcounters

> OpenTelemetry receiver for Windowsperfcounters

# Windowsperfcounters Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@dashpole](https://github.com/dashpole), [@alxbl](https://github.com/alxbl), [@pjanotti](https://github.com/pjanotti)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/windowsperfcountersreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-beta-green)

## Overview

This receiver is based on the [Telegraf Windows Performance Counters Input
Plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/win_perf_counters).

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:

```yaml theme={null}
windowsperfcounters:
  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>]*
      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 `_Total`.                                                                            |
| `"_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 counter and the behavior of the `_Total` instance

The `_Total` must be collected individually on its own metric,
since it is dropped when collected together with other instances.

```yaml theme={null}
windowsperfcounters:
  metrics:
    processor.time.total:
      description: Total CPU active and idle time
      unit: "%"
      gauge:
  collection_interval: 30s
  perfcounters:
    - object: "Processor"
      instances:
          - "_Total"
      counters:
        - name: "% Processor Time"
          metric: processor.time.total
```

> \[!WARNING]
> When using the `"*"` for `instances`, check what is the aggregation
> instance used by the counter. If the counter uses something other than `_Total`,
> e.g.: `_Global_`, special care is needed to avoid double-counting when
> aggregating the metrics after they are scraped by the receiver.

### 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 `windowsperfcounters` receivers with different
`collection_interval` values. For example:

```yaml theme={null}
receivers:
  windowsperfcounters/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

  windowsperfcounters/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: [windowsperfcounters/memory, windowsperfcounters/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`:

```yaml theme={null}
receivers:
  windowsperfcounters:
    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: [windowsperfcounters]
```

## 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](https://github.com/influxdata/telegraf/issues/5357) and [Docker](https://forums.docker.com/t/unable-to-collect-network-metrics-inside-windows-container-on-windows-server-2016-data-center/69480) forum.

* The counter category `Process` is [unreliable with multiple instances of the same process][1]. 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][2].

[1]: https://learn.microsoft.com/en-us/windows/win32/perfctrs/collecting-performance-data#understanding-multiple-processor-counters

[2]: https://learn.microsoft.com/en-us/windows/win32/perfctrs/handling-duplicate-instance-names

## Configuration

### Example Configuration

```yaml theme={null}
windowsperfcounters:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
  perfcounters:
    - object: "object"
      counters:
        - name: counter1
          metric: metric

windowsperfcounters/customname:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
    metric2:
      description: desc
      unit: "1"
      gauge:
  collection_interval: 30s
  perfcounters:
    - object: object1
      counters:
        - name: counter1
          metric: metric
    - object: object2
      counters:
        - name: counter1
          metric: metric
        - name: counter2
          metric: metric2

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

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

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

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

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

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

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

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

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

windowsperfcounters/noperfcounters:
  metrics:
    metric:
      description: desc
      unit: "1"
      gauge:
```

***

*Last generated: 2026-07-06*