Basic Agent Usage for Windows

Setup

If you haven’t installed the Datadog Agent yet, see below or the in-app installation instructions. See the Agent documentation for supported OS versions.

For installation and configuration to the Datadog EU site, use the SITE= parameter. See the configuration variables table below.

Installation

Starting with Agent v6.11.0, the core and APM/trace components of the Windows Agent run under the ddagentuser account created at install time instead of the LOCAL_SYSTEM account. The Live Processes component, if enabled, runs under the LOCAL_SYSTEM account. Learn more about the Datadog Windows Agent User.

If installing the Datadog Agent on a domain environment, see the installation requirements for the Agent.

Note: There are special considerations for domain controllers.

  1. Download the Datadog Agent installer to install the latest version of the Agent.

    If you need to install a specific version of the Agent, see the installer list.
  2. Run the installer (as Administrator) by opening datadog-agent-7-latest.amd64.msi.

  3. Follow the prompts, accept the license agreement, and enter your Datadog API key.

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

To install the Agent with the command line:

  1. Download the Datadog Agent installer.
  2. Run one of the following commands inside the directory where you downloaded the installer.

Command prompt

start /wait msiexec /qn /i datadog-agent-7-latest.amd64.msi APIKEY="<YOUR_DATADOG_API_KEY>"

PowerShell

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

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.

Configuration

Each configuration item is added as a property to the command line. The following configuration command line options are available when installing the Agent on Windows:

VariableTypeDescription
APIKEYStringAdds the Datadog API KEY to the configuration file.
SITEStringSet the Datadog intake site, for example: SITE=
TAGSStringComma-separated list of tags to assign in the configuration file. Example: TAGS="key_1:val_1,key_2:val_2"
HOSTNAMEStringConfigures the hostname reported by the Agent to Datadog (overrides any hostname calculated at runtime).
LOGS_ENABLEDStringEnable ("true") or disable ("false") the log collection feature in the configuration file. Logs are disabled by default.
APM_ENABLEDStringEnable ("true") or disable ("false") the APM Agent in the configuration file. APM is enabled by default.
PROCESS_ENABLEDStringEnable ("true") or disable ("false") the Process Agent in the configuration file. The Process Agent is disabled by default.
HOSTNAME_FQDN_ENABLEDStringEnable ("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_PORTNumberA 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_HOSTStringIf using a proxy, sets your proxy host. Learn more about using a proxy with the Datadog Agent.
PROXY_PORTNumberIf using a proxy, sets your proxy port. Learn more about using a proxy with the Datadog Agent.
PROXY_USERStringIf using a proxy, sets your proxy user. Learn more about using a proxy with the Datadog Agent.
PROXY_PASSWORDStringIf 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.
DDAGENTUSER_NAMEStringOverride the default ddagentuser username used during Agent installation (v6.11.0+). Learn more about the Datadog Windows Agent User.
DDAGENTUSER_PASSWORDStringOverride 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.
APPLICATIONDATADIRECTORYPathOverride 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+)
PROJECTLOCATIONPathOverride 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+)
[DEPRECATED] ADDLOCALStringEnable additional agent component. Setting to "MainApplication,NPM" causes the driver component for Network Performance Monitoring to be installed. (version 7.44.0 and previous)
EC2_USE_WINDOWS_PREFIX_DETECTIONBooleanUse the EC2 instance id for Windows hosts on EC2. (v7.28.0+)

Note: If a valid datadog.yaml is found and has an API key configured, that file takes precedence over all specified command line options.

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 using the GUI or Command line instructions.

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:
CommandDescription
checkRuns the specified check.
diagnoseExecutes some connectivity diagnosis on your system.
flareCollects a flare and send it to Datadog.
helpGets help about any command.
hostnamePrints the hostname used by the Agent.
importImports and converts configuration files from previous versions of the Agent.
launch-guiStarts the Datadog Agent Manager.
restart-serviceRestarts the Agent within the service control manager.
runStarts the Agent.
startStarts the Agent. (Being deprecated, but accepted. Use run as an alternative.)
start-serviceStarts the Agent within the service control manager.
statusPrint the current status.
stopserviceStops the Agent within the service control manager.
versionPrints 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
      

Use the Datadog Agent Manager (available from the start menu).

windows Start Menu

Use the start, stop, and restart commands in the Datadog Agent Manager:

Manager snapshot

You can also use Windows PowerShell, where available: [start|stop|restart]-service datadogagent

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

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

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.

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

To verify the Agent is running, check if the service status in the Services panel is listed as “Started”. A process called ddagent.exe should also exist in the Task Manager.

Information about the Agent’s state for Agent v5.2+ is available in the Datadog Agent Manager -> Settings -> Agent Status:

Windows Status

For the status of Agent v3.9.1 to v5.1, navigate to http://localhost:17125/status.

The info command is available for PowerShell:

& "$env:ProgramFiles\Datadog\Datadog Agent\embedded<PYTHON_MAJOR_VERSION>\python.exe" "$env:ProgramFiles\Datadog\Datadog Agent\agent\agent.py" info

or cmd.exe:

"%ProgramFiles%\Datadog\Datadog Agent\embedded<PYTHON_MAJOR_VERSION>\python.exe" "%ProgramFiles%\Datadog\Datadog Agent\agent\agent.py" info

Note: For Agent versions <= 6.11 the path should be %ProgramFiles%\Datadog\Datadog Agent\embedded\python.exe instead.

Logs location

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

Note: ProgramData is a hidden folder.

Need help? Contact Datadog support.

For Windows Server 2008, Vista, and newer systems, the Agent logs are located in C:\ProgramData\Datadog\logs.

Note: ProgramData is a hidden folder.

Need help? Contact Datadog support.

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>
Windows flare with Agent 6

To send Datadog support a copy of your Windows logs and configurations, do the following:

  • Open the Datadog Agent Manager.

  • Select Actions.

  • Select Flare.

  • Enter your ticket number (if you don’t have one, leave the value as zero).

  • Enter the email address you use to log in to Datadog.

Windows Flare

The flare command is available for PowerShell:

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

or cmd.exe:

"%ProgramFiles%\Datadog\Datadog Agent\embedded\python.exe" "%ProgramFiles%\Datadog\Datadog Agent\agent\agent.py" flare <CASE_ID>

Flare fails to upload

The output of the flare command tells you where the compressed flare archive is saved. In case the file fails to upload to Datadog, you can retrieve it from this directory and manually add as an attachment to an email. Common locations flare files are stored:

  • Linux: \tmp\
  • MacOS: $TMPDIR
  • Windows: C:\Users\<DDAGENTUSER>\AppData\Local\Temp\

For older Agent versions on Windows, you can find the location of this file by running the following from the Agent’s Python command prompt:

Step 1:

  • Agent v5.12+: "%ProgramFiles%\Datadog\Datadog Agent\dist\shell.exe" since

  • Older Agent versions: "%ProgramFiles%\Datadog\Datadog Agent\files\shell.exe"

Step 2:

import tempfile
print tempfile.gettempdir()

Example:

Flare Fail

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:

DHCP

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.

Windows DHCP Service

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:

process_config:
  enabled: "true"

After configuration is complete, restart the Agent.

Further reading