---
title: Single Step APM Instrumentation on Windows
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > APM > Application Instrumentation > Single Step APM Instrumentation >
  Single Step APM Instrumentation on Windows
---

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

# Single Step APM Instrumentation on Windows

## Overview{% #overview %}

With Single Step Instrumentation (SSI), you can enable APM for your Java and .NET applications on Windows VMs using a single Datadog Agent installation command.

{% section %}Set up APM with an agentInstall the `dd-apm` skill in your AI coding agent for guided APM setup.
```shell
npx skills add https://github.com/datadog-labs/agent-skills --skill dd-apm --full-depth -y
```
{% /section %}

## Enable APM on Windows{% #enable-apm-on-windows %}

{% alert level="info" %}
Before proceeding, confirm that your environment is compatible by reviewing the [SSI compatibility guide.](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md)
{% /alert %}

### New Agent installation{% #new-agent-installation %}

If you don't yet have a Datadog Agent installed, follow these steps to install the Agent and enable SSI simultaneously.

You can enable APM on Windows in the following ways:

- Instrument only .NET applications on IIS
- Instrument all Java and .NET applications across your entire Windows host

{% tab title="IIS" %}
To instrument only .NET applications running on IIS:

1. From an administrator PowerShell session on your Windows host, run one of the following commands. Replace `<YOUR_DD_API_KEY>` with your [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) and `<YOUR_DD_SITE>` with your Datadog site: <YOUR_DATADOG_SITE>.

Use the PowerShell installer:

   ```powershell
   [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; $env:DD_API_KEY = '<YOUR_DD_API_KEY>'; $env:DD_SITE = '<YOUR_DD_SITE>'; $env:DD_APM_INSTRUMENTATION_ENABLED = 'iis'; $env:DD_APM_INSTRUMENTATION_LIBRARIES = 'dotnet:3'; (New-Object System.Net.WebClient).DownloadFile('https://install.datadoghq.com/datadog-installer-x86_64.exe', 'C:\Windows\SystemTemp\datadog-installer-x86_64.exe'); C:\Windows\SystemTemp\datadog-installer-x86_64.exe
   ```

Alternatively, install with the MSI:

   ```powershell
   $p = Start-Process -Wait -PassThru msiexec -ArgumentList '/qn /norestart /i "https://windows-agent.datadoghq.com/datadog-agent-7-latest.amd64.msi" /log C:\Windows\SystemTemp\install-datadog.log APIKEY="<YOUR_DD_API_KEY>" SITE="<YOUR_DD_SITE>" DD_APM_INSTRUMENTATION_ENABLED="iis" DD_APM_INSTRUMENTATION_LIBRARIES="dotnet:3"'
   if ($p.ExitCode -ne 0) { Write-Host "msiexec failed with exit code $($p.ExitCode) please check the logs at C:\Windows\SystemTemp\install-datadog.log" -ForegroundColor Red }
   ```

To install a different .NET version, change `dotnet:3`, or omit `DD_APM_INSTRUMENTATION_LIBRARIES` to install the latest.

**Note**: The Chocolatey installation method does not preserve the SSI settings and cannot be used to enable SSI.

1. Restart the IIS applications you want instrumented. (You do not need to restart the entire IIS server.)

The Agent then automatically loads the Datadog .NET SDK into supported application processes to enable distributed tracing.

**Generate the command from Datadog**: To get a command pre-filled with your API key and site, go to [Install the Datadog Agent on Windows](https://app.datadoghq.com/fleet/install-agent/latest?platform=windows) and, in the Customize your observability coverage section, toggle Application Performance Monitoring (APM). To pin the .NET SDK version, select Customize Library Versions under Instrumentation Configuration. Then copy and run the generated command.
{% /tab %}

{% tab title="Host-wide (Preview)" %}

{% alert level="info" %}
**Join the Preview!** Host-wide instrumentation for Windows is in Preview and limited to Preview participants. The installation and configuration options described in this tab appear in Datadog only after you are enrolled. Request access to join the Preview.
{% /alert %}

To instrument Java and .NET applications across your entire Windows host:

1. In Datadog, go to [Install the Datadog Agent on Windows](https://app.datadoghq.com/fleet/install-agent/latest?platform=windows).

1. In the Customize your observability coverage section, toggle Application Performance Monitoring (APM).

1. (Optional) Set your SDK version:

By default, Single Step Instrumentation installs the latest supported version of the Datadog .NET and Java SDK. If you need to pin a specific version:

   1. Under Instrumentation Configuration, select Customize Library Versions.
   1. Under .NET, choose the version you want to use.

1. Copy and run the provided installation command on your Windows host. Datadog generates this command in-app after you are enrolled in the Preview.

1. Configure instrumentation rules.

Host-wide SSI automatically instruments all Java applications on the host and all .NET applications running in IIS. To instrument .NET applications running outside of IIS, you must define an instrumentation rule that allows them. You can also use instrumentation rules for granular control over which Java applications on the host or .NET applications in IIS are instrumented.

1. Restart the services you want instrumented.

{% /tab %}

{% alert level="info" %}
SSI adds a small amount of startup time to instrumented applications. If this overhead is not acceptable for your use case, contact [Datadog Support](https://docs.datadoghq.com/help/).
{% /alert %}

### Existing Agent installation{% #existing-agent-installation %}

If you already have a Datadog Agent installed, enable SSI remotely from Datadog. You do not need to run commands on each host.

1. In Datadog, go to [**APM > Instrument a Service**](https://app.datadoghq.com/apm/instrumentation).

1. Under How do you want to instrument these hosts?, select Deploy on existing hosts to instrument your services remotely through the Datadog Agent.

1. Under Which hosts should we instrument?, use the scope filters (Environments, Hostname, APM enabled) to narrow down your hosts. Then select the Agents you want to instrument on the Eligible for deployment tab. Hosts that can't be instrumented appear on the Excluded from deployment tab.

1. In Configure SDKs installation, click Yes to have Datadog automatically install the tracing SDKs. To pin specific SDK versions instead of the latest, expand Customize library versions.

1. In Configure rollout strategy, choose what percentage of Agents to deploy to at a time. Datadog shows the resulting stages and an estimated duration. Deployments automatically pause if three consecutive Agents fail or if failures reach 10% of the total. You can re-run the deployment later.

1. In Review and apply APM instrumentation, check the Configuration Summary (toggle between Summary and YAML), then click Apply Instrumentation.

1. Configure instrumentation rules.

Host-wide SSI automatically instruments all Java applications on the host and all .NET applications running in IIS. To instrument .NET applications running outside of IIS, you must define an instrumentation rule that allows them. You can also use instrumentation rules for granular control over which Java applications on the host or .NET applications in IIS are instrumented.

## Verify the installation{% #verify-the-installation %}

1. From an administrator PowerShell session, confirm the Agent is healthy and the APM Agent is running:

   ```powershell
   & "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" status
   ```

Check the **APM Agent** section of the output.

1. After your instrumented applications receive traffic, confirm your services appear on the [APM Services page](https://app.datadoghq.com/apm/services). If they don't appear within a few minutes, follow the [SSI troubleshooting guide](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm/troubleshooting.md).

## Configure Unified Service Tags{% #configure-unified-service-tags %}

Unified Service Tags (USTs) apply consistent tags across traces, metrics, and logs, making it easier to navigate and correlate your observability data. Learn how to [set USTs for Windows services](https://docs.datadoghq.com/integrations/windows-service.md#tags).

## Enable SDK-dependent products and features{% #enable-sdk-dependent-products-and-features %}

After SSI loads the Datadog SDK into your applications and enables distributed tracing, you can configure additional products that rely on the SDK:

| Product                                                                                                             | Environment variable                 |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| [Runtime Metrics](https://docs.datadoghq.com/tracing/metrics/runtime_metrics.md)                                    | `DD_RUNTIME_METRICS_ENABLED`         |
| [Log Injection](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces.md)                      | `DD_LOGS_INJECTION`                  |
| [Continuous Profiler](https://docs.datadoghq.com/profiler.md)                                                       | `DD_PROFILING_ENABLED`               |
| [Data Streams Monitoring](https://docs.datadoghq.com/data_streams.md)                                               | `DD_DATA_STREAMS_ENABLED`            |
| [App and API Protection](https://docs.datadoghq.com/security/application_security.md)                               | `DD_APPSEC_ENABLED`                  |
| [Runtime Code Analysis (IAST)](https://docs.datadoghq.com/security/code_security/iast.md)                           | `DD_IAST_ENABLED`                    |
| [Dynamic Instrumentation](https://docs.datadoghq.com/tracing/trace_collection/dynamic_instrumentation.md)           | `DD_DYNAMIC_INSTRUMENTATION_ENABLED` |
| [Data Jobs Monitoring](https://docs.datadoghq.com/data_jobs.md)                                                     | `DD_DATA_JOBS_ENABLED`               |
| [Software Composition Analysis](https://docs.datadoghq.com/security/code_security/software_composition_analysis.md) | `DD_APPSEC_SCA_ENABLED`              |

**Note**: All variables accept `true` or `false`. `DD_PROFILING_ENABLED` also accepts `auto`, which profiles only eligible processes and is recommended for SSI.

To enable products, [set environment variables](https://docs.datadoghq.com/tracing/trace_collection/library_config.md) in your application configuration.

## Advanced options{% #advanced-options %}

### Define instrumentation rules{% #define-instrumentation-rules %}

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com



{% alert level="warning" %}
Instrumentation rules are not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md) ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}


{% /callout %}

{% callout %}
# Important note for users on the following Datadog sites: app.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com



{% alert level="info" %}
Instrumentation rules apply only to host-wide instrumentation. They are not supported for IIS-only installation.
{% /alert %}


{% /callout %}

Instrumentation rules let you control which processes SSI automatically instruments on Windows hosts. Each rule matches process attributes, then allows or blocks instrumentation for matching processes. Rules are required to instrument .NET applications running outside of IIS. They are also useful for granular control over which Java applications on the host or .NET applications in IIS are instrumented.

You can deploy a rule to all eligible hosts, or scope it to one or more host groups to limit where it applies.

To view and manage instrumentation rules, go to APM > Instrument a Service > [Instrumentation Rules](https://app.datadoghq.com/apm/service-setup/workload-selection).

{% image
   source="https://docs.dd-static.net/images/tracing/trace_collection/apm-instrumentation-rules-for-hosts.39a1e6f6bad8f9ea219ebb6909081ecd.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/apm-instrumentation-rules-for-hosts.39a1e6f6bad8f9ea219ebb6909081ecd.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The APM Instrumentation Rules page with Hosts selected, showing the Default Behavior, Hosts in Scope, and Deployment Status cards above a list of instrumentation rules" /%}

#### Prerequisites for instrumentation rules{% #prerequisites-for-instrumentation-rules %}

- **Agent**: v7.73 or later on each host, with SSI and [Remote Configuration](https://docs.datadoghq.com/remote_configuration.md) enabled. Hosts that meet these requirements are eligible for instrumentation rules.
- **Permissions**: The **APM Workload Selection Write** [permission](https://docs.datadoghq.com/account_management/rbac/permissions.md), which is required to create and manage instrumentation rules and host groups.

#### Set the default behavior{% #set-the-default-behavior %}

The default behavior applies to processes on eligible hosts that do not match any instrumentation rule. It also applies when you have not created any rules.

1. On the [Instrumentation Rules](https://app.datadoghq.com/apm/service-setup/workload-selection) page, go to the Default Behavior card and click Edit.
1. Select one of the following options:
   - Allow everything else: Supported applications are instrumented unless a rule blocks them. The exception is .NET applications running outside of IIS, which remain blocked unless a rule allows them.
   - Block everything else: Applications are not instrumented unless a rule allows them.
1. Click Save.

#### Create host groups{% #create-host-groups %}

Host groups are reusable collections of hosts that you can target with instrumentation rules.

To create a host group:

1. On the [Instrumentation Rules](https://app.datadoghq.com/apm/service-setup/workload-selection) page, go to the Hosts in Scope card and click Manage host groups.

1. Click New Host Group and enter a name for the group.

1. Click Add Hosts, then search for and select the hosts to add. You can search by hostname, facets, or host tags.
Important alert (level: info): Host groups are dynamic, so new hosts that match your search are added to the group automatically. A host can belong to more than one group, but all hosts in a group must run on the same platform, such as Linux or Windows.
   {% image
      source="https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-add-hosts.e6b0fc767f0cc049a1d02a03b2d414dc.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-add-hosts.e6b0fc767f0cc049a1d02a03b2d414dc.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="The new host group form, with two of three hosts selected in the Add Hosts list" /%}

1. Click Save Group.

Datadog maintains an All hosts group automatically. It lists the eligible hosts that do not belong to any other group, so you can see which hosts are left to group. You cannot edit its host list.

If you delete a host group, Datadog removes the group's rules, and the Agent stops applying them the next time it polls Remote Configuration.

To change the order of host groups, drag a group by its handle in the group list. Group order affects how instrumentation rules are evaluated.

{% image
   source="https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-host-groups.943be7fb1c5555aceb4d5f0c81e7a583.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-host-groups.943be7fb1c5555aceb4d5f0c81e7a583.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The Host Groups page, showing a Canary group ordered above the All hosts group, with the Canary group's hosts listed" /%}

#### Create instrumentation rules{% #create-instrumentation-rules %}

**Note**: You can use Bits AI to create instrumentation rules with natural language. In the Create instrumentation rule window, click Generate with Bits and describe which processes to instrument. Bits AI generates the corresponding rule.

To create an instrumentation rule:

1. On the [Instrumentation Rules](https://app.datadoghq.com/apm/service-setup/workload-selection) page, click New Rule. Alternatively, on the Host Groups page, select a group, open its Rules tab, and click Create a new rule.

1. Define one or more conditions, then select Block Instrumentation or Allow Instrumentation. See the Define rule conditions section.

   {% image
      source="https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-create-rule.8cfe420c99dfafcfeda4f90ab60bac7f.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-create-rule.8cfe420c99dfafcfeda4f90ab60bac7f.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="The Create instrumentation rule window, with a condition of Language equals Python, the Allow Instrumentation action, and the Rule Impact Preview panel" /%}

1. Under Set host targeting, select All eligible hosts or Select host groups.

If you select more than one group, the groups share a single rule, and editing it later updates every selected group.

   {% image
      source="https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-host-targeting.6eed8e193acb4b36a6b051b25320b6f5.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-host-targeting.6eed8e193acb4b36a6b051b25320b6f5.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="The Set host targeting step, with Select host groups chosen and a host group named Test selected" /%}

1. Name the rule, then click Next.

1. Review the rule. Datadog adds new rules to the end of each targeted group's rule list. Optionally, under Set evaluation order, drag rules to change their order in each group. See the How instrumentation rules are evaluated section.

   {% image
      source="https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-review-order.15543c82fff1a7ead101c8606fc3caa5.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-review-order.15543c82fff1a7ead101c8606fc3caa5.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="The rule review step, showing the rule summary and the evaluation order of rules in the Test host group" /%}

1. Click Create Rule.

Datadog deploys rules to eligible hosts through Remote Configuration within 50 seconds. After the rules are deployed, restart the affected services for the changes to take effect. The Deployment Status card on the [Instrumentation Rules](https://app.datadoghq.com/apm/service-setup/workload-selection) page shows how many eligible hosts have received the current rules.

To apply rules manually, such as on hosts without Remote Configuration enabled, click Export above the rules list to export the configuration file, then apply it to your hosts.

#### How instrumentation rules are evaluated{% #how-instrumentation-rules-are-evaluated %}

For each process, Datadog evaluates instrumentation rules in the following order and applies the first rule that matches:

1. Rules from the groups that the process's host belongs to, in group order from top to bottom. Within each group, rules are evaluated in the order set under Set evaluation order.
1. Rules that target All eligible hosts. These rules apply to every eligible host, including hosts in host groups.

If no rule matches, the default behavior applies.

#### Define rule conditions{% #define-rule-conditions %}

Each rule consists of one or more conditions. A process must match all of a rule's conditions for the rule to apply. A condition includes the following elements:

- Attribute: The process property that the rule evaluates.
- Operator: The comparison logic (`equals`, `not equals`, `prefix`, or `contains`).
- Value: The text or pattern to match, such as a process name or command-line flag.

Supported attributes include:

| Attribute            | Description                                                                                                                                                                       | Example                                |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Operating System     | OS of the host.                                                                                                                                                                   | `windows`                              |
| Executable           | Executable name of the process.                                                                                                                                                   | `w3wp.exe`                             |
| Executable Full Path | Full path of the executable.                                                                                                                                                      | `C:\Windows\System32\inetsrv\w3wp.exe` |
| Arguments            | Command-line arguments used to start the process.                                                                                                                                 | `--env=production`                     |
| Working Directory    | Working directory of the process.                                                                                                                                                 | `C:\inetpub\wwwroot`                   |
| Language             | Programming language detected for the process.                                                                                                                                    | `dotnet`                               |
| Entry Point File     | The specific file used to launch the application.                                                                                                                                 | `MyService.dll`, `app.py`              |
| IIS Application Pool | The IIS application pool hosting the worker process. Because all IIS workers share the `w3wp.exe` executable, this is the most reliable way to target a specific .NET app on IIS. | `DefaultAppPool`, `MyWebApp`           |

#### Example use cases{% #example-use-cases %}

Review the following examples demonstrating how to apply instrumentation rules:

{% collapsible-section %}
##### Example 1: Instrument all processes except specific ones

Instrument all processes by default. Add block rules to exclude services that would add noise without value, such as analytics cron jobs and Java batch processors.

1. Set the default behavior to Allow everything else.
1. Create the following rules, each targeting All eligible hosts:
| Rule name                  | Condition                                           | Action                |
| -------------------------- | --------------------------------------------------- | --------------------- |
| Exclude analytics cron job | `Working Directory` `contains` `analytics-service`  | Block Instrumentation |
| Exclude batch services     | `Entry Point File` `contains` `batch-processor.jar` | Block Instrumentation |

{% /collapsible-section %}

{% collapsible-section %}
##### Example 2: Instrument only specific IIS applications

Block all instrumentation by default. Add allow rules to opt specific IIS applications into APM. Because all IIS workers share the `w3wp.exe` executable, use IIS Application Pool to identify target applications.

For example, to instrument only a checkout application and a customer portal:

1. Set the default behavior to Block everything else.
1. Create the following rules, each targeting All eligible hosts:
| Rule name       | Condition                                            | Action                |
| --------------- | ---------------------------------------------------- | --------------------- |
| Checkout        | `IIS Application Pool` `equals` `CheckoutPool`       | Allow Instrumentation |
| Customer portal | `IIS Application Pool` `equals` `CustomerPortalPool` | Allow Instrumentation |

{% /collapsible-section %}

{% collapsible-section %}
##### Example 3: Roll out instrumentation gradually with a host group

Block all instrumentation by default, and allow it only on a small set of canary hosts. After you validate the results, add more hosts to the group, or change the rule to target all eligible hosts.

1. Set the default behavior to Block everything else.
1. Create a host group named `canary` and add the hosts to instrument first.
1. Create a rule with the following settings:
| Setting        | Value                        |
| -------------- | ---------------------------- |
| Condition      | `Language` `equals` `java`   |
| Action         | Allow Instrumentation        |
| Host targeting | Select host groups: `canary` |

Only Java applications on hosts in the `canary` group are instrumented. All other applications are not instrumented.
{% /collapsible-section %}

## Remove Single Step APM instrumentation from your Agent{% #remove-single-step-apm-instrumentation-from-your-agent %}

To disable SSI for .NET on your host, run:

```shell
&"C:\Program Files\Datadog\Datadog Agent\bin\datadog-installer.exe" remove datadog-apm-library-dotnet
```

## Troubleshooting{% #troubleshooting %}

If you encounter problems enabling APM with SSI, see the [SSI troubleshooting guide](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm/troubleshooting.md).

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Enable Runtime Metrics](https://docs.datadoghq.com/tracing/metrics/runtime_metrics.md)
