Study guide
Config File Troubleshooting
Datadog Fundamentals Study Guide Exam
Track your progress as you read
Finished sections get a check mark.
1 Computer Fundamentals
Datadog Cert Format and Study Map Shell, OS, and Processes Networking Basics for Observability Hardware, Metadata, and Config Files Linux/Windows Troubleshooting Basics
2 Infrastructure Development
2.1 Agent Install and Architecture 2.2 API Keys and Application Keys 2.3 Running the Agent and Status 2.4 Hostnames and Environments
3 Networking and Agent Configuration
Datadog Ports and Endpoints Datadog IPs and Connectivity Autodiscovery Patterns
4 Data Collection
DogStatsD and Custom Metrics Integrations and Crawlers API Endpoints for Data Tagging Best Practices Metrics, Timeseries, and Types
5 Troubleshooting Datadog
Agent Commands and Flare Agent Logs and Debug Config File Troubleshooting
6 Data Visualization and Utilization
6.1 Host Map and Infrastructure List 6.2 Dashboards and Widgets 6.3 Monitors, Alerts, and Notifications 6.4 Investigation Workflows and Exam Tips
Config File Troubleshooting
Key Takeaways Explain This Topic AI
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.
Last updated: July 2026
Quick Answer: Global Agent settings live in datadog.yaml ; integrations use conf.d/<name>.d/conf.yaml . After edits, restart the Agent and run configcheck . Suspect wrong site , 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.yaml and /opt/datadog-agent/conf.d/main.conf are 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-agent fails immediately.
journalctl -u datadog-agent.service shows a parse error with a line number .
status cannot 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 from conf.yaml.example ).
Provide instance connection details (host, port, credentials, SSL).
Restart the Agent.
Confirm with configcheck that the integration appears with resolved values.
Run datadog-agent check <integration> if status still 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 nginx and read /var/log/datadog/agent.log .
If still stuck after logs: consider flare for 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 .