Linux/Windows Troubleshooting Basics
Key Takeaways
- When telemetry stops, verify service state first, then configuration, then network—skipping the OS layer wastes time in the UI.
- Agent logs on Linux commonly live under /var/log/datadog/; Windows uses ProgramData paths—know logs exist before memorizing every subdirectory.
- Permission errors on config files or check scripts prevent integrations from running even when the core Agent process is healthy.
- systemctl status / journalctl on Linux and Event Viewer / Get-Service on Windows are the first tools for service-level diagnosis.
- Chapter 5 covers Datadog-specific agent commands; this section covers the OS habits those commands assume.
Troubleshooting Starts at the Operating System
Datadog publishes rich Agent commands (status, flare, configcheck)—Chapter 5 covers them in detail. Fundamentals exam questions still expect you to know what to check before you invoke Datadog binaries. Think of troubleshooting as layers:
- Is the Agent service running?
- Did the latest config change parse correctly?
- Can the host reach Datadog endpoints?
- Are integrations authorized to read their targets?
This section focuses on layers 1, 2, and 4 from a Linux vs Windows perspective.
Linux Troubleshooting Basics
Service state
sudo systemctl status datadog-agent
sudo systemctl restart datadog-agent
sudo systemctl enable datadog-agent
status shows active (running) or failure reasons such as exit-code and failed to load config. If the service is inactive (dead) after reboot, check whether it was enabled for boot (systemctl is-enabled datadog-agent).
Logs
Agent logs on Linux typically reside under /var/log/datadog/ (exact subpaths vary by component—agent.log, agent.log rotated, or trace-agent.log). Use:
sudo tail -n 100 /var/log/datadog/agent.log
sudo journalctl -u datadog-agent -n 50
journalctl captures systemd stdout/stderr when file logging is sparse. Exam stems mentioning "check the log for YAML parse errors" point here—not the Datadog web UI.
Permissions and ownership
The Agent runs as a dedicated user (dd-agent on many packages). Integration checks that read nginx status pages, Docker sockets, or database credentials fail if permissions are too strict. Symptom: Agent running, specific check ERROR in status. Fix: adjust file or group permissions minimally—avoid running the entire Agent as root unless documentation requires it.
Common Linux failure patterns
| Symptom | Likely OS-level cause |
|---|---|
| Agent won't start after edit | YAML syntax, tabs, invalid key |
| No metrics after reboot | Service not enabled; dependency start order |
| Integration check only fails | Local permission or missing binary in PATH |
| Disk full warnings | Logs or spool directories consumed capacity |
Windows Troubleshooting Basics
Service state
Open Services (services.msc) and locate Datadog Agent, or use PowerShell:
Get-Service DatadogAgent
Restart-Service DatadogAgent
Status Stopped with Start Pending stuck indicates configuration or permission problems on boot.
Logs and Event Viewer
Windows Agent logs live under C:\ProgramData\Datadog\ (versioned subfolders for logs and config). Event Viewer → Windows Logs → Application may also contain service start failures. When an exam mentions ProgramData on Windows, it signals the canonical Datadog install root—not C:\Program Files\ alone.
Permissions
Windows integrations may need the Agent service account to reach WMI, performance counters, or IIS logs. A check that works under your admin interactive session but fails as a service indicates privilege context issues—classic Fundamentals reasoning.
Path and config editors
Notepad++ vs Notepad is irrelevant; what matters is encoding (UTF-8 without wrong BOM) and line endings when copying YAML from web pages. Strange invisible characters cause parse errors just like tabs.
Cross-Platform Config Validation Habits
Before restarting production Agents:
- Copy the original config for rollback
- Edit the smallest change possible—one integration at a time
- Validate syntax with Datadog's
agent configcheckwhen available - Restart and immediately check service status + log tail
If metrics flatline after a valid change, wait one collection interval—but do not wait if the service failed to start.
Distinguishing Agent Problems from Infrastructure Problems
| Observation | More likely Agent/config | More likely host/infrastructure |
|---|---|---|
| Only one integration missing | Integration conf under conf.d/ | — |
| All hosts in AZ stop reporting | — | Network ACL or DNS outage |
| Single host silent | Local service stopped | Local firewall |
| UI shows host, no system metrics | Check disabled | Hardware failure (rare) |
Security-Aware Troubleshooting
When logs show 401 Unauthorized or API key invalid, resist editing random keys. Confirm:
- The key in
datadog.yamlmatches the intended org DD_API_KEYenv var is not overriding with an old value in containers- You did not paste an application key where an API key belongs (Chapter 2 explains the difference)
Rotating keys is a platform task; troubleshooting is verifying the running process sees the key you think it sees.
Practical Drills Before Exam Day
On a lab VM, deliberately:
- Break YAML indentation and observe failed start
- Stop the service and note missing host metrics
- Fix permissions on a dummy check script and reload Agent
- Restore config and confirm status shows Running checks
These five-minute exercises beat rereading documentation because they connect motor memory to exam scenarios.
Bridge to Datadog-Specific Tools
Once OS basics confirm the service is alive, Datadog's CLI refines diagnosis:
agent status— running checks, DogStatsD stats, forwarder healthagent flare— support bundle (know when not to flare secrets to untrusted parties)agent configcheck— dry-run integration configs
Chapter 5 is your deep dive. Fundamentals items often pair one OS fact (service name, log directory, permission) with one Agent fact (status subcommand output). Answer the layer the question actually asks about.
Closing Perspective
Computer fundamentals are not filler—they explain why Datadog behaves as it does on real servers. Hostnames identify machines, YAML configures them, TCP carries telemetry, and systemd keeps the Agent alive. Master these habits and the product-specific chapters become implementation details instead of mystery boxes.
On Linux with systemd, which command most directly shows whether the Datadog Agent service is running?
After editing datadog.yaml, the Agent fails immediately on restart. What should you inspect first?
An integration check fails while the core Agent service stays running. What is a plausible OS-level explanation?