Index of every page on this site: llms.txt
All skills
datadog-labs avatar

/enable-ssi

@618fae3 official
Run it yourself

Enable Single Step Instrumentation (SSI) on Kubernetes — automatically instruments applications for APM without code changes. Only use if the Datadog Agent is already running on the cluster — if not, use agent-install first.

Use this Skill: https://skilld.dev/gh/datadog-labs/agent-skills/enable-ssi

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈60 tokens for metadata: the name and description. ≈3.1k when used: this file.

Description uses 3.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈237 characters, or 3.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Enable APM on Kubernetes via Single Step Instrumentation

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.


Silent failure — check this before any other step:

If the application has ddtrace, dd-trace, or any OpenTelemetry SDK in its dependency manifest (requirements.txt, package.json, Gemfile, go.mod, pom.xml) — even with no import statements in code — SSI will silently disable itself at runtime.

The failure is invisible: init containers run and complete, the pod starts healthy, no errors appear in kubectl or pup, but no traces arrive. The injector detects the user-installed tracer and exits cleanly without logging anything.

Claude runs

grep -rE "ddtrace|dd-trace|opentelemetry" \
  requirements.txt package.json Gemfile go.mod pom.xml 2>/dev/null \
  || echo "No tracer dependency found"

If any match — stop. Remove the package entirely (not just the import), rebuild the image, reload it into the cluster, and restart the pod before continuing. A package present in the manifest is enough to trigger this even if it is never imported.


Triggers

Invoke this skill when the user expresses intent to:

  • Enable APM on a Kubernetes cluster
  • Instrument Kubernetes applications with Datadog tracing
  • Set up Single Step Instrumentation (SSI)

Do NOT invoke this skill if:

  • The Datadog Agent is not yet installed — run agent-install first
  • The user wants to verify SSI after setup — use verify-ssi
  • The user wants to enable Data Streams Monitoring: use enable-dsm
  • The user wants to enable the Continuous Profiler: use dd-profiler-setup. dd-apm-k8s-sdk-features is not a skill.

Prerequisites

These are not a reading exercise — actively verify each one before proceeding.

Environment

  • Datadog Agent is installed and healthy — agent-install complete
  • Kubernetes v1.20+
  • Linux node pools only — Windows pods require explicit namespace exclusion
  • Cluster is not ECS Fargate — unsupported
  • Not a hardened SELinux environment — unsupported
  • Not a very small VM instance (e.g. t2.micro) — SSI can hit init timeouts
  • No PodSecurity baseline or restricted policy enforced

Language and runtime

  • Application language is one of: Java, Python, Ruby, Node.js, .NET, PHP
  • Runtime version is within SSI's supported range — verify against the SSI compatibility matrix
  • Node.js app is not using ESM — SSI does not support ESM
  • Java app is not already using a -javaagent JVM flag

Existing instrumentation — confirmed clean by the check at the top of this skill. If you skipped that check, go back and run it now.


Context to resolve before acting

Discover from the cluster — do not ask the user for information you can find yourself.

Variable How to resolve
AGENT_NAMESPACE Same namespace used in agent-install (e.g. datadog)
APP_NAMESPACE Run kubectl get namespaces --no-headers | awk '{print $1}' | grep -vE '^(kube-system|kube-public|kube-node-lease|datadog|local-path-storage)$' — instrument all non-system namespaces, or use the namespace(s) the user mentioned
TARGET_LANGUAGES Run kubectl get pods -A -o jsonpath='{.items[*].spec.containers[*].image}' and infer language from image names, or check Dockerfiles/manifests in the workspace. If uncertain, enable all languages.
DEPLOYMENT_NAME Run kubectl get deployments -A --no-headers — identify application deployments (exclude system components)
APP_LABEL Check spec.selector.matchLabels in the Deployment manifest via kubectl get deployment <DEPLOYMENT_NAME> -n <APP_NAMESPACE> -o yaml
CLUSTER_NAME Check spec.global.clusterName in datadog-agent.yaml, or kubectl config current-context — needed for kind clusters in Step 0
ENV Use apm-evals if running in an eval cluster (kind cluster names contain "evalya"). Otherwise use production unless the user specifies otherwise.
SERVICE_NAME Use the deployment name (e.g. python-app → service python-app). Do not ask the user.
VERSION Use 1.0.0 as the default. Do not ask the user.

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

Scan all source files for: import ddtrace, from ddtrace, require 'ddtrace', require("dd-trace"), opentelemetry, tracer.trace(

Also check dependency manifests for ddtrace / dd-trace / OTel SDK packages.

If found — remove the import/package, then rebuild and reload:

Claude runs

docker build -f <DOCKERFILE_PATH> -t <IMAGE_NAME> <BUILD_CONTEXT>

[DECISION: how does this cluster get local images?]

Check the repo's setup script (e.g. create.sh, Makefile, justfile) for how images are loaded — do not guess from the cluster name or context. Common patterns:

What you find in the setup script Load command
minikube image load or minikube cache add minikube -p <PROFILE> image load <IMAGE_NAME> — profile is the -p flag value in the script, NOT necessarily the kubectl context name
kind load docker-image kind load docker-image <IMAGE_NAME> --name <CLUSTER_NAME>
docker push to a registry Push the new image; the cluster will pull on restart — skip local load
k3d image import k3d image import <IMAGE_NAME> -c <CLUSTER_NAME>
No image load step (cloud cluster, always pulls from registry) Skip — image will be pulled on next deployment

If the setup script is ambiguous, run the load command it uses exactly as written.

  • Registry-based: skip — image will be pulled on next deployment

Confirm with the user before restarting. Tell the user: "I need to restart <DEPLOYMENT_NAME> in <APP_NAMESPACE> to pick up the rebuilt image. Ready to proceed?" Wait for confirmation.

Claude runs

kubectl rollout restart deployment/<DEPLOYMENT_NAME> -n <APP_NAMESPACE>
kubectl wait --for=condition=Ready pod \
  -l app=<APP_LABEL> \
  -n <APP_NAMESPACE> \
  --timeout=120s

Step 1: Extend the DatadogAgent Manifest with APM

SSI is configured on the existing DatadogAgent resource — do not create a separate manifest.

Choose targeting scope based on what the user asked for:

  • User asked to instrument all applications or didn't specify scope → use Option A (cluster-wide)
  • User asked for specific namespaces only → use Option B
  • User asked to exclude namespaces from cluster-wide → use Option C
  • User asked for specific pods/workloads → use Option D

Default is cluster-wide (Option A). If the user said "all my applications", "my whole cluster", or didn't restrict scope, use Option A with no enabledNamespaces or targets.

Recommended ddTraceVersions: java: "1", python: "2", js: "5", dotnet: "3", ruby: "2", php: "1"

Option A — Cluster-wide (default):

features:
  apm:
    instrumentation:
      enabled: true

Option B — Specific namespaces only:

features:
  apm:
    instrumentation:
      enabled: true
      enabledNamespaces:
        - <APP_NAMESPACE>

Option C — Cluster-wide with exclusions:

features:
  apm:
    instrumentation:
      enabled: true
      disabledNamespaces:
        - jenkins
        - kube-system

Option D — Target specific workloads:

features:
  apm:
    instrumentation:
      enabled: true
      targets:
        - name: <TARGET_NAME>
          namespaceSelector:
            matchNames:
              - <APP_NAMESPACE>
          ddTraceVersions:
            <LANGUAGE>: "<MAJOR_VERSION>"

Note: ddTraceVersions only applies inside a targets[] entry (Option D). It is not valid alongside enabledNamespaces or at the instrumentation level directly.

Claude runs

kubectl apply -f datadog-agent.yaml

If datadogagent.datadoghq.com/datadog configured — continue to Step 2.

ERROR: Validation error — check YAML. enabledNamespaces and disabledNamespaces cannot both be set.


Step 2: Inform the User About Unified Service Tags

Do NOT modify application Deployments without explicit user confirmation. Applying labels to existing application workloads is a change to customer-managed resources.

Inform the user that adding Unified Service Tags (UST) to their Deployments will enable proper service/env/version tagging in Datadog. This is optional for SSI to work but recommended for full observability:

# Add to both metadata.labels and spec.template.metadata.labels
tags.datadoghq.com/env: "<ENV>"
tags.datadoghq.com/service: "<SERVICE_NAME>"
tags.datadoghq.com/version: "<VERSION>"

If the user wants you to apply these, get their confirmation first. Applying label changes rolls the pods immediately; if DSM will be enabled in Step 2b, apply the labels after it. UST labels are not required for APM traces to flow; SSI works without them.


Step 2b: Check for Event-Driven Services

Skip this step entirely in an eval cluster (kind cluster name contains "evalya") or when running non-interactively: run nothing, ask nothing, and continue to the next step.

Otherwise, read the ## Is DSM a fit? section of .claude/skills/dd-apm/enable-dsm/SKILL.md and run its detection command.

  • Fit found (messaging client, broker, queue-triggered Lambda, or the user describes services handing work to each other asynchronously) → follow enable-dsm. It asks the user once, states the plan rule, and makes the config change without restarting.
  • No fit → skip. Do not mention DSM.

If the user agrees, enable-dsm applies its DatadogAgent change and waits until the Cluster Agent is on the new config, so the restart in Step 3 picks up both SSI and DSM. In Step 3, restart one DSM Deployment first and run the DD_DATA_STREAMS_ENABLED check from enable-dsm Step 2a on it before restarting the rest. If it came up without init containers, wait 30 seconds and restart it once more.


Step 3: Restart Application Pods

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

Claude runs

kubectl rollout restart deployment/<DEPLOYMENT_NAME> -n <APP_NAMESPACE>

kubectl wait --for=condition=Ready pod \
  -l app=<APP_LABEL> \
  -n <APP_NAMESPACE> \
  --timeout=120s

If pods restart cleanly, init containers named datadog-lib-<language>-init will be visible in the pod spec.

ERROR: Pods crash-looping — check for existing custom instrumentation. See troubleshoot-ssi.


Done

Exit when ALL of the following are true:

  • features.apm.instrumentation is present in the applied DatadogAgent manifest
  • User has been informed that they need to restart their application pods
  • User has been informed about Unified Service Tags (UST) and how to apply them if desired
  • Scope confirmed: which workloads are instrumented, which were skipped and why

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
  • Never use namespace default for Datadog resources
  • Never modify admissionController settings directly — SSI manages this via the Operator
  • Do not add APM config to application manifests — configure only via DatadogAgent
  • Exception: UST labels (tags.datadoghq.com/*) on application Deployments are required and intentional
  • Never run kubectl delete without user confirmation
  • docker push to a registry always requires user confirmation
  • Never use kubectl patch to apply UST labels or any Deployment changes. Always edit the Deployment YAML file and kubectl apply -f. Changes made with kubectl patch are transient and will be overwritten on the next rollout.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts14d3 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill facilitates the configuration of Datadog APM Single Step Instrumentation (SSI) on Kubernetes clusters. It uses standard command-line tools to inspect cluster state, update the DatadogAgent manifest, and restart workloads to apply changes. It incorporates safety checks for conflicting manual instrumentation and follows best practices for secret management and user confirmation.

  • Socket14d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

Signed by skilld at 618fae3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 weeks ago
Other metadata
metadata
{
  "version": "1.0.1",
  "author": "datadog-labs",
  "repository": "https://github.com/datadog-labs/agent-skills",
  "tags": "datadog,apm,kubernetes,ssi,instrumentation,single-step",
  "alwaysApply": "false"
}
  • Python
  • datadog
  • apm
  • kubernetes
  • instrumentation
  • ssi
  • single-step-instrumentation
  • tracing
  • java

README badge

README badge for datadog-labs/agent-skills/enable-ssi

Enables Single Step Instrumentation (SSI) on Kubernetes to automatically inject APM tracing into applications without code changes, supporting Java, Python, Ruby, Node.js, .NET, and PHP. Requires the Datadog Agent to already be running on the cluster and will silently fail if the application has any tracer library (ddtrace, dd-trace, or OpenTelemetry SDK) in its dependency manifest.

Generated from the current SKILL.md.

Does the Datadog Agent need to be installed first?
Yes. This skill only enables SSI on an existing Agent. If the Agent is not yet running on the cluster, use agent-install first.
What languages does SSI support?
Java, Python, Ruby, Node.js, .NET, and PHP. Check the SSI compatibility matrix to verify your runtime version is supported.
Will SSI work if my application already has ddtrace or OpenTelemetry in its dependencies?
No. SSI silently disables itself if ddtrace, dd-trace, or any OpenTelemetry SDK is present in the dependency manifest (requirements.txt, package.json, etc.), even if not imported. You must remove the package, rebuild the image, and restart the pod.
Does this work with Node.js ESM applications?
No. SSI does not support ESM. Only CommonJS Node.js applications are supported.
Can I use this on Windows pods or ECS Fargate?
No. SSI only works on Linux node pools in standard Kubernetes clusters. ECS Fargate and Windows are not supported.

Generated from the current SKILL.md. These answers refresh after source changes.