Config File Troubleshooting
Key Takeaways
- Linux main config is `/etc/datadog-agent/datadog.yaml`; per-integration files live in `/etc/datadog-agent/conf.d/<integration>.d/conf.yaml`.
- Invalid YAML syntax commonly prevents the Agent from starting — check journalctl or agent.log for parse errors with line numbers.
- After most `datadog.yaml` or `conf.d` edits, restart the Agent before expecting new metrics or log pipelines.
- A wrong `site` / `DD_SITE` value can make a locally healthy Agent send data to the wrong Datadog region.
- Use `configcheck` to confirm the running Agent loaded the file you edited — disk presence alone is not enough.
Quick Answer: Global Agent settings live in
datadog.yaml; integrations useconf.d/<name>.d/conf.yaml. After edits, restart the Agent and runconfigcheck. Suspect wrongsite, bad YAML, or missing restart when data never appears despite a "healthy" local status.
Configuration-file troubleshooting is the bridge between Infrastructure Development (installing the Agent) and Data Collection (metrics, logs, tags). The Fundamentals exam asks you to reason about file locations, which settings belong where, and the operational steps that make config changes take effect.
Configuration File Layout
| File / directory | Purpose |
|---|---|
datadog.yaml | Global settings: api_key, site, hostname, proxy, log_level, tags, forwarder options |
conf.d/ | Per-integration and per-feature YAML snippets |
conf.d/<integration>.d/conf.yaml | Active integration config the Agent loads |
conf.d/<integration>.d/conf.yaml.example | Sample/reference — not loaded unless copied to conf.yaml |
Platform paths (Linux focus)
- Main config:
/etc/datadog-agent/datadog.yaml - Integrations:
/etc/datadog-agent/conf.d/
Windows uses C:\ProgramData\Datadog\ with the same logical split between datadog.yaml and conf.d\. macOS paths differ slightly by version, but the yaml + conf.d model is identical — a frequent compare-and-contrast pattern on the exam.
Common Trap:
/var/log/datadog-agent/datadog.yamland/opt/datadog-agent/conf.d/main.confare distractors. The active Linux main config is under/etc/datadog-agent/, not the log directory or legacy Agent 5 paths.
Permissions: Why sudo Appears in Scenarios
/etc/datadog-agent/datadog.yaml is owned by root on typical Linux installs. Standard users cannot save edits, which is why exam items mention sudo when modifying Agent settings. Integration files under conf.d/ follow the same pattern. Use configuration management (Ansible, Chef, etc.) in production, but know the permission reason for the test.
YAML Syntax and Startup Failures
The Agent refuses to start when YAML is invalid. Symptoms:
systemctl start datadog-agentfails immediately.journalctl -u datadog-agent.serviceshows a parse error with a line number.statuscannot run because the process never launched.
Fix the indentation, tab characters (YAML prefers spaces), or malformed key at the cited line, then restart. This is more common on integration files than on the main datadog.yaml, especially when copying from conf.yaml.example without removing comment-only lines incorrectly.
Restart: The Most Missed Step
Many troubleshooting scenarios describe an admin who "edited conf.yaml but metrics never changed." The Agent reads most file-based settings at startup. The documented fix is:
sudo systemctl restart datadog-agent # Linux systemd
# or: sudo datadog-agent restart-service # Windows
Then verify with datadog-agent configcheck and datadog-agent status. Editing alone is never sufficient on the exam when the question asks what was "often missed."
High-Impact datadog.yaml Settings
| Setting | Misconfiguration symptom |
|---|---|
api_key | No data reaches the org; authentication errors in logs |
site / DD_SITE | Agent looks healthy locally but data lands in the wrong region (US vs EU vs other sites) |
hostname / hostname_fqdn | Duplicate hosts or drifting identity in Host Map |
proxy | Forwarder retries when direct egress is blocked but proxy was not configured |
tags | Missing expected host tags on all metrics from the machine |
Site mismatch scenario
An EU organization installs the Agent with default US site settings. Checks run, status looks fine, but the team sees no fresh data in their EU org. The strong suspect is site still pointing at the wrong Datadog site, not "too many dashboard widgets."
Integration Config Under conf.d/
To enable an Agent-based integration:
- Create or edit
conf.d/<integration>.d/conf.yaml(often by copying fromconf.yaml.example). - Provide instance connection details (host, port, credentials, SSL).
- Restart the Agent.
- Confirm with
configcheckthat the integration appears with resolved values. - Run
datadog-agent check <integration>ifstatusstill shows warnings.
If configcheck does not list your integration, the Agent never loaded the file — wrong directory name, typo in folder structure (postgres.d vs postgresql.d), or YAML error.
Log Pipeline Config Pitfalls
Log collection uses YAML under conf.d/ as well (for example conf.d/<source>.d/conf.yaml defining logs: entries). Two Fundamentals-tested edge cases:
| Issue | Agent behavior |
|---|---|
| Duplicate log source in multiple YAML files | Agent keeps the first file alphabetically and ignores the others to prevent duplicate shipping |
| Log lines without newline terminators | Tailer may wait indefinitely for a complete line before forwarding |
These are config-file problems even though the symptom appears in the Logs product.
configcheck vs Editing Disk
Candidates often assume "the file exists, so the Agent must use it." configcheck proves otherwise — it shows the merged, resolved configuration active in memory, including Autodiscovery templates. Always trust configcheck over assumptions about which file should win.
Worked Scenario: Edited Integration, No Metrics
After editing conf.d/nginx.d/conf.yaml, nginx metrics are still absent. The Agent service is running. What should you do first?
datadog-agent configcheck— is nginx listed?- If missing: fix path/YAML, then restart.
- If listed with errors:
datadog-agent check nginxand read/var/log/datadog/agent.log. - If still stuck after logs: consider
flarefor Support.
Creating a second API key or reinstalling the OS are classic distractors.
Config Troubleshooting Checklist
Confirm the active conf.yaml (not only .example), validate YAML syntax, restart the Agent, run configcheck, then status / check <name>. Verify api_key and site match the target org before escalating with flare.
On Linux, where are the main Agent config and per-integration configs typically stored?
You edited an integration conf.yaml, but the expected new metrics never appeared. What common step is often missed?
An EU-based organization's host Agent shows healthy local checks, but no fresh data reaches the Datadog site after install. Which misconfiguration is a strong suspect?
Two YAML log collection files point to the same log source. How does the Agent handle that situation?