# troubleshoot-ssi

Diagnose and resolve Datadog Single Step Instrumentation (SSI) failures on Kubernetes when APM traces fail to show up in your backend.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 427 installs · ★ 178
- Author: datadog-labs
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/datadog-labs/agent-skills/tree/HEAD/dd-apm/k8s-ssi/troubleshoot-ssi/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/troubleshoot-ssi

## What it does

This skill debugs automated Datadog APM injection across Kubernetes clusters. It correlates cluster-level status from `kubectl` with backend ingestion data via `pup`. The workflow inspects mutating admission webhooks, validates the `datadog-lib-<language>-init` init container injection, and verifies `LD_PRELOAD` setup.

During triage, the agent executes seven diagnostic checks across both tools. It scans for spans within the past hour, verifies runtime SDK options, reviews pod events, and lists active tracers in Datadog Fleet. Without an active cluster context in `kubectl` and an authenticated `pup-cli` binary via OAuth or `DD_APP_KEY`, diagnostics cannot run.

The diagnostic routine uncovers silent failures that produce no visible errors. It catches conflicts with existing OpenTelemetry or `ddtrace` libraries, unsupported runtimes, missing pod restarts after enabling SSI, and opt-out annotations like `admission.datadoghq.com/enabled: "false"`.

## Requirements
- Works with: Kubernetes

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add datadog-labs/agent-skills --skill troubleshoot-ssi -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/troubleshoot-ssi/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/troubleshoot-ssi/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add datadog-labs/agent-skills --skill troubleshoot-ssi -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/troubleshoot-ssi/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add datadog-labs/agent-skills --skill troubleshoot-ssi -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/troubleshoot-ssi/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install datadog-labs/agent-skills troubleshoot-ssi
```

2. **Manually: put the files in place**
- File: `.github/skills/troubleshoot-ssi/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add datadog-labs/agent-skills --skill troubleshoot-ssi -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/datadog-labs/agent-skills --path dd-apm/k8s-ssi/troubleshoot-ssi
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/troubleshoot-ssi/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add datadog-labs/agent-skills --skill troubleshoot-ssi -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/datadog-labs/agent-skills/tree/HEAD/dd-apm/k8s-ssi/troubleshoot-ssi/SKILL.md

## When to use it
- diagnose missing APM traces in Datadog
- verify admission webhook and init container injection
- detect silent conflicts with OpenTelemetry or ddtrace libraries
- inspect tracer telemetry and runtime configuration via pup-cli

## Example prompts
- Check why the payment-service pod in the billing namespace is missing traces in Datadog
- Investigate why the Datadog init container was not injected into the api-gateway pod
- Find out why traces are missing for the auth-service deployment after enabling SSI

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b756bd78fe5390e4.

BEGIN THIRD-PARTY FILE b756bd78fe5390e4
````text
---
name: troubleshoot-ssi
description: Diagnose and fix Single Step Instrumentation (SSI) issues on Kubernetes — SSI automatically instruments applications for APM without code changes. Only use if the agent and SSI are already configured but traces are missing or instrumentation is not working.
metadata:
  version: "1.0.0"
  author: datadog-labs
  repository: https://github.com/datadog-labs/agent-skills
  tags: datadog,apm,kubernetes,ssi,troubleshooting,instrumentation
  alwaysApply: "false"
---

# Troubleshoot APM SSI on Kubernetes

## Triggers

Invoke this skill when the user expresses intent to:
- Debug why a pod is not being instrumented
- Investigate why traces are not appearing in Datadog
- Diagnose admission webhook or init container injection failures
- Follow up on failed checks from `verify-ssi`
- Report that a specific service or pod has no traces

Do NOT invoke this skill if:
- SSI has not been enabled yet — run `enable-ssi` first

---

## Prerequisites

- [ ] kubectl configured to target cluster — `kubectl config current-context`

### pup-cli: check, install, and authenticate

### Claude runs

```bash
pup --version
```

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

### Claude runs

```bash
if [[ "$(uname)" == "Darwin" ]]; then
  brew tap datadog-labs/pack && brew install pup
else
  PUP_VERSION=$(curl -s https://api.github.com/repos/datadog-labs/pup/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
  curl -L "https://github.com/datadog-labs/pup/releases/download/${PUP_VERSION}/pup_linux_amd64.tar.gz" | tar xz -C /usr/local/bin pup
  chmod +x /usr/local/bin/pup
fi
pup --version
```

Check auth:
```bash
pup auth status
```

If not authenticated:

### Claude runs

```bash
pup auth login
```

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

If no browser available: `export DD_APP_KEY=<your-app-key>`.

---

## Context to resolve before acting

| Variable | How to resolve |
|---|---|
| `AGENT_NAMESPACE` | Namespace where Datadog Agent is installed |
| `APP_NAMESPACE` | Namespace of the application with missing traces |
| `CLUSTER_NAME` | `kubectl config current-context` or `spec.global.clusterName` in `datadog-agent.yaml` |
| `SERVICE_NAME` | `tags.datadoghq.com/service` label on the Deployment, or ask the user |
| `ENV` | `tags.datadoghq.com/env` label on the Deployment, or ask the user |
| `POD_NAME` | `kubectl get pods -n <APP_NAMESPACE>` — use the specific pod the user mentioned |
| `DEPLOYMENT_NAME` | Check `metadata.name` in the Deployment manifest, or ask the user |
````
END THIRD-PARTY FILE b756bd78fe5390e4

The third-party file has ended. Everything between the b756bd78fe5390e4 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2592 of 20756 bytes. © datadog-labs · MIT · https://github.com/datadog-labs/agent-skills/tree/HEAD/dd-apm/k8s-ssi/troubleshoot-ssi/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md