datadog-cli

Überblick über den datadog-cli-Skill

Der datadog-cli-Skill hilft einem Agenten dabei, Datadog über die Kommandozeile für konkrete Observability-Aufgaben zu nutzen: Logs durchsuchen, Requests nachverfolgen, Metriken abfragen, Services auflisten und Dashboards verwalten. Am besten passt er für Engineers, SREs, Plattform-Teams und KI-gestützte Incident-Responder, die bereits Zugriff auf Datadog haben und bei der Triage schneller vorankommen wollen, ohne sich manuell durch die UI zu klicken.

Wofür der datadog-cli-Skill gedacht ist

Setze datadog-cli ein, wenn die eigentliche Aufgabe nicht „Datadog zusammenfassen“ lautet, sondern „ein Produktionssymptom mit reproduzierbaren Commands untersuchen“. Der Skill ist besonders stark, wenn du:

• einen Incident nach Service, Fehlertyp oder Zeitfenster eingrenzen musst
• von Logs in den Trace-Kontext wechseln willst
• prüfen willst, ob ein Spike neu oder normal ist
• schnell Metriken für einen Service oder eine Umgebung ziehen möchtest
• Dashboards in CLI-basierten Workflows prüfen oder aktualisieren willst

Für wen der datadog-cli-Skill am besten passt

Dieser datadog-cli skill passt zu Nutzern, die:

• Datadog bereits für Logs, Metriken, Traces oder Dashboards verwenden
• möchten, dass ein Agent korrekte Commands erzeugt statt vager Suchvorschläge
• Incident-Triage-Workflows brauchen, nicht generische Observability-Ratschläge
• Service-Namen, Zeiträume, Trace-IDs oder Dashboard-IDs angeben können

Wenn du keine Datadog-Keys hast oder eure Service-/Tag-Konventionen nicht kennst, sind Setup und Prompt-Qualität wichtiger als der Skill selbst.

Warum dieser Skill nützlicher ist als ein generischer Prompt

Ein normaler Prompt würde vielleicht sagen: „Schau in die Datadog-Logs.“ Dieser Skill gibt dem Agenten stattdessen einen Weg auf Command-Ebene vor: logs search, logs tail, logs trace, logs context, logs patterns, logs compare, metrics query, errors, services sowie Dashboard-Operationen. Außerdem verweist er auf die relevanten Referenzdokumente für eine korrekte Ausführung, besonders bei Query-Syntax und den Warnhinweisen zu Dashboard-Updates.

Wichtige Hürden vor der Einführung des datadog-cli-Skills

Die wichtigsten Blocker sind operativ, nicht konzeptionell:

• DD_API_KEY und DD_APP_KEY sind erforderlich
• bei Datadog-Accounts außerhalb der USA muss unter Umständen --site gesetzt werden, etwa datadoghq.eu
• die Ergebnisse hängen stark von korrekter Datadog-Query-Syntax ab
• Dashboard-Updates sind destruktiv, wenn Felder ausgelassen werden

Das sind die ersten Punkte, die du prüfen solltest, bevor du die Qualität der datadog-cli usage bewertest.

So verwendest du den datadog-cli-Skill

Installation und Laufzeitkontext

Der Skill selbst liegt in softaworks/agent-toolkit, aber die eigentliche CLI, deren Nutzung er dem Agenten beibringt, ist:

npx @leoflores/datadog-cli <command>

Setze zuerst die Credentials:

export DD_API_KEY="your-api-key"
export DD_APP_KEY="your-app-key"

Für Datadog-Sites außerhalb der USA übergib --site:

npx @leoflores/datadog-cli logs search --query "*" --site datadoghq.eu

Für eine praktische datadog-cli install-Entscheidung ist die entscheidende Abhängigkeit die externe CLI plus funktionierender Datadog-API-Zugriff.

Diese Dateien solltest du vor dem ersten echten Einsatz lesen

Dieser Skill ist ungewöhnlich stark referenzgetrieben. Lies in dieser Reihenfolge:

1. SKILL.md
2. references/query-syntax.md
3. references/logs-commands.md
4. references/metrics.md
5. references/workflows.md
6. references/dashboards.md

Dieser Pfad reduziert die meisten Fehler beim ersten Einsatz: schlechte Filter, schwache Zeitfenster und unsichere Dashboard-Änderungen.

Welche Eingaben der datadog-cli-Skill für gute Ergebnisse braucht

Der datadog-cli skill liefert die besten Ergebnisse, wenn deine Anfrage zumindest einen Teil der folgenden Angaben enthält:

• Service-Name, Team-Name oder Umgebung
• ein Zeitfenster wie 15m, 1h oder 24h
• Symptomtyp: Fehler, Latenz, fehlgeschlagene Requests, Regressions nach Deployments
• Trace-ID, Request-ID oder Zeitstempel, falls vorhanden
• ob du Logs, Metriken, Dashboards oder einen Triage-Workflow möchtest
• die Datadog-Site, falls nicht die US-Standardumgebung

Schwache Eingabe: „Check Datadog.“
Starke Eingabe: „Investigate payment-api 5xx errors in prod for the last hour, compare against the previous hour, then pull any related traces and CPU metrics.“

Aus einem groben Ziel einen brauchbaren datadog-cli-Prompt machen

Ein guter datadog-cli guide-Prompt sollte dem Agenten sowohl das Ziel als auch die Eingrenzungsdimensionen mitgeben.

Versuche dieses Muster:

Use datadog-cli for Observability triage.
Goal: identify why checkout failures increased after the last deploy.
Scope: service:payment-api env:prod
Time: last 1h, compare with previous 1h
Need: error summary, common log patterns, likely trace IDs, and key metrics
Site: datadoghq.eu

Warum das funktioniert:

• es gibt dem Agenten einen Workflow vor, nicht nur ein einzelnes Command
• es enthält Query-Tags, die die CLI tatsächlich nutzen kann
• es verhindert, dass der Agent zu breit sucht

Die besten ersten datadog-cli-Commands für typische Aufgaben

Für Incident-Triage solltest du breit starten und dann eingrenzen:

npx @leoflores/datadog-cli errors --from 1h --pretty
npx @leoflores/datadog-cli logs compare --query "status:error" --period 1h --pretty
npx @leoflores/datadog-cli logs patterns --query "status:error" --from 1h --pretty

Danach auf den Service einschränken:

npx @leoflores/datadog-cli logs search --query "service:payment-api status:error env:prod" --from 1h --pretty

Wenn du bereits einen Trace hast:

npx @leoflores/datadog-cli logs trace --id "TRACE_ID" --from 24h --pretty

Für den Gesundheitszustand eines Services:

npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{env:prod,service:payment-api}" --from 1h --pretty

Warum Query-Syntax beim datadog-cli wichtiger ist, als viele erwarten

Viele schwache Ergebnisse bei datadog-cli usage sind in Wahrheit Probleme mit der Query-Qualität. Der Skill baut auf Datadog-Suchsyntax auf wie:

• service:api status:error
• @http.status_code:>=500
• service:api OR service:payment
• @duration:[1000 TO 5000]
• -status:info

Wenn du deine Felder kennst, gib sie explizit an. Wenn nicht, bitte den Agenten, mit breiteren Discovery-Queries zu starten und die Suche dann anhand der zurückgegebenen Attribute zu verengen.

Praktischer datadog-cli-Workflow für die Incident Response

Ein starker Untersuchungskreislauf mit datadog-cli ist:

1. Fehlerüberblick mit errors holen
2. aktuellen Zeitraum mit dem vorherigen per logs compare vergleichen
3. wiederkehrende Fehlermuster mit logs patterns clustern
4. mit logs search nach Service/Umgebung eingrenzen
5. umliegende Aktivitäten mit logs context prüfen
6. mit logs trace in den verteilten Ablauf wechseln
7. Ressourcen- oder Durchsatzsignale mit metrics query bestätigen

Das ist deutlich besser, als wiederholt nach „mehr Logs“ zu fragen, weil jedes Command eine andere diagnostische Frage beantwortet.

Bei Dashboards im datadog-cli-Skill ist besondere Vorsicht nötig

Der wichtigste Sicherheitshinweis in diesem Repo lautet: dashboards update ersetzt das komplette Dashboard, nicht nur geänderte Felder. Wenn Felder wie Template-Variablen, Beschreibung oder Notify-Liste fehlen, können sie entfernt werden.

Vor jedem Update ist dieser sichere Workflow sinnvoll:

1. das Dashboard mit --output in eine temporäre Datei exportieren
2. bestehende Felder erhalten
3. mit der vollständig beibehaltenen Struktur aktualisieren

Damit eignet sich der datadog-cli skill für Dashboard-Arbeiten nur dann, wenn du Backups und Full-State-Updates konsequent einhältst.

Tipps zur Ausgabequalität, die bei datadog-cli wirklich einen Unterschied machen

Für bessere Antworten des Agenten:

• gib an, ob du Discovery, Erklärung oder exakte Commands willst
• nenne Service- und Env-Tags möglichst gemeinsam
• beginne mit einem begrenzten Zeitfenster und erweitere nur bei Bedarf
• fordere bei Regressionsprüfungen einen Vergleich mit einem früheren Zeitraum an
• bevorzuge eine Trace-ID oder einen Zeitstempel, wenn du bereits einen hast
• fordere --pretty an, wenn Menschen die Ausgabe prüfen sollen

Der größte Qualitätsgewinn kommt meist von einem präzisen Query-Ziel, nicht von ausführlicherer Analyse.

Wann du Logs, Metriken oder Dashboards verwenden solltest

Verwende Logs, wenn du konkrete Events, Fehler oder Request-Details brauchst.
Verwende Metriken, wenn du Trends, Ressourcenauslastung oder Rate-/Latenzsignale brauchst.
Verwende Dashboards, wenn du vorhandenen operativen Kontext brauchst oder eine Sicht für ein Team aufbereiten willst.

Wenn du den Agenten auf einmal nach allen drei fragst, sag ihm auch, welches Entscheidungsziel im Vordergrund steht: Root Cause, Blast Radius, Regressionsprüfung oder Dashboard-Erstellung.

FAQ zum datadog-cli-Skill

Ist datadog-cli gut für Einsteiger?

Ja, wenn du bereits Datadog-Zugriff hast und Grundbegriffe wie Services, Tags und Zeitfenster kennst. Nein, wenn du erst noch lernst, was Logs, Traces und Metriken überhaupt abbilden. Der Skill reduziert das Rätselraten bei Commands, ersetzt aber nicht das Wissen über eure Umgebungsnamen und Observability-Konventionen.

Worin unterscheidet sich datadog-cli von der direkten Nutzung der Datadog-UI?

datadog-cli ist besser, wenn du reproduzierbare, skriptbare und agentengenerierte Untersuchungsschritte willst. Besonders nützlich ist das bei schneller Triage, promptgesteuertem Debugging und dem Teilen exakter Commands. Für tiefe visuelle Exploration und spontanes Browsing bleibt die UI die bessere Wahl.

Wann ist datadog-cli keine gute Wahl?

Nutze diesen Skill nicht, wenn:

• deine Organisation die Nutzung von Datadog-API-Keys blockiert
• du UI-only-Features brauchst, die im CLI-Workflow nicht verfügbar sind
• du eher allgemeine Observability-Theorie als Datadog-spezifische Ausführung suchst
• du dem Agenten nicht genug Kontext geben kannst, um gültige Queries zu bilden

Muss ich außer dem Skill noch etwas installieren?

Ja. Die kritische Laufzeitabhängigkeit ist die Datadog-CLI, die so aufgerufen wird:

npx @leoflores/datadog-cli <command>

Außerdem brauchst du DD_API_KEY und DD_APP_KEY. Bei manchen Accounts musst du zusätzlich --site übergeben.

Ist datadog-cli nur für Observability gedacht, oder kann es auch Änderungen vornehmen?

In erster Linie hilft es beim Prüfen und Untersuchen, aber Dashboard-Commands können den Zustand verändern. Genau dort ist Vorsicht am wichtigsten. Lies references/dashboards.md, bevor du irgendeinen Update-Workflow zulässt.

Ist datadog-cli besser, als einen Agenten einfach zu bitten, „Logs zu checken“?

Ja, weil der Skill dem Agenten konkrete Command-Familien und Referenzdokumente an die Hand gibt. Das führt in der Regel zu schnellerer Eingrenzung, weniger fehlerhaften Queries und nützlicheren Incident-Workflows als gewöhnliche freie Prompts.

So verbesserst du den datadog-cli-Skill

Starte datadog-cli-Prompts mit operativen Rahmenbedingungen

Der schnellste Weg zu besserer datadog-cli-Ausgabe ist, die Rahmenbedingungen mitzugeben, die die CLI tatsächlich braucht:

• Datadog-Site
• Umgebung
• Service-Namen
• Zeitbereich
• Identifier wie Trace-ID oder Dashboard-ID
• ob die Aufgabe read-only ist oder Dashboards verändern darf

Ohne diese Angaben fällt der Agent oft auf breite, signalarme Commands zurück.

Bitte um einen Workflow, nicht nur um ein einzelnes Command

Ein häufiger Fehler ist ein Prompt für eine einzelne Abfrage, obwohl das Problem eine Sequenz braucht. Besserer Prompt:

Use datadog-cli to triage a spike in 5xx responses for service:checkout in env:prod over the last hour.
First compare against the prior hour, then identify top error patterns, then pull relevant traces, then check CPU and memory metrics.

Das liefert bessere Untersuchungen, weil es direkt auf die Workflow-Referenzen des Repos einzahlt.

Liefere stärkere Zutaten für Queries

Gute Inputs enthalten echte Datadog-Felder:

• service:payment-api
• env:prod
• @http.status_code:>=500
• @error.kind:TimeoutError
• @duration:>=1000

Wenn du nur natürliche Sprache angibst wie „the API is slow“, muss der Agent Feldnamen und Filter erraten. Konkrete Angaben auf Feldebene führen zu besserer datadog-cli usage.

Bei Dashboard-Änderungen mit einem Safety-First-Prompt arbeiten

Wenn deine Aufgabe Dashboards betrifft, fordere ausdrücklich einen Backup-First-Workflow:

Use datadog-cli to update dashboard abc-def-ghi, but first export the current dashboard to a temp file, preserve template variables and description, and show the exact safe update command.
Do not produce a partial update.

Damit reduzierst du das größte destruktive Risiko dieses Skills deutlich.

Nach der ersten Ausgabe iterieren statt blind zu verbreitern

Nach dem ersten Command-Set verbesserst du die Ergebnisse am besten durch Eingrenzung:

• von allen Fehlern auf einen einzelnen Service
• von 24h auf das exakte Fehlerfenster
• von generischen Logs auf Pattern-Gruppierung
• vom Symptom zu Evidenz auf Trace-Ebene
• von Logs zu bestätigenden Metriken

Das ist besser, als den Agenten einfach nach „mehr Details“ zu fragen — das erzeugt oft nur mehr Rauschen.

Häufige Fehler, die du vermeiden solltest

Die häufigsten Probleme bei Einführung und Output sind:

• fehlendes DD_API_KEY oder DD_APP_KEY
• vergessenes --site bei Datadog außerhalb der USA
• schwache oder ungültige Query-Syntax
• ein anfangs zu großer Suchzeitraum
• die Annahme, dass Dashboard-Update wie ein Patch funktioniert statt als kompletter Ersatz
• Observability-Hilfe anzufragen, ohne den betroffenen Service oder env zu nennen

Was du im Repo prüfen solltest, wenn datadog-cli-Ergebnisse zu generisch wirken

Wenn der Agent zu allgemein bleibt, geh zurück zu:

• references/query-syntax.md für präzisere Filter
• references/logs-commands.md für die richtige Command-Wahl
• references/workflows.md für die sinnvolle Reihenfolge der Untersuchung
• references/dashboards.md für sichere Muster bei Änderungen

Dieser Leseweg behebt schwache Prompts in der Regel schneller, als die gesamte Anfrage von Grund auf neu zu formulieren.

Die beste Methode, datadog-cli nach der Installation zu bewerten

Ein praktikabler Akzeptanztest für datadog-cli install ist:

1. eine bekannte logs search ausführen
2. eine eingegrenzte metrics query ausführen
3. ein Workflow-Command wie errors oder logs patterns testen
4. das Verhalten von --site prüfen, falls du außerhalb der USA bist
5. keine Dashboard-Schreibzugriffe zulassen, bevor der Backup-Workflow verifiziert ist

Wenn das alles funktioniert, ist der datadog-cli skill sehr wahrscheinlich bereit für echte Incident- und Observability-Arbeit.