---
title: PowerShell
description: Collect custom metrics from allowlisted read-only PowerShell cmdlets.
breadcrumbs: Docs > Integrations > PowerShell
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# PowerShell
Supported OS Integration version1.0.0
{% callout %}
# Important note for users on the following Datadog sites: us2.ddog-gov.com

{% alert level="info" %}
To find out if this integration is available in your organization, see your [Datadog Integrations](https://app.datadoghq.com/integrations) page or ask your organization administrator.

To initiate an exception request to enable this integration for your organization, email [support@ddog-gov.com](mailto:support@ddog-gov.com).
{% /alert %}

{% /callout %}

## Overview{% #overview %}

Collect custom metrics from read-only PowerShell `Get-*` cmdlets on Windows hosts. The integration maps cmdlet output properties to metrics and tags. This lets you monitor Windows and application state exposed through PowerShell.

For security, the integration runs only cmdlets and parameters explicitly permitted in an administrator-owned allowlist.

**Minimum Agent version:** 7.85.0

## Setup{% #setup %}

### Installation{% #installation %}

The PowerShell integration is included in the [Datadog Agent](https://app.datadoghq.com/account/settings/agent/latest?platform=windows) package. No additional installation is needed.

### Configuration{% #configuration %}

1. Create or edit the allowlist at `C:\ProgramData\Datadog\protected\powershell_allowlist.yaml` to permit the read-only cmdlets and parameters that the Agent may run. See the [sample PowerShell allowlist](https://github.com/DataDog/datadog-agent/blob/main/cmd/agent/dist/protected/powershell_allowlist.yaml.example) for an example. The allowlist must be owned by Administrators or SYSTEM. The check fails closed if the file is missing, invalid, or owned by another user.

The following example permits the check to query listening TCP connections and correlate them with running processes:

   ```yaml
   version: 1
   allowed_cmdlets:
     Get-NetTCPConnection:
       module: NetTCPIP
       parameters:
         State:
           required: false
           allowed_values:
             - Listen
     Get-Process:
       module: Microsoft.PowerShell.Management
   ```
Allowlist options: 
| Option                                                           | Type            | Required                | Description                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------- | --------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`                                                        | integer         | Yes                     | Allowlist schema version. The only supported value is `1`.                                                                                                                                                                                                             |
| `allowed_cmdlets`                                                | mapping         | Yes                     | Cmdlets that the check may run. The mapping must contain at least one entry, and each key must be a read-only cmdlet name in the form `Get-<Noun>`.                                                                                                                    |
| `allowed_cmdlets.<cmdlet>.module`                                | string          | Yes                     | Module that the cmdlet must resolve to at runtime. Use the value returned by `(Get-Command <cmdlet>).ModuleName`. Use `"*"` to explicitly skip module validation.                                                                                                      |
| `allowed_cmdlets.<cmdlet>.parameters`                            | mapping         | No                      | Parameters that instances may pass to the cmdlet. Undeclared parameters are rejected. Parameter names may contain letters, numbers, and underscores.                                                                                                                   |
| `allowed_cmdlets.<cmdlet>.parameters.<parameter>.required`       | boolean         | No; defaults to `false` | Whether every instance using the cmdlet must include this entry in `parameters`.                                                                                                                                                                                       |
| `allowed_cmdlets.<cmdlet>.parameters.<parameter>.allowed_values` | list of strings | Conditional             | Case-sensitive exact values permitted for the parameter. Boolean and numeric instance values are compared using their string forms. Every declared parameter must define `allowed_values` or `pattern`. If both are set, `allowed_values` is used for validation.      |
| `allowed_cmdlets.<cmdlet>.parameters.<parameter>.pattern`        | string          | Conditional             | Case-sensitive Go RE2 expression defining permitted values. The expression is automatically anchored and must match the entire parameter value. RE2 does not support lookaround or backreferences. Every declared parameter must define `pattern` or `allowed_values`. |

Unknown options cause the allowlist to be rejected. Cmdlet and parameter names are case-sensitive and must match the instance configuration. The allowlist constrains cmdlets and their `parameters`; `where` only removes output rows and does not need an allowlist entry. Cmdlets referenced by `tag_queries` must also appear in `allowed_cmdlets`. Tag queries invoke their target cmdlets without parameters, so those cmdlets cannot have any required allowlist parameters. Runtime module validation still applies.

1. Edit `powershell.d/conf.yaml` in the `conf.d` folder at the root of the Agent's [configuration directory](https://docs.datadoghq.com/agent/configuration/agent-configuration-files.md?tab=agentv6v7#agent-configuration-directory). See the [sample `powershell.d/conf.yaml`](https://github.com/DataDog/datadog-agent/blob/main/cmd/agent/dist/conf.d/powershell.d/conf.yaml.example) for all available configuration options.

The following example submits a constant custom metric for each listening TCP connection whose local address does not match `127.*`. It also runs `Get-Process` and joins `OwningProcess` from each connection to `Id` from each process to add a `process_name` tag:

   ```yaml
   instances:
     - cmdlet: Get-NetTCPConnection
       name: powershell
       parameters:
         - [State, Listen]
       where:
         - [LocalAddress, notlike, '127.*']
       tags:
         - connection_state:listen
       metrics:
         - [1, tcp_connection.info, gauge]
       tag_by:
         - LocalAddress AS local_address
         - LocalPort AS local_port
       tag_queries:
         - [OwningProcess, Get-Process, Id, ProcessName AS process_name]
   ```

The equivalent PowerShell commands are:

   ```powershell
   Get-NetTCPConnection -State Listen |
     Where-Object -Property LocalAddress -NotLike -Value '127.*' |
     Select-Object LocalAddress, LocalPort, OwningProcess
   
   Get-Process |
     Select-Object Id, ProcessName
   ```

The `parameters` option passes allowlisted named arguments directly to the cmdlet, while `where` filters the returned objects using PowerShell `Where-Object` semantics before selecting properties. All `where` entries must match for a row to be retained. The check then joins the results where `OwningProcess` equals `Id`.

This configuration submits `powershell.tcp_connection.info`. A metric property may be a numeric property returned by the cmdlet or the literal `1` for a constant value. Non-numeric properties can be translated with the metric mapping form described in the sample configuration. Supported metric types are `gauge`, `rate`, `count`, `monotonic_count`, `histogram`, and `distribution`.

1. [Restart the Agent](https://docs.datadoghq.com/agent/guide/agent-commands.md#restart-the-agent).

### Validation{% #validation %}

[Run the Agent's status subcommand](https://docs.datadoghq.com/agent/basic_agent_usage/windows.md?tab=gui#agent-status-and-information) and look for `powershell` under the **Checks** section.

## Data Collected{% #data-collected %}

### Metrics{% #metrics %}

The PowerShell integration does not include default metrics. All metrics configured through this integration are forwarded to Datadog as [custom metrics](https://docs.datadoghq.com/account_management/billing/custom_metrics.md), which may impact your billing.

### Events{% #events %}

The PowerShell integration does not include any events.

### Service Checks{% #service-checks %}

The PowerShell integration does not include any service checks.

## Troubleshooting{% #troubleshooting %}

Need help? Contact [Datadog support](https://docs.datadoghq.com/help/) with an [Agent Flare](https://docs.datadoghq.com/agent/troubleshooting/send_a_flare.md?tab=agentv6v7).
