Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Your First Host: Installing the Datadog Agent Step by Step

Install the Datadog Agent on a Linux host with the one-line script, check its status, find the host in Infrastructure List, and see your first system metrics.

The fastest way to see value from Datadog is to put the Agent on one machine and watch the host appear. This lesson walks through that first install on Linux, shows what each step does, and tells you what to check when nothing shows up. The commands are real; they run on your server, not on this site. The TryIt blocks are stand-ins that build and check the commands for you.

Before you start

You need:

  • A Datadog account and your site (see accounts, sites and API keys).
  • An API key from Organization Settings.
  • A Linux host with sudo, outbound HTTPS (port 443) to Datadog, and a supported distribution (Debian, Ubuntu, RHEL, CentOS, Amazon Linux, SUSE and others).

In the Datadog UI, Integrations > Agent shows a copy-paste command for your OS with your key already filled in. It looks like this (Agent major version 7):

Terminal
DD_API_KEY=<YOUR_API_KEY> DD_SITE="datadoghq.com" \
  bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

The script detects your package manager, adds Datadog's package repository, installs the datadog-agent package, writes /etc/datadog-agent/datadog.yaml with your key and site, and starts the service. Read a script before you run it as root: you can download it first with curl -L -o install.sh ... and open it.

Check that it runs

Terminal
sudo systemctl status datadog-agent
sudo datadog-agent status

datadog-agent status is the single most useful command you will learn. It prints the Agent version, the connection to Datadog (look for the API key check to say valid), every running check with the number of metrics it sends, DogStatsD counters, and log collection state. On Windows the equivalent is & "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" status, and there is a Datadog Agent Manager GUI.

Within a minute or two the host shows up under Infrastructure > Infrastructure List. Click it to open a host panel with CPU, memory, load, disk and network graphs. These come from the built-in system, cpu, memory, disk, network, io, load, uptime and file_handle checks, which are on by default.

Where things live on Linux

Path What it is
/etc/datadog-agent/datadog.yaml Main configuration
/etc/datadog-agent/conf.d/ One folder per integration
/var/log/datadog/agent.log Agent's own log
/opt/datadog-agent/ Program files and embedded Python

The Agent runs as the unprivileged user dd-agent. Remember this name: when you tail log files later, that user must have read permission.

Your first dashboard in two clicks

Open the host, then choose Dashboards > New Dashboard, or start from a built-in one like Host Dashboard. Add a Timeseries widget with the query avg:system.cpu.user{host:<your host>}. You will learn this query language in the metrics explorer and query language. For now, notice that the metric name is system.cpu.user and the filter is a tag, host.

Python Stand-in: install command builder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

DD_TAGS is a real environment variable the installer honors: it writes host tags into datadog.yaml so the host is tagged from minute one. Tags are separated by spaces in this variable.

When nothing shows up

Work through this list in order. Most problems are in the first three items.

  1. Wrong site. Compare site: in datadog.yaml with the domain in your browser.
  2. Wrong or missing API key. datadog-agent status shows the key check; fix the key and restart.
  3. No outbound HTTPS. Proxies and firewalls must allow the Agent to reach Datadog on 443. If you need a proxy, set proxy: in datadog.yaml (or DD_PROXY_HTTPS).
  4. Service not running. sudo systemctl status datadog-agent, then read /var/log/datadog/agent.log.
  5. Clock skew. Metrics with timestamps far from real time are rejected; keep NTP running.
  6. Hostname problems. Cloned VM images can share a hostname, so two machines appear as one host. Set hostname: explicitly.

When you need help from support or want to share state, run sudo datadog-agent flare. It collects configuration (with secrets scrubbed), logs and status into a zip and can send it to a support case.

Python Stand-in: diagnose a status report

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Uninstall and upgrade

The package manager handles both: sudo apt-get remove datadog-agent (Debian/Ubuntu) or sudo yum remove datadog-agent (RHEL family). To upgrade, re-run the install script; it upgrades in place and keeps datadog.yaml. Pin the major version deliberately: Agent 7 is the current line, and Agent 6 and earlier are retired.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command shows the Agent's connection state, running checks and log collection?

    datadog-agent status prints a full report: version, API key check, checks, DogStatsD and logs.
  2. 2. Which user does the Agent run as on Linux?

    dd-agent is unprivileged, so it needs explicit permission to read protected files such as logs.
  3. 3. The host never appears. The browser shows app.datadoghq.eu and datadog.yaml says site: datadoghq.com. What is wrong?

    Data sent to US1 does not appear in an EU1 organization.
  4. 4. What does DD_TAGS do in the install command?

    It writes space-separated tags such as env:staging into the host configuration.

Summary

  • The one-line installer adds the repository, installs the Agent and writes datadog.yaml with your API key and site.
  • datadog-agent status is the first diagnostic; datadog-agent flare packages everything for support.
  • The host appears in Infrastructure List within minutes, with CPU, memory, disk and network metrics.
  • Most "no data" problems are the wrong site, a wrong key, or blocked outbound HTTPS.

Next: The Datadog UI and the Platform Map