Basic Agent Usage for Windows

Docs > Agent > Basic Agent Usage > Basic Agent Usage for Windows

Overview

This page outlines the basic features of the Datadog Agent for Windows. If you haven’t installed the Agent yet, see the installation instructions below or follow the instructions in the app.

Install the Datadog Agent

Requirements

Windows version: Windows Server 2016 or later, or Windows 10 or later. See the Agent Supported Platforms documentation for supported OS versions.
Datadog account: Ensure you have access to a Datadog account and have your Datadog API key.
Administrator privileges: Administrator access is required on the Windows machine.

The core and APM/trace components of the Windows Agent run under the ddagentuser account. The Live Processes component, if enabled, runs under the LOCAL_SYSTEM account. Learn more about the Datadog Windows Agent User.

Install with the GUI

The default installation location for the Agent is %ProgramFiles%\Datadog\Datadog Agent. If you choose to use a custom installation location, ensure that you specify a Datadog subdirectory for the Datadog files.

Download the Datadog Agent installer to install the latest version of the Agent.
Run the installer by opening datadog-agent-7-latest.amd64.msi. When prompted, enter your Administrator credentials.
Follow the prompts, accept the license agreement, and enter your Datadog API key.

When the install finishes, you are given the option to launch the Datadog Agent Manager.

Install with the command line

Open PowerShell with Administrator privileges.

Run the following command to install the Datadog Agent:

Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-agent-7-latest.amd64.msi APIKEY="<YOUR_DATADOG_API_KEY>"'

When deploying the Datadog Agent in an Active Directory environment, Datadog recommends using a Group Managed Service Account (gMSA).

Using gMSA can enhance security and simplify management. Some of the benefits include:

Deployment across multiple servers: Unlike traditional Managed Service Accounts (MSAs) or standalone Managed Service Accounts (sMSAs), gMSAs can be deployed across multiple servers.
Automated password management: The passwords for gMSAs are handled at the operating system level, and are rotated on a regular basis without requiring manual intervention.

When running with a gMSA, the core and APM/trace components of the Windows Agent run under the configured account. The Live Processes component, if enabled, runs under the LOCAL_SYSTEM account. Learn more about the Datadog Windows Agent User.

Prerequisites

An Active Directory environment
Permission to create and manage gMSAs
See further requirements in the Microsoft documentation.

Note: For a comprehensive understanding of setting up gMSAs, see Microsoft’s Group Managed Service Accounts Overview.

Create and configure a gMSA

Create a Security Group:
1. Open Active Directory Users and Computers (ADUC).
2. Navigate to the appropriate Organizational Unit (OU).
3. Right-click and select New > Group.
4. Name the group. For example, DatadogAgentsGroup.
5. Set the correct group scope for your organization. For example, Domain local.
6. Set the type to Security.
Create the gMSA:
1. Open PowerShell with Administrator privileges.
2. Run the following command to create the gMSA, replacing <YOUR_DOMAIN_NAME> with your domain name:
```
New-ADServiceAccount -Name DatadogGMSA -DNSHostName <YOUR_DOMAIN_NAME> -PrincipalsAllowedToRetrieveManagedPassword DatadogAgentsGroup
```
Verify that the gMSA can be used on the target machine:
1. Ensure the target machine is part of the DatadogAgentsGroup.
2. On the target machine, open PowerShell and run:
```
Install-ADServiceAccount -Identity DatadogGMSA
```
  Ensure the command ran without errors.

Install the Agent

Follow the instructions below to install the latest version of the Datadog Agent. If you need to install a specific version of the Agent, see the installer list.

Install via the GUI

Download the Datadog Agent installer to install the latest version of the Agent.
Run the installer by opening datadog-agent-7-latest.amd64.msi. When prompted, enter your Administrator credentials.
Follow the prompts, accept the license agreement, and enter your Datadog API key.
When prompted for the “Datadog Agent User Account”, enter the username of the gMSA. For example, <YOUR_DOMAIN_NAME>\DatadogGMSA$ and no password. When the install finishes, you are given the option to launch the Datadog Agent Manager.

Install with the command line

Open PowerShell with Administrator privileges.
Run the following command to install the Datadog Agent:

Note: Replace DatadogGMSA$ with the username of your gMSA. The username must end with a $ symbol.

Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-agent-7-latest.amd64.msi APIKEY="<YOUR_DATADOG_API_KEY>" DDAGENTUSER_NAME="<YOUR_DOMAIN_NAME>\DatadogGMSA$"'

Installation configuration options

Each of the following configuration options can be added as a property to the command line when installing the Agent on Windows. For additional Agent configuration options, see more Agent configuration options.

Variable	Type	Description
`APIKEY`	String	Adds the Datadog API KEY to the configuration file.
`SITE`	String	Set the Datadog intake site, for example: `SITE=`
`TAGS`	String	Comma-separated list of tags to assign in the configuration file. Example: `TAGS="key_1:val_1,key_2:val_2"`
`HOSTNAME`	String	Configures the hostname reported by the Agent to Datadog (overrides any hostname calculated at runtime).
`DDAGENTUSER_NAME`	String	Override the default `ddagentuser` username used during Agent installation (v6.11.0+). Learn more about the Datadog Windows Agent User.
`DDAGENTUSER_PASSWORD`	String	Override the cryptographically secure password generated for the `ddagentuser` user during Agent installation (v6.11.0+). Must be provided for installs on domain servers. Learn more about the Datadog Windows Agent User.
`APPLICATIONDATADIRECTORY`	Path	Override the directory to use for the configuration file directory tree. May only be provided on initial install; not valid for upgrades. Default: `C:\ProgramData\Datadog`. (v6.11.0+)
`PROJECTLOCATION`	Path	Override the directory to use for the binary file directory tree. May only be provided on initial install; not valid for upgrades. Default: `%ProgramFiles%\Datadog\Datadog Agent`. (v6.11.0+) If you choose to override the default directory, ensure that you specify a `Datadog` subdirectory for the Datadog files.

Notes

The /qn option runs a quiet install. To see the GUI prompts, remove it.
Some Agent versions may cause a forced reboot. To prevent this, add the parameter: REBOOT=ReallySuppress.
Some Agent components require a kernel driver to collect data. To know if a kernel driver is required for your component, see its documentation page or search for kernel driver in the associated Agent configuration files.
If a valid datadog.yaml is found, that file takes precedence over all specified command line options.

More Agent configuration options

Each of the following configuration options can be added as a property to the command line when installing the Agent on Windows.

Note: If a valid datadog.yaml is found, that file takes precedence over all specified command line options.

Variable	Type	Description
`LOGS_ENABLED`	String	Enable (`"true"`) or disable (`"false"`) the log collection feature in the configuration file. Logs are disabled by default.
`APM_ENABLED`	String	Enable (`"true"`) or disable (`"false"`) the APM Agent in the configuration file. APM is enabled by default.
`PROCESS_ENABLED`	String	Enable (`"true"`) or disable (`"false"`) the Process Agent in the configuration file. The Process Agent is disabled by default.
`HOSTNAME_FQDN_ENABLED`	String	Enable (`"true"`) or disable (`"false"`) the usage of FQDN for the Agent hostname. It is equivalent to set `hostname_fqdn` in the Agent configuration file. The usage of FQDN for the hostname is disabled by default. (v6.20.0+)
`CMD_PORT`	Number	A valid port number between 0 and 65534. The Datadog Agent exposes a command API on port 5001. If that port is already in use by another program, the default may be overridden here.
`PROXY_HOST`	String	(If using a proxy) sets your proxy host. Learn more about using a proxy with the Datadog Agent.
`PROXY_PORT`	Number	(If using a proxy) sets your proxy port. Learn more about using a proxy with the Datadog Agent.
`PROXY_USER`	String	(If using a proxy) sets your proxy user. Learn more about using a proxy with the Datadog Agent.
`PROXY_PASSWORD`	String	(If using a proxy) sets your proxy password. For the process/container Agent, this variable is required for passing in an authentication password and cannot be renamed. Learn more about using a proxy with the Datadog Agent.
`EC2_USE_WINDOWS_PREFIX_DETECTION`	Boolean	Use the EC2 instance id for Windows hosts on EC2. (v7.28.0+)
[DEPRECATED] `ADDLOCAL`	String	Enable additional Agent component. Setting to `"MainApplication,NPM"` causes the driver component for Network Performance Monitoring to be installed. (version 7.44.0 and previous)

Note: Agent 7 only supports Python 3. Before upgrading, confirm that your custom checks are compatible with Python 3. See the Python 3 Custom Check Migration guide for more information. If you’re not using custom checks or have already confirmed their compatibility, upgrade normally.

If you’re upgrading from a Datadog Agent version < 5.12.0, first upgrade to a more recent version of Agent 5 (>= 5.12.0 but < 6.0.0) using the EXE installer and then upgrade to Datadog Agent version >= 6.

Installation log files

You can find Agent installation log files at %TEMP%\MSI*.LOG.

Validation

To verify your installation, follow the instructions in the Agent Status and Information section.

Agent commands

The execution of the Agent is controlled by the Windows Service Control Manager.

The main executable name is agent.exe. The location is as follows depending on the Agent version:
- Agent versions <= 6.11: "C:\Program Files\Datadog\Datadog Agent\embedded\agent.exe"
- Agent versions >= 6.12: "C:\Program Files\Datadog\Datadog Agent\bin\agent.exe"
The configuration GUI is a browser-based configuration application (for Windows 64-bit only).
Commands can be run from the an elevated(run as Admin) command line (PowerShell or Command Prompt) using the syntax <PATH_TO_AGENT.EXE> <COMMAND>.
Command-line options are below:

Command	Description
check	Runs the specified check.
diagnose	Executes some connectivity diagnosis on your system.
flare	Collects a flare and send it to Datadog.
help	Gets help about any command.
hostname	Prints the hostname used by the Agent.
import	Imports and converts configuration files from previous versions of the Agent.
launch-gui	Starts the Datadog Agent Manager.
restart-service	Restarts the Agent within the service control manager.
run	Starts the Agent.
start	Starts the Agent. (Being deprecated, but accepted. Use `run` as an alternative.)
start-service	Starts the Agent within the service control manager.
status	Print the current status.
stopservice	Stops the Agent within the service control manager.
version	Prints the version info.

Examples:

PowerShell (powershell.exe)

& "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" status
& "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" launch-gui
& "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" flare

Command Prompt (cmd.exe)

"%ProgramFiles%\Datadog\Datadog Agent\bin\agent.exe" status
"%ProgramFiles%\Datadog\Datadog Agent\bin\agent.exe" launch-gui
"%ProgramFiles%\Datadog\Datadog Agent\bin\agent.exe" flare

Configuration

Use the Datadog Agent Manager to enable, disable, and configure checks. Restart the Agent for your changes to be applied.

The main Agent configuration file is located at: C:\ProgramData\Datadog\datadog.yaml

Configuration files for integrations are in: C:\ProgramData\Datadog\conf.d\ OR C:\Documents and Settings\All Users\Application Data\Datadog\conf.d\

Note: ProgramData is a hidden folder.

Uninstall the Agent

There are two different methods to uninstall the Agent on Windows. Both methods remove the Agent, but do not remove the C:\ProgramData\Datadog configuration folder on the host.

Add or remove programs

Press CTRL and Esc or use the Windows key to run Windows Search.
Search for add and click Add or remove programs.
Search for Datadog Agent and click Uninstall.

PowerShell

Note: Enable WinRM to use the commands below.

Use the following PowerShell command to uninstall the Agent without rebooting:

$productCode = (@(Get-ChildItem -Path "HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall" -Recurse) | Where {$_.GetValue("DisplayName") -like "Datadog Agent" }).PSChildName
start-process msiexec -Wait -ArgumentList ('/log', 'C:\uninst.log', '/q', '/x', "$productCode", 'REBOOT=ReallySuppress')

Troubleshooting

Agent status and information

To verify the Agent is running, check if the DatadogAgent service in the Services panel is listed as Started. A process called Datadog Metrics Agent (agent.exe) should also exist in the Task Manager.

To receive more information about the Agent’s state, start the Datadog Agent Manager:

Right click on the Datadog Agent system tray icon -> Configure, or
Run launch-gui command from an elevated(run as Admin) command line
- PowerShell: & "<PATH_TO_AGENT.EXE>" launch-gui
- cmd: "<PATH_TO_AGENT.EXE>" launch-gui

Then, open the status page by going to Status -> General. Get more information on running checks in Status -> Collector and Checks -> Summary.

The status command is available for PowerShell:

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

or cmd.exe:

"%ProgramFiles%\Datadog\Datadog Agent\bin\agent.exe" status

Logs location

The Agent logs are located in C:\ProgramData\Datadog\logs\agent.log.

Note: ProgramData is a hidden folder.

Send a flare

Navigate to http://127.0.0.1:5002 to display the Datadog Agent Manager.
Select flare tab.
Enter your ticket number (if you have one).
Enter the email address you use to log in to Datadog.
Press Submit.

The flare command is available for PowerShell:

& "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" flare <CASE_ID>

or cmd.exe:

"%ProgramFiles%\Datadog\Datadog Agent\bin\agent.exe" flare <CASE_ID>

Use cases

Monitoring a Windows service

On your target host, launch the Datadog Agent Manager and select the “Windows Service” integration from the list. There is an out-of-the-box example; however, this example uses DHCP.

To get the name of the service, open services.msc and locate your target service. Using DHCP as the target, you can see the service name at the top of the service properties window:

When adding your own services, be sure to follow the formatting exactly as shown. If formatting is not correct the integration fails. Note: Special characters in a service name must be escaped. For example, the name MSSQL$BILLING can be added with MSSQL\$BILLING.

Also, whenever you modify an integration, the Datadog service needs to be restarted. You can do this from services.msc or from the UI sidebar.

For Services, Datadog doesn’t track the metrics—only their availability. (For metrics, use the Process or WMI integration). To set up a Monitor, select the Integration monitor type then search for Windows Service. From Integration Status -> Pick Monitor Scope, choose the service you would like to monitor.

Monitoring system load for Windows

The Datadog Agent collects a large number of system metrics by default. The most commonly used system metrics are system.load.* but these metrics are Unix specific.

While Windows does not offer the system.load.* metrics, an equivalent option that’s available by default is system.proc.queue.length. This metric shows the number of threads observed as delayed in the processor ready queue that are waiting to be executed.

Monitoring Windows processes

You can monitor Windows processes with Live Process Monitoring. To enable this on Windows, edit the Agent main configuration file by setting the following parameter to true:

datadog.yaml: