troubleshoot-ssi

Troubleshoot APM SSI on Linux

Triggers

Invoke this skill when the user expresses intent to:

• Debug why a Linux process is not being instrumented
• Investigate why traces are not appearing in Datadog from a Linux host
• Diagnose SSI injection failures on Linux
• Follow up on failed checks from verify-ssi
• Report that a specific service or host has no traces

Do NOT invoke this skill if:

• SSI has not been enabled yet — run enable-ssi first

Critical: pup First, SSH Second

You do NOT need SSH access to start troubleshooting. The pup CLI queries Datadog's backend directly. Start with pup commands immediately using information the user already gave you (hostname, service name, env). Only go to SSH if pup doesn't reveal the cause.

pup-cli: check, install, and authenticate

Claude runs

pup --version

If not found, install it (OS-aware):

Claude runs

if [[ "$(uname)" == "Darwin" ]]; then
  brew tap datadog-labs/pack && brew install datadog-labs/pack/pup
else
  PUP_VERSION

Auth — check in this order:

1. Check OAuth status:

If authenticated — proceed directly to Step 1.

ERROR: Not authenticated:

Claude runs

This opens a browser tab for OAuth. Complete the login there — Claude will continue once the command exits.

2. If OAuth login is not possible (e.g., no browser access), fall back to API keys:

If DD_API_KEY and DD_APP_KEY are both set — proceed to Step 1. pup will use them automatically even if pup auth status shows unauthenticated.

Context

Use what the user already provided. Do not ask for missing context upfront — resolve variables lazily, only when a specific step needs them.

If the user has already provided DD_HOSTNAME and SERVICE_NAME, go directly to Step 1. Do not ask for ENV or SSH details first.

How SSI Works on Linux — Domain Knowledge

Read this before investigating. It gives you the mental model to reason about novel failures.

Injection chain:

1. Install script (with DD_APM_INSTRUMENTATION_ENABLED=host) installs datadog-apm-inject and language library packages under /opt/datadog-packages/
2. The inject package writes its launcher path into /etc/ld.so.preload
3. The Linux dynamic linker pre-loads the launcher into every new process at startup
4. The launcher detects the process language and loads the appropriate tracer .so from /opt/datadog-packages/datadog-apm-library-<lang>/
5. The tracer sends spans to the Agent at localhost:8126
6. The Agent forwards traces to Datadog at intake.<DD_SITE>

Diagnostic layers:

• pup — sees what Datadog's backend received + injection errors reported by the launcher. Start here.
• /proc/<pid>/maps — sees the actual shared libraries loaded into a running process. The authoritative check for whether injection succeeded.
• datadog-agent status — sees whether the local Agent is receiving traces.

Known silent failures:

• musl libc (Alpine) — launcher is glibc-compiled; musl is ABI-incompatible. Linker loads it but injection silently aborts
• Existing ddtrace/OTel — launcher detects user-installed tracer and silently disables itself (already_instrumented result class)
• Unsupported runtime version — silently skipped
• Process started before SSI was enabled — /etc/ld.so.preload only affects new processes
• Static binary / Go — Go programs link statically and ignore LD_PRELOAD entirely
• SELinux/AppArmor — can block /etc/ld.so.preload reads for confined processes
• Package directory empty/corrupt — datadog-installer status reflects DB registration, not actual files. A package can show as installed while its directory is empty. Always verify files exist under /opt/datadog-packages/<package>/

Service name identity — important: With SSI, DD_SERVICE is often not set in the process environment. The tracer auto-detects a service name. The telemetry-reported name (what pup fleet tracers list and service-library-config get show) may not match what you expect in the APM UI:

• JVM: telemetry reports jar artifact name with version (e.g. inventory-service-1.0.0), spans use the base name (inventory-service)
• Python: telemetry may report fastapi or django rather than the app name
• Node.js: names typically match

If service-library-config get returns empty, use pup traces search --query "host:<DD_HOSTNAME>" --from 1h --limit 5 to discover what service names have been sending traces, then retry.

Step 1: Triage with pup (no SSH required)

Run these first. The answers determine everything that follows.

Claude runs

ENV is required for service-library-config get. If the user didn't provide it, state your assumed value (e.g. prod) and run it anyway — don't stop to ask.

Key values to check in service-library-config get output:

• apm_enabled — must be true. If false, the tracer won't send traces regardless of injection.
• trace_agent_url — must point to http://localhost:8126 or the correct agent socket. Wrong value = tracer can't reach the Agent.
• site — must match your Datadog org's site.

Presenting your findings (required)

Your final response is the deliverable — not your investigation transcript. It must include every diagnostic from this skill that you ran or that applies, each with its purpose and what you found. Avoid these failure modes:

• Omitting a required diagnostic. Your response must explicitly include, by name:

  • pup apm troubleshooting list --hostname <DD_HOSTNAME> — injection errors
  • pup apm service-library-config get --service-name <SERVICE_NAME> --env <ENV> — runtime SDK config
  • verification that apm_enabled is true and that trace_agent_url points to the correct agent endpoint (e.g. http://localhost:8126)
  • datadog-agent status for the APM receiver, and a /proc/<pid>/maps (or equivalent) check that the tracer .so is loaded into the process

  Run them if you have access; recommend them for the user to run if you don't.

• Substituting a proxy check. Confirming port 8126 is listening shows the Agent's receiver is up — it is not a substitute for verifying the tracer-side apm_enabled and trace_agent_url config keys. They answer different questions; report both.

• Concluding before the checks. Outline and run the diagnostics before settling on a root cause, then give specific per-finding remediation and note that the service must be restarted after any config or package fix.

Step 2: State Your Hypotheses

Before investigating, explicitly state your ranked hypotheses based on triage output. Do not skip this step.

State your top 1-3 hypotheses explicitly: "Based on triage, I think the most likely cause is X because Y."

Step 3: Investigate with pup (deeper)

Use only the tools relevant to your hypotheses.

Check SDK config in detail:

Key values to check:

• apm_enabled — if false, tracer won't send traces. Check source to see who disabled it (code > env_var > remote_config > default)
• trace_agent_url — should be http://localhost:8126 or a Unix socket. Wrong value = tracer can't reach Agent
• site — must match your Datadog org's site. Mismatch = traces going to wrong org
• service — with SSI and no DD_SERVICE set, source: default is expected

If service-library-config get returns empty — the service name you're using may not match the actual name in trace data:

Use the service field from trace results for subsequent config lookups.

Check injection error details:

Step 4: Investigate via SSH (if pup didn't reveal the cause)

Before asking for SSH credentials, briefly explain what you need to check and why, so the user understands the diagnostic plan before handing over access.

Is /etc/ld.so.preload set?

If it contains a path ending in launcher.preload.so or libdatadog-apm-inject.so — launcher is armed for new processes. ERROR: Empty or missing — SSI was not fully set up. Re-run the install script with DD_APM_INSTRUMENTATION_ENABLED=host.

Is the tracer actually loaded into the running process?

This is the authoritative injection check — use /proc/<pid>/maps, not environ:

Use the PID:

• Launcher + language library present — injection succeeded for this process
• Launcher only, no language library — launcher ran but couldn't inject the tracer (check pup troubleshooting list for the reason)
• Nothing — /etc/ld.so.preload not set, process started before SSI was enabled, or static binary

Was the process started before SSI was enabled?

If process started before /etc/ld.so.preload was written, restart the service. Always confirm with the user before restarting production services.

Is the base libc musl?

ERROR: musl — SSI's launcher requires glibc. No workaround; must migrate to Debian/Ubuntu/RHEL/Amazon Linux.

Is it a static binary?

ERROR: statically linked — SSI cannot instrument this binary. Manual instrumentation required.

Are the APM packages actually present on disk?

datadog-installer status reflects only DB registration — a package can show as installed while its directory is empty. Always verify:

ERROR: Directory empty or missing — package is registered but broken on disk. Use the remediation flow.

Does the app have existing manual instrumentation?

Also check dependency manifests: requirements.txt, package.json, Gemfile, pom.xml. ERROR: Found — SSI silently disabled itself. Remove manual tracer, restart the service.

Is the Agent APM receiver listening and receiving traces?

• feature_auto_instrumentation_enabled: true — SSI is active on the agent
• Receiver (previous minute) — trace count received by the agent
• Endpoints — where traces are forwarded

ERROR: Port 8126 not listening — APM receiver disabled. Check apm_config.enabled in /etc/datadog-agent/datadog.yaml.

What service name did the tracer register?

With SSI, DD_SERVICE is often not set. Read the tracer's memfd to find the real service name:

Use the fd number:

Returns service_name, service_env, tracer_version.

Is SELinux/AppArmor blocking /etc/ld.so.preload?

If SELinux/AppArmor is denying access, work with the user's security team. Do not disable SELinux systemwide.

Step 5: Reflect Before Concluding

Before applying any fix, answer:

1. What evidence confirms my hypothesis?
2. What evidence would contradict it — and have I checked?
3. Is there a simpler explanation I haven't considered?

If the conclusion doesn't hold up, return to Step 2 with new hypotheses.

Step 6: Fix

Remediation: Reinstalling a Broken APM Package

datadog-installer status reflects DB registration, not actual file presence. If pup troubleshooting list shows incorrect_installation but the installer says the package is installed, the registration is stale:

If re-running the install script is sufficient (package files are intact), use remove first only if the script reports success but the problem persists.

After any config change — restart the service (confirm with user first for production):

The user must restart the affected service for SSI to re-inject. Identify the service manager and present restart instructions — do not restart automatically unless the user explicitly asks.

Common restart commands:

Step 7: Verify

Re-run the pup triage commands to confirm the fix worked:

Claude runs

If there are no new injection errors and traces are arriving — resolved. Automatically proceed to onboarding-summary now — do not ask the user for permission.

ERROR: Still failing — return to Step 2 with updated hypotheses.

Security constraints

• Never write a raw API key into any file or chat message
• Never disable SELinux systemwide
• Always confirm before restarting production services
• datadog-installer remove requires explicit confirmation — confirm with user before running