enable-ssi

Configure SSI and Unified Service Tags on Linux

Before doing anything else: Fully resolve all variables in ## Context to resolve before acting. Do not begin Step 0 until every variable has a concrete value.

Triggers

Invoke this skill when:

• The Datadog Agent is already installed with SSI (DD_APM_INSTRUMENTATION_ENABLED=host was used) and you need to configure Unified Service Tags on the application service
• The user wants to set DD_SERVICE, DD_ENV, DD_VERSION on a running service
• SSI is installed but /proc/<pid>/maps doesn't show the language tracer (launcher-only injection)

Do NOT invoke this skill if:

• The Datadog Agent is not yet installed — run agent-install first
• SSI packages are missing from /opt/datadog-packages/ — re-run agent-install
• The target is a Kubernetes cluster — use dd-apm-k8s-enable-ssi instead

Background

When the install script runs with DD_APM_INSTRUMENTATION_ENABLED=host, it:

1. Installs datadog-apm-inject and language library packages under /opt/datadog-packages/
2. Writes the launcher path into /etc/ld.so.preload
3. SSI is now armed — every new process on the host gets the launcher injected at startup

What SSI does NOT configure automatically:

• DD_SERVICE, DD_ENV, DD_VERSION — these must be set on the application process for traces to be tagged correctly
• Without DD_SERVICE, the tracer auto-detects a service name (often the process name or framework name), which may not match what the user expects

Prerequisites

Verify SSI is armed:

Claude runs

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST

If /etc/ld.so.preload contains a path to the launcher, and /opt/datadog-packages/datadog-apm-inject exists — SSI is armed.

ERROR: Either missing — run agent-install first.

Check for existing manual instrumentation:

Claude runs

ERROR: Manual instrumentation found — SSI silently disables itself when it detects an existing tracer. Remove the manual import/package before proceeding.

Check base libc:

Claude runs

ERROR: musl — SSI requires glibc. No workaround; must use a glibc-based OS.

Context to resolve before acting

Step 0 (Only if existing instrumentation detected): Remove Manual Instrumentation

• Python: pip uninstall ddtrace, remove import ddtrace / ddtrace-run from CMD
• Node.js: npm uninstall dd-trace, remove require('dd-trace')
• Java: remove -javaagent:/path/to/dd-java-agent.jar JVM flag
• Ruby: gem uninstall ddtrace, remove require 'ddtrace'
• .NET: remove Datadog.Trace NuGet and profiler env vars

After removing, restart the service. Confirm with the user before restarting. Tell the user: "I need to restart <SYSTEMD_SERVICE_NAME> to remove the old instrumentation. This will cause a brief outage. Ready to proceed?" Wait for confirmation.

Step 1: Set Unified Service Tags on the Application Process

Without UST, traces arrive with an auto-detected service name that may not match user expectations, and won't be tagged with env or version.

For systemd-managed services (most common):

Claude runs

Add a drop-in override (preserves the original unit file):

What you need to do in a terminal

Add to the editor:

Apply:

Claude runs

If the UST vars appear in the output — configuration applied.

For supervisord:

Reload: sudo supervisorctl reload

For pm2:

Reload: pm2 reload <app>

Step 2: Restart the Service

Confirm with the user before restarting. Tell the user: "I need to restart <SYSTEMD_SERVICE_NAME> for SSI to inject into it. This will cause a brief outage. Ready to proceed?" Wait for confirmation.

Claude runs

If active is returned — service is running.

ERROR: Returns failed — check logs:

Step 3: Confirm Injection and UST in the Running Process

Claude runs

Use the PID:

If both the launcher and language library appear in maps, and UST vars are in environ — SSI and tagging are fully configured.

ERROR: Launcher in maps but no language library — injection attempted but failed. Run:

Go to troubleshoot-ssi if errors are present.

Done

Exit when ALL of the following are true:

• Launcher and language library visible in /proc/<PID>/maps
• DD_SERVICE, DD_ENV, DD_VERSION present in /proc/<PID>/environ
• Service is running and healthy

Automatically proceed to verify-ssi now — do not ask the user for permission.

Security constraints

• Never write a raw API key into any file or chat message
• Always confirm with the user before restarting production services
• Do not modify application source code — configure only via environment variables in the service unit