Deploying the Datadog Agent on Linux for Unified Metrics, Logs, and Traces

Desired Outcome: One Agent, Three Telemetry Streams

Instead of running separate collectors for metrics, logs, and traces, deploy the Datadog Agent as a single managed service on a Linux host. The goal is a host that reports system metrics, forwards file logs, and receives distributed traces—all visible in the Datadog UI under one hostname.

Prerequisites and Environment Checks

• A supported Linux distribution with systemd (for example, recent Debian, Ubuntu, RHEL, CentOS, or SUSE variants).
• Outbound HTTPS access to Datadog intake endpoints. The Agent pushes data outbound; no inbound firewall rules are required.
• A Datadog API key. Treat this as a secret credential and avoid embedding it in images or public repositories.
• Root or sudo privileges to install packages and manage system services.

Install the Agent Package

Install from the official Datadog package repository for your distribution. The repository method integrates with your system package manager, making upgrades and removal predictable.

Datadog provides an official installation script that detects your distribution, configures the package repository, installs the Agent, and starts the service. Run it as root or with sudo, substituting your API key:

DD_API_KEY=<YOUR_API_KEY> bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

Replace <YOUR_API_KEY> with your actual key. The script writes the key to /etc/datadog-agent/datadog.yaml and enables the service.

Risk: Passing the key on the command line exposes it in shell history and the process list. For automated environments, download the package and configure the key in datadog.yaml instead.

Configure Metrics, Logs, and Traces

System metrics are collected by default. Logs and APM (Application Performance Monitoring, which captures distributed traces) are optional subsystems that must be enabled.

Edit /etc/datadog-agent/datadog.yaml as root:

api_key: <YOUR_API_KEY>
site: datadoghq.com
logs_enabled: true
apm_config:
  enabled: true

If your organization uses a non-US region, set site accordingly (for example, datadoghq.eu). Confirm the correct value in your Datadog account settings.

To collect logs from a file, create a configuration file under /etc/datadog-agent/conf.d/. For example, to tail an application log:

logs:
  - type: file
    path: /var/log/myapp/app.log
    service: myapp
    source: myapp

Save this as /etc/datadog-agent/conf.d/myapp.d/conf.yaml. The directory name must match the integration name, and the file must be named conf.yaml.

Version caution: Configuration syntax and default settings can vary between Agent major versions. Confirm the exact keys and file paths in the version-specific documentation before enabling APM or log collection in production.

Restart and Verify the Service

Apply the configuration by restarting the Agent. Run this on the host with sudo:

sudo systemctl restart datadog-agent
sudo systemctl status datadog-agent

Expected check: The status command should show active (running) with no recent error entries. If the service fails to start, the status output usually includes the last few log lines.

Next, run the Agent status command to confirm subsystems:

sudo datadog-agent status

Look for sections indicating the Collector, Logs Agent, and Trace Agent are running. The exact output format varies by version, but critical errors or missing sections indicate a configuration problem.

Validate in the Datadog UI

Within a few minutes, the host should appear in Infrastructure > Host map. Confirm the hostname matches and that expected tags are present.

For logs, open Logs > Explorer and search for the service:myapp or source:myapp tag you configured. If metrics appear but logs do not, the most common causes are logs_enabled: false, incorrect file permissions, or a mismatched path in the log configuration.

For traces, open APM > Traces. If your application is not yet instrumented with a tracing library, the Trace Agent will be running but no traces will appear until your services emit them. The Agent acts as the collector and forwarder; it does not automatically generate traces from arbitrary applications.

Recovery and Rollback

If the Agent fails to start after a configuration change, first inspect the Agent logs:

sudo journalctl -u datadog-agent --since "10 minutes ago"

Common recovery steps:

1. Validate the API key: A missing or malformed key in datadog.yaml prevents the Agent from authenticating. Check for extra spaces or unescaped special characters.
2. Check network connectivity: From the host, test HTTPS access to the intake endpoint. If outbound port 443 is blocked, the Agent cannot report data.
3. Disable optional integrations: If enabling APM or logs introduced the failure, set the corresponding flag to false, restart, and confirm the base Agent runs before re-enabling them one at a time.

If you must remove the Agent entirely, stop the service and remove the package. On systemd hosts:

sudo systemctl stop datadog-agent
sudo apt-get remove datadog-agent   # Debian/Ubuntu
sudo yum remove datadog-agent       # RHEL/CentOS

Removing the package stops data collection immediately. Historical data already ingested remains in Datadog according to your retention settings.

Limitations and Practical Verification

The Agent collects host metrics and forwards logs and traces, but it does not replace application instrumentation. Traces require your services to use a supported tracing library. Log collection from rotated files depends on the Agent's file-tailing configuration and permissions.

Enabling logs and traces increases ingested data volume, which can affect billing. Review indexing and retention settings before broad rollout.

To verify the final state, confirm three things: the service is active, datadog-agent status lists the expected subsystems without critical errors, and the host plus at least one log or trace is visible in the Datadog UI. If any check fails, work backward through the recovery steps above.