Install the Datadog Agent on Linux hosts via SSH with Single Step Instrumentation (SSI) enabled — SSI automatically instruments applications for APM without code changes.
Before doing anything else: Fully resolve all variables in ## Context to resolve before acting. Do not begin Step 1 until every variable has a concrete value.
If it returns a hostname — proceed.
ERROR: Connection refused or timeout — resolve connectivity before continuing.
Once SSH is confirmed, present a plan to the user before proceeding. For example:
Here's what I'm going to do: 1. Install the Datadog Agent with SSI on: <host1>, <host2>, ... 2. Verify each agent is running and healthy 3. Discover services on each host that need restarting for SSI to take effect 4. After you restart services, verify instrumentation is workingReady to proceed?
Wait for user confirmation before starting installs.
If architecture is x86_64 or aarch64, and the OS is a supported distribution (Ubuntu 16.04+, Debian 9+, RHEL/CentOS 6-9, Amazon Linux 2/2023, SUSE 12+) — proceed.
ERROR: Architecture is armv7l (32-bit ARM) or unsupported OS — stop. Datadog Agent 7 and SSI do not support this configuration.
Check echo $DD_API_KEY first — if set, use it. Otherwise ask the user for their API key from Datadog UI: Organization Settings → API Keys. Never log or print the key.
DD_SITE
Check echo $DD_SITE first — if set, use it. Otherwise ask the user. Default: datadoghq.com. Options: datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com
SSH_KEY
Ask the user for the path to their SSH private key, or check CLAUDE.md
SSH_USER
Ask the user for the SSH username. Default: root
SSH_HOST
Ask the user for the hostname or IP of the target host
DD_APM_INSTRUMENTATION_ENABLED=host causes the install script to also install datadog-apm-inject and language library packages under /opt/datadog-packages/ in one pass.
If the script completes without errors — proceed to Phase 2.
Verify APM inject packages are present on disk (not just registered):
bash
ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \ "ls /opt/datadog-packages/ && sudo datadog-installer status 2>/dev/null | grep apm | head -10"
If /opt/datadog-packages/datadog-apm-inject exists — injection is available.
ERROR: Directory missing or empty — datadog-installer status may show the package as registered while its directory is actually empty (stale registration). Reinstall:
Verify hostname registration — the Agent must resolve and register its hostname for the host to appear in Datadog. DNS lookup failures are common in containers and minimal VMs:
bash
ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \ "sudo datadog-agent status 2>&1 | grep -iE '^\s+Hostname' | head -3"
If Hostname: <some-name> is shown — hostname resolved. Record this as DD_HOSTNAME for all subsequent steps.
ERROR: Hostname: (none) or any DNS resolution error — the agent can’t resolve its own FQDN. Fix by setting the hostname explicitly in datadog.yaml:
bash
# Read the actual system hostnameACTUAL_HOSTNAME=$(ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> "hostname")# Append to datadog.yaml only if not already setssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \ "grep -q '^hostname:' /etc/datadog-agent/datadog.yaml || \ echo \"hostname: ${ACTUAL_HOSTNAME}\" | sudo tee -a /etc/datadog-agent/datadog.yaml"# Restart the Agentssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \ "sudo systemctl restart datadog-agent 2>/dev/null || sudo service datadog-agent restart"# Confirm hostname is now registeredssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \ "sudo datadog-agent status 2>&1 | grep -iE '^\s+Hostname' | head -2"
SSI only injects into processes at startup. Existing processes keep running uninstrumented until restarted. Discover what’s running so the user knows what to restart.
For each application-level listener (ignore sshd, systemd, chronyd):
bash
ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> "# Command line of the processsudo cat /proc/<PID>/cmdline | tr '\0' ' '# Service manager (may not be available in all environments)sudo systemctl status <PID> 2>/dev/null | head -3 || true# Parent processPPID=\$(sudo awk '/PPid/ {print \$2}' /proc/<PID>/status)sudo cat /proc/\$PPID/cmdline | tr '\0' ' '"
Present findings to the user:
I found the following application services on <host>: Port 8080 — PID 1234 — /usr/bin/python3 /app/server.py Managed by: systemd unit flask-app.service Port 3000 — PID 5678 — node /app/server.js Managed by: supervisordThese services need to be restarted for Datadog SSI to inject into them.Restart them however is appropriate for your environment, then let me knowand I'll verify the instrumentation.
Do not offer to restart services. Do not restart services unless the user explicitly asks.
Not done: Agent running on each target host (datadog-agent status shows Running, API key valid)
Not done: /opt/datadog-packages/datadog-apm-inject exists on disk on each host
Not done: User has been informed which services need restarting
Not done: User has confirmed they are ready to restart services
Automatically proceed to enable-ssi (if services need UST labels configured) or verify-ssi (if services have already been restarted) — do not ask the user for permission.
Never write a raw API key into any file or chat message
Never store DD_API_KEY in shell history — pass it inline in the SSH command only
If the user’s API key appears in any output, redact it before displaying
Always confirm before restarting production services
About this skill
Trigger
Install the Datadog Agent on Linux hosts via SSH with Single Step Instrumentation (SSI) enabled — SSI automatically instruments applications for APM without code changes. Only use if no agent is installed yet.
The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.
MIT — the text of every skill is reproduced unmodified, frontmatter included, under the upstream licence.
Discovery
48 skills found by walking the repository tree for SKILL.md, not by matching a directory convention. 11 distinct layouts observed: agent-observability/*/SKILL.md, */SKILL.md, dd-apm/k8s-ssi/*/SKILL.md, dd-apm/linux-ssi/*/SKILL.md, dd-apm/*/SKILL.md, dd-apps/*/SKILL.md, dd-audit/*/SKILL.md, dd-browser-sdk/*/SKILL.md, dd-security/csm/*/SKILL.md, dd-software-delivery/*/SKILL.md, SKILL.md (repo root).
Issue colours
Resolved from a curated brand profile — hue 299°, chroma 0.183. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.
Heading repairs
1 repair applied to this skill so the document has one h1 and no skipped levels:
Shifted “16 headings” from h1 to h2 so the skill title is the only h1.
Spec compliance
12 editorial notes across 12 of 48 skills. They are printed in the margin of each skill rather than as errors here.
Images inside a skill come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.
Signal
Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.
Agent surfaces
The whole issue is available as one markdown document at /datadog-labs/agent-skills.md, and each skill at its own .md URL.
Publication
Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.