Single Step APM Instrumentation on Windows
このページは日本語には対応しておりません。随時翻訳に取り組んでいます。
翻訳に関してご質問やご意見ございましたら、
お気軽にご連絡ください。
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.
Enable APM on Windows
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
To instrument only .NET applications running on IIS:
In Datadog, go to Install the Datadog Agent on Windows.
In the Customize your observability coverage section, toggle Application Performance Monitoring (APM).
(Optional) Set your SDK version:
By default, Single Step Instrumentation installs the latest supported version of the Datadog .NET SDK. If you need to pin a specific version:
- Under Instrumentation Configuration, select Customize Library Versions.
- Under .NET, choose the version you want to use.
Copy and run the provided MSI install command on your Windows host.
Restart the IIS applications you want instrumented. (You do not need to restart the entire IIS server.)
After installation, the Agent automatically loads the Datadog .NET SDK into supported application processes to enable distributed tracing.
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.
To instrument Java and .NET applications across your entire Windows host:
In Datadog, go to Install the Datadog Agent on Windows.
In the Customize your observability coverage section, toggle Application Performance Monitoring (APM).
(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:
- Under Instrumentation Configuration, select Customize Library Versions.
- Under .NET, choose the version you want to use.
Copy and run the provided MSI install command on your Windows host.
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.
Restart the services you want instrumented.
SSI adds a small amount of startup time to instrumented applications. If this overhead is not acceptable for your use case, contact
Datadog Support.
Existing Agent installation
If you already have a Datadog Agent installed, use Fleet Automation to enable SSI.
In Datadog, go to Fleet Automation > Configuration.
Click Configure Agents.
Apply filters to select the agents you want to configure, then click Next.
Click the Application Performance Monitoring (APM) tile, then click Next.
In the Configure SDKs Installation screen, click Yes to automatically install the SDKs. Select Use latest version, or uncheck to specify individual SDK versions.
Click Next.
Review your configuration and click Deploy Configuration.
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.
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.
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:
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 in your application configuration.
Advanced options
Define instrumentation rules
Instrumentation rules are not supported for your selected
Datadog site (
).
Instrumentation rules (available for Agent v7.73+) apply only to host-wide instrumentation. They are not supported for IIS-only installation.
Instrumentation rules let you control which processes are automatically instrumented by SSI on Windows hosts. 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.
To configure instrumentation rules:
In Datadog, go to APM > Service Setup > Manage Instrumentation Rules.
Click Add or Edit Rules.
Define instrumentation rules:
- Click Add New Rule, then choose Allow Rule or Block Rule to specify whether matching processes should be instrumented.
- Name your rule.
- Add one or more conditions. See Define rule conditions to learn more.
(Optional) Drag and drop rules to reorder them.
Note: Rules are evaluated in order. After a process matches a rule, subsequent rules are ignored.
Set the default behavior (allow or block) for processes that do not match any rule.
Click Next to preview your rules.
Click Deploy Rules.
If Remote Configuration is enabled, rules are deployed to every host and applied on those with SSI enabled within 50 seconds. Alternatively, click Export to export the configuration file and apply it manually to your hosts.
Define rule conditions
Each rule consists of one or more conditions. 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
Review the following examples demonstrating how to apply instrumentation rules:
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.
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. This approach is useful for gradual rollouts.
Remove Single Step APM instrumentation from your Agent
To disable SSI for .NET on your host, run:
&"C:\Program Files\Datadog\Datadog Agent\bin\datadog-installer.exe" remove datadog-apm-library-dotnet
Troubleshooting
If you encounter problems enabling APM with SSI, see the SSI troubleshooting guide.
Further reading
