Getting Started with the Agent
This guide provides an introduction to the Agent and how you can use it to send system level metrics to the Datadog platform. It walks through an example Agent installation on Ubuntu. It covers:
- Agent installation
- Verifying that the Agent is running
- Configuring Agent features
- Troubleshooting resources
Overview
About the Agent
The Datadog Agent is software that runs on your hosts. It collects events and metrics from hosts and sends them to Datadog, where you can analyze your monitoring and performance data. It can run on your local hosts (Windows, MacOS), containerized environments (Docker, Kubernetes), and in on-premises data centers. You can install and configure it using configuration management tools (Chef, Puppet, Ansible).
The Agent is able to collect 75 to 100 system level metrics every 15 to 20 seconds. With additional configuration, the Agent can send live data, logs, and traces from running processes to the Datadog Platform. The Datadog Agent is open source and its source code is available on GitHub at DataDog/datadog-agent.
Agent overhead
The amount of space and resources the Agent takes up depends on the configuration and what data the Agent is configured to send. At the onset, you can expect around 0.08% CPU used on average with a disk space of roughly 830MB to 880MB.
See Agent Overhead to learn more about these benchmarks.
Data collected
Agent metrics
The following Agent metrics are information the Agent sends to Datadog about itself, so that you can determine things like what hosts or containers have running Agents, when an Agent starts, and what version of Python it’s running.
| Metric | Description |
|---|
datadog.agent.python.version | Shows a value of 1 if the Agent is reporting to Datadog. The metric is tagged with the python_version. |
datadog.agent.running | Shows a value of 1 if the Agent is reporting to Datadog. |
datadog.agent.started | A count sent with a value of 1 when the Agent starts (available in v6.12+). |
See the Agent Metrics integration for a full list of Agent metrics.
Checks
Depending on your platform, the Agent has several core checks enabled by default that collect metrics.
To collect metrics from other technologies, see the Integrations page.
Differences between Agents for hosts and containers
This guide walks you through installing and configuring an Agent on a host. If you plan to eventually install Agents in a containerized environment, there are a few differences you should know about.
On a host, the Agent is configured using a YAML file (as you will see later in this guide), whereas Agent configuration options for a container’s Agent are passed in with environment variables, for example:
DD_API_KEY for the Datadog API keyDD_SITE for the Datadog site
Similarly, while on a host, integrations are identified through the Agent configuration file, in a container environment, integrations are automatically identified through Datadog’s Autodiscovery feature. See Basic Agent Autodiscovery to learn more.
See the Docker Agent or Kubernetes for a walkthrough on running the Agent in a containerized environment.
Why should I install the Agent?
The Agent needs to be installed to send data from any one of the many Agent based Integrations. The Agent is not necessarily required to forward data to the Datadog Platform, for example, you can send Logs and Metrics through the Datadog API. However, the Agent is the recommended method to forward your data to the Datadog Platform.
The Agent collects host data every 15 seconds to provide an accurate understanding of what is happening across your environments. As previously mentioned in the Checks section, the Agent has several checks enabled which collect over 50 default metrics to provide greater insight on system level data.
Setup
Prerequisites
Create a Datadog account.
Have your Datadog API key on hand.
Have the Datadog UI open.
Note: This walkthrough uses the Ubuntu operating system. See the Basic Agent Usage page for a full list of supported platforms.
Installation
In the Datadog UI, go to the Agent Installation page for Ubuntu by navigating to Integrations > Agent and selecting Ubuntu. To install the Datadog Agent on a host, use the one-line install command from that page (example shown below), updated with your Datadog API key.
Example Ubuntu one-line install command:
DD_API_KEY=<DATADOG_API_KEY> DD_SITE="" bash -c "$(curl -L https://s3.amazonaws.com/dd-agent/scripts/install_script_agent7.sh)"
Go to the in-app Agent Installation page for your operating system for the most up-to-date installation instructions.
Validation
Terminal command
Run the Agent’s status command to verify installation.
sudo datadog-agent status
A successful installation returns an Agent Status report that begins with Agent information like this:
===============
Agent (v7.36.1)
===============
Status date: 2022-06-15 15:54:48.364 EDT / 2022-06-15 19:54:48.364 UTC (1655322888364)
Agent start: 2022-06-15 15:54:29.85 EDT / 2022-06-15 19:54:29.85 UTC (1655322869850)
Pid: 9801
Go Version: go1.17.6
Python Version: 3.8.11
Build arch: amd64
Agent flavor: agent
Check Runners: 6
Log Level: info
Events
In the Datadog UI, go to the Events Explorer Page Events > Explorer. The Agent sends events to Datadog when an Agent is started or restarted. The following message displays if your Agent successfully installs:
Datadog agent (v. 7.XX.X) started on <Hostname>
Service checks
The Agent is set up to provide the following service checks:
datadog.agent.up:
Returns OK if the Agent connects to Datadog.
datadog.agent.check_status:
Returns CRITICAL if an Agent check is unable to send metrics to Datadog, otherwise returns OK.
These checks can be used in the Datadog Platform to visualize the Agent status through monitors and dashboards at a quick glance. See Service Check Overview to learn more.
Metrics
In the Datadog UI, go to the Metrics Summary page Metrics > Summary and search for the metric datadog.agent.started or the metric datadog.agent.running. If these metrics are not visible right away, it may take a few minutes for the Agent to send the data to the Datadog Platform.
Click on either of the metrics and a Metric panel opens up. This panel shows additional metadata about where these metrics are collected from and any associated tags. Because so far in this walkthrough no tags are configured on this host, you should see only the default tags that Datadog assigns to the metrics including version and host. See the following section on Agent Configuration Files to learn more about how to add tags.
Explore other default metrics such as ntp.offset or system.cpu.idle.
Agent configuration files
The Agent’s main configuration file is datadog.yaml. The required parameters are:
- your Datadog API key, which is used to associate your Agent’s data with your organization, and
- the Datadog site (
See the sample config_template.yaml file for all available configuration options.
You can adjust the Agent configuration files to take advantage of other Datadog features including tags.
Tags add an additional layer of metadata to your metrics and events. They allow you to scope and compare your data in Datadog visualizations. When data is sent to Datadog from multiple hosts, tagging this information allows you to scope down to the data you are most interested in visualizing.
For example, let’s say you have data that is collected from different teams and you are only interested in seeing the metrics from team alpha, tagging those specific hosts with either the team:alpha or team:bravo tag gives you the ability to filter down to the metrics that are tagged with team:alpha. See Getting Started with Tags to learn more about tagging your data.
Locate your Agent’s main configuration file. For Ubuntu, the file locations is /etc/datadog-agent/datadog.yaml.
In the datadog.yaml file, locate the tags parameter. Host level tags can be set in the datadog.yaml configuration to apply tags on all metrics, traces and logs forwarded from this host.
## @param tags - list of key:value elements - optional
## @env DD_TAGS - space separated list of strings - optional
## List of host tags. Attached in-app to every metric, event, log, trace, and service check emitted by this Agent.
##
## This configuration value merges with `DD_EXTRA_TAGS`, allowing some
## tags to be set in a configuration file (`tags`), and additional tags to be added
## with an environment variable (`DD_EXTRA_TAGS`).
##
## Learn more about tagging: https://docs.datadoghq.com/tagging/
#
# tags:
# - team:infra
# - <TAG_KEY>:<TAG_VALUE>
Uncomment the tags parameter and the provided example team:infra tag. You can also add your own custom tag, for example test:agent_walkthrough.
## @param tags - list of key:value elements - optional
## @env DD_TAGS - space separated list of strings - optional
## List of host tags. Attached in-app to every metric, event, log, trace, and service check emitted by this Agent.
##
## This configuration value merges with `DD_EXTRA_TAGS`, allowing some
## tags to be set in a configuration file (`tags`), and additional tags to be added
## with an environment variable (`DD_EXTRA_TAGS`).
##
## Learn more about tagging: https://docs.datadoghq.com/tagging/
#
tags:
- team:infra
- test:agent_walkthrough
Restart the Agent by running the Agent’s restart command. The Ubuntu restart command:
sudo service datadog-agent restart
After a few minutes, go to Metrics > Summary again, and click on the metric datadog.agent.started. In addition to the default host and version tags, you can also see the team tag and whatever personal tags you added. You can also filter metrics by the Tag field at the top of the page.
Go to Events > Explorer and find the custom tags displayed with the latest Agent Event.
Other configuration options
The collection of logs, traces, and processes data can be enabled through the Agent configuration file. These are not features that are enabled by default. For example, in the configuration file, notice that for the logs_enabled parameter, it is set to false.
##################################
## Log collection Configuration ##
##################################
## @param logs_enabled - boolean - optional - default: false
## @env DD_LOGS_ENABLED - boolean - optional - default: false
## Enable Datadog Agent log collection by setting logs_enabled to true.
#
# logs_enabled: false
Other Datadog features that can be configured through the Agent configuration file include:
Throughout your setup, when the documentation refers to the datadog.yaml file or the Agent configuration file, this is the file you need to configure.
Commands
See Agent Commands to Start, Stop or Restart your Agent.
Troubleshooting
For help troubleshooting the Agent:
Further Reading
Additional helpful documentation, links, and articles:
Next steps
After the Agent is installed:
