Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Agent and Integrations

Configuring the Datadog Agent: datadog.yaml, Tags, Proxy and Secrets

Configure the Datadog Agent with datadog.yaml: site, API key, hostname, host tags, proxy, log and APM switches, environment variables, secrets management and config validation.

The Agent's behavior is controlled by one main file, datadog.yaml, plus one folder per integration. Knowing the handful of keys that matter, and how environment variables and secrets interact with the file, saves hours of guessing. Datadog cannot run on this site, so here you edit YAML in your head and in the stand-ins, then apply it on a real host.

Where the files are

Platform Main file
Linux /etc/datadog-agent/datadog.yaml
Windows C:\ProgramData\Datadog\datadog.yaml
macOS ~/.datadog-agent/datadog.yaml
Container built from DD_* environment variables

A full annotated example, datadog.yaml.example, sits beside it and lists every option. Most settings you want are a short list.

The keys that matter

YAML
api_key: "<YOUR_API_KEY>"
site: datadoghq.com          # must match your org's site
hostname: web-prod-01        # optional; set it when cloning machines
tags:                        # host tags, applied to everything from this host
  - env:prod
  - team:payments
  - role:web

logs_enabled: true           # turn on log collection
apm_config:
  enabled: true              # trace agent (on by default)
process_config:
  process_collection:
    enabled: true            # live processes
dogstatsd_non_local_traffic: false   # true only when other hosts/containers send to us
proxy:
  https: http://proxy.internal:3128
  no_proxy:
    - 169.254.169.254        # cloud metadata endpoint
log_level: info              # trace, debug, info, warn, error, critical

Some notes on the keys:

  • site and api_key are the only required ones.
  • tags are host-level. They are added to every metric, log and trace the Agent sends. Use them for env, team, role, region. Per-service tags belong to the service itself (see unified service tagging).
  • logs_enabled is off by default; without it no logs are collected.
  • proxy matters in corporate networks. Remember no_proxy for local addresses.
  • log_level: debug is invaluable while troubleshooting but noisy; set it back afterwards.
  • min_collection_interval is not here: it is set per integration instance in conf.d.

After editing, restart the Agent (sudo systemctl restart datadog-agent) and verify with sudo datadog-agent status. Validate the YAML first: a tab or a bad indent silently breaks startup, and the error appears only in /var/log/datadog/agent.log. sudo datadog-agent configcheck prints the resolved check configurations, and sudo datadog-agent config prints the effective main configuration with secrets scrubbed.

Environment variables and precedence

Any setting can be given as an environment variable: DD_ plus the upper-case key (DD_SITE, DD_LOGS_ENABLED, DD_TAGS). When both the file and the variable exist, the environment variable wins. This is how container and Kubernetes deployments configure the Agent with no file at all. Remember that DD_TAGS takes space-separated tags, while the YAML key is a list.

Secrets management

Do not store passwords in conf.d files. The Agent supports secrets management with a helper executable: you write ENC[db_password] in a config, and the Agent calls your secret_backend_command to resolve it.

YAML
secret_backend_command: /usr/local/bin/fetch-secret.sh
secret_backend_arguments: []

Your script receives a JSON list of secret handles on standard input and prints JSON with the values. Datadog also has built-in backend types for common stores (for example AWS Secrets Manager and Kubernetes secrets) through secret_backend_type. The helper must not be world-writable, and the dd-agent user must be able to run it; the Agent refuses to start the secret call otherwise.

In Kubernetes, read the API key from a Secret rather than a plain environment variable (apiKeyExistingSecret in the Helm chart).

Validating your edits

Before restarting production hosts, check the file. Here is a stand-in validator that parses YAML and applies the rules of this lesson.

Python Stand-in: lint a datadog.yaml

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.

Python Stand-in: environment variable overrides the file

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.

Reload and rollout

Most changes need a restart. For fleets, push the file with your config management tool and restart in waves. To change a setting at runtime for debugging, sudo datadog-agent config set log_level debug works for supported keys and reverts on restart (check the version's docs for which keys). Keep datadog.yaml in version control without the key: render the key from a secret at deploy time.

Common mistakes

  1. Tabs or wrong indentation in YAML.
  2. site mismatch with the organization.
  3. Setting tags as a string instead of a list in the file.
  4. Putting integration settings in datadog.yaml instead of conf.d.
  5. Leaving log_level: debug on, which fills disks with logs.
  6. Opening DogStatsD to the network without a firewall.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A setting exists both in datadog.yaml and as a DD_ environment variable. Which wins?

    Environment variables override the file, which is how containers are configured.
  2. 2. Which setting is off by default and must be enabled to collect logs?

    Set logs_enabled: true (or DD_LOGS_ENABLED=true) to turn log collection on.
  3. 3. What does ENC[name] in a config file mean?

    The Agent calls the configured secret backend to resolve handles into values.
  4. 4. Which command prints the resolved check configurations?

    configcheck shows how check configs were loaded and resolved.

Summary

  • datadog.yaml needs api_key and site; tags, hostname, logs_enabled, proxy are the next most common keys.
  • DD_* environment variables override the file and configure containers.
  • Use secrets management instead of plain passwords; keep keys out of version control.
  • Validate YAML, restart, then confirm with datadog-agent status and configcheck.

Next: Integrations and Checks