--- title: Getting Started with the Agent description: >- Guide to installing and configuring the Datadog Agent to collect system-level metrics, events, and logs from hosts. breadcrumbs: Docs > Getting Started > Getting Started with the Agent --- # Getting Started with the Agent ## Overview{% #overview %} This guide introduces the Datadog Agent and covers: - Introduction to the Agent - Installation - Data collected by the Agent - Advanced configurations and features - Troubleshooting ## What is the Datadog Agent?{% #what-is-the-datadog-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. The Agent can run on: - Local hosts (Windows, macOS) - Containerized environments (Docker, Kubernetes) - On-premises data centers You can also install and configure the Agent using configuration management tools like Chef, Puppet, or Ansible. The Agent can collect 75-100 system-level metrics every 15-20 seconds. With additional configuration, it can send live data, logs, and traces from running processes to Datadog. The Datadog Agent is open source, and its source code is available on GitHub at [DataDog/datadog-agent](https://github.com/DataDog/datadog-agent). ### The Agent configuration file{% #the-agent-configuration-file %} The Agent's main configuration file is `datadog.yaml`. The required parameters are: - Your [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys), which is used to associate the Agent's data with your organization. - Your [Datadog site](https://docs.datadoghq.com/getting_started/site/) (). See the [sample `config_template.yaml` file](https://github.com/DataDog/datadog-agent/blob/master/pkg/config/config_template.yaml) for all available configuration options. You can adjust the Agent configuration files to take advantage of other Datadog features. ## Installation{% #installation %} ### Prerequisites{% #prerequisites %} 1. Create a [Datadog account](https://www.datadoghq.com). 1. Have your [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) on hand. ### Setup{% #setup %} Use [Fleet Automation](https://docs.datadoghq.com/agent/fleet_automation/), the Datadog in-app workflow, to install, upgrade, configure, and troubleshoot the Datadog Agent on a single host or at scale. See the [Agent documentation](https://docs.datadoghq.com/agent/?tab=Host-based) for additional Agent configuration for your specific platform. ## Data collected by the Agent{% #data-collected-by-the-agent %} To give you full visibility into your infrastructure, the Datadog Agent reports metrics about its own health and configuration, as well as metrics gathered from your hosts and services through its default checks. ### Agent metrics{% #agent-metrics %} The Agent reports the following metrics to Datadog about itself. These metrics provide information about which hosts or containers have running Agents, when each Agent started, and the Python version the Agent is using. | Metric | Description | | ------------------------------ | ----------------------------------------------------------------------------- | | `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+). | | `datadog.agent.python.version` | The metric is tagged with the `python_version`. | See the [Agent Metrics](https://docs.datadoghq.com/integrations/agent_metrics/) integration for a full list of Agent metrics. ### Checks{% #checks %} Depending on your platform, the Agent has several core checks enabled by default that collect metrics. | Check | Metrics | Platforms | | ----------- | ------------------------------------------------------------------------- | ------------------ | | CPU | [System](https://docs.datadoghq.com/integrations/system/#metrics) | All | | Disk | [Disk](https://docs.datadoghq.com/integrations/disk/#metrics) | All | | IO | [System](https://docs.datadoghq.com/integrations/system/#metrics) | All | | Memory | [System](https://docs.datadoghq.com/integrations/system/#metrics) | All | | Network | [Network](https://docs.datadoghq.com/integrations/network/#metrics) | All | | NTP | [NTP](https://docs.datadoghq.com/integrations/ntp/#metrics) | All | | Uptime | [System](https://docs.datadoghq.com/integrations/system/#metrics) | All | | File Handle | [System](https://docs.datadoghq.com/integrations/system/#metrics) | All except Mac | | Load | [System](https://docs.datadoghq.com/integrations/system/#metrics) | All except Windows | | Docker | [Docker](https://docs.datadoghq.com/agent/docker/data_collected/#metrics) | Docker | | Winproc | [System](https://docs.datadoghq.com/integrations/system/#metrics) | Windows | To collect metrics from other technologies, see the [Integrations](https://docs.datadoghq.com/getting_started/integrations/) page. ### Service checks{% #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 Datadog to visualize the Agent status through monitors and dashboards at a glance. See [Service Check Overview](https://docs.datadoghq.com/extend/service_checks/#visualize-your-service-check-in-datadog) to learn more. ## Advanced configurations and features{% #advanced-configurations-and-features %} {% collapsible-section #id-for-anchoring %} #### Differences between Agent for hosts and containers There are key differences between installing Agents on a host and in a containerized environment: - **Configuration differences**: - **Host**: The Agent is configured using a YAML file. - **Container**: Configuration options are passed using [environment variables](https://docs.datadoghq.com/agent/guide/environment-variables/#overview), for example: ```sh `DD_API_KEY` # Datadog API key `DD_SITE` # Datadog site ``` - **Integrations detection**: - **Host**: [Integrations](https://docs.datadoghq.com/getting_started/integrations/) are identified through the Agent configuration file. - **Container**: Integrations are automatically identified using Datadog's Autodiscovery feature. See [Basic Agent Autodiscovery](https://docs.datadoghq.com/getting_started/containers/autodiscovery/?tab=adannotationsv2agent736) to learn more. Additionally, see the [Docker Agent](https://docs.datadoghq.com/agent/docker/?tab=standard) or [Kubernetes](https://docs.datadoghq.com/agent/kubernetes/installation?tab=operator) for a walkthrough on running the Agent in a containerized environment. {% /collapsible-section %} {% collapsible-section #id-for-anchoring %} #### Setting tags through the Agent configuration file 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](https://docs.datadoghq.com/getting_started/tagging/) to learn more about tagging your data. 1. Locate your Agent's [main configuration file](https://docs.datadoghq.com/agent/configuration/agent-configuration-files/#agent-main-configuration-file). For Ubuntu, the file location is `/etc/datadog-agent/datadog.yaml`. 1. 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. ```yaml ## @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 # - : ``` 1. Uncomment the tags parameter and the provided example `team:infra` tag. You can also add your own custom tag, for example `test:agent_walkthrough`. ```yaml ## @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 ``` 1. Restart the Agent by running the Agent's [restart command](https://docs.datadoghq.com/agent/configuration/agent-commands/#restart-the-agent). The Ubuntu restart command: ```shell sudo service datadog-agent restart ``` 1. After a few minutes, go to the [Metrics Summary page](https://app.datadoghq.com/metric/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 any personal tags you added. You can also filter metrics by the `Tag` field at the top of the page. 1. Go to the [Events Explorer page](https://app.datadoghq.com/event/explorer) and find the custom tags displayed with the latest Agent Event. {% /collapsible-section %} {% collapsible-section #id-for-anchoring %} #### Finding metrics in the Datadog UI You can confirm the Agent is running correctly by checking its default metrics in the Datadog UI. Go to the [Metrics Summary page](https://app.datadoghq.com/metric/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 Datadog. Click on either of the metrics and a Metric panel opens. This panel shows additional metadata about where these metrics are collected and any associated tags. If no tags are configured on a host, you should see only the default tags that Datadog assigns to the metrics including `version` and `host`. See the section above on setting tags through the Agent configuration files to learn more about how to add tags. Explore other default metrics such as `ntp.offset` or `system.cpu.idle`. {% /collapsible-section %} {% collapsible-section #id-for-anchoring %} #### Agent overhead The amount of space and resources the Agent takes up depends on the configuration and what data the Agent is sending. At the onset, you can expect around 0.08% CPU used on average with a disk space of roughly 880MB to 1.3GB. See [Agent Overhead](https://docs.datadoghq.com/agent/basic_agent_usage/?tab=agentv6v7#agent-overhead) to learn more about these benchmarks. {% /collapsible-section %} {% collapsible-section #id-for-anchoring %} #### Additional configuration options The collection of [logs](https://docs.datadoghq.com/logs/), [traces](https://docs.datadoghq.com/tracing/), and [processes](https://docs.datadoghq.com/infrastructure/process/?tab=linuxwindows#introduction) data can be enabled through the Agent configuration file. These features are not enabled by default. For example, in the configuration file, the `logs_enabled` parameter is set to false. ```yaml ################################## ## 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: - Enabling [OTLP Trace Ingestion](https://docs.datadoghq.com/opentelemetry/otlp_ingest_in_the_agent/?tab=host) - [Customizing log collection](https://docs.datadoghq.com/agent/logs/advanced_log_collection/) to filter or scrub sensitive data - Configuring custom data through [DogStatsD](https://docs.datadoghq.com/extend/dogstatsd/?tab=hostagent) 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. {% /collapsible-section %} ## Commands{% #commands %} See [Agent Commands](https://docs.datadoghq.com/agent/configuration/agent-commands/) to [Start](https://docs.datadoghq.com/agent/configuration/agent-commands/#start-the-agent), [Stop](https://docs.datadoghq.com/agent/configuration/agent-commands/#stop-the-agent) or [Restart](https://docs.datadoghq.com/agent/configuration/agent-commands/#restart-the-agent) your Agent. ## Troubleshooting{% #troubleshooting %} For help troubleshooting the Agent: - See [Agent Troubleshooting](https://docs.datadoghq.com/agent/troubleshooting/) - View the [Agent Log Files](https://docs.datadoghq.com/agent/configuration/agent-log-files/) - Contact [Datadog support](https://docs.datadoghq.com/help/) ## Further Reading{% #further-reading %} - [The Datadog Agent](https://docs.datadoghq.com/agent/) - [Join an interactive session to power up your Infrastructure monitoring](https://dtdg.co/fe) - [Why should I install the Datadog Agent on my cloud instances?](https://docs.datadoghq.com/agent/faq/why-should-i-install-the-agent-on-my-cloud-instances/) - [Monitor AWS Lambda Managed Instances with Datadog](https://www.datadoghq.com/blog/lambda-managed-instances) ## Next steps{% #next-steps %} - [Learn about Integrations](https://docs.datadoghq.com/getting_started/integrations) - [Learn about the Datadog UI](https://docs.datadoghq.com/getting_started/application) - [Learn how to collect Logs through the Agent](https://docs.datadoghq.com/getting_started/logs) - [Learn how to collect Traces through the Agent](https://docs.datadoghq.com/getting_started/tracing)