datadog-cli

Vue d’ensemble du skill datadog-cli

Le datadog-cli skill aide un agent à utiliser Datadog en ligne de commande pour des tâches d’observabilité concrètes : rechercher dans les logs, suivre des traces de requêtes, interroger des métriques, lister des services et gérer des dashboards. Il convient surtout aux ingénieurs, SRE, équipes plateforme et intervenants d’astreinte assistés par IA qui ont déjà accès à Datadog et veulent accélérer le triage sans passer leur temps à cliquer dans l’interface.

À quoi sert datadog-cli

Utilisez datadog-cli quand le vrai besoin n’est pas « résumer Datadog », mais « enquêter sur un symptôme en production avec des commandes reproductibles ». Le skill est particulièrement utile quand vous devez :

• circonscrire un incident par service, type d’erreur ou fenêtre temporelle
• passer des logs au contexte de trace
• vérifier si un pic est nouveau ou habituel
• récupérer rapidement des métriques pour un service ou un environnement
• inspecter ou mettre à jour des dashboards via des workflows pilotés par CLI

Pour quels profils ce skill est le plus adapté

Ce datadog-cli skill convient aux utilisateurs qui :

• utilisent déjà Datadog pour les logs, métriques, traces ou dashboards
• veulent qu’un agent génère des commandes correctes plutôt que des suggestions de recherche vagues
• ont besoin de workflows de triage d’incident, pas de conseils génériques sur l’observabilité
• sont à l’aise pour fournir des noms de service, plages horaires, trace IDs ou dashboard IDs

Si vous n’avez pas de clés Datadog ou si vous ne maîtrisez pas vos conventions de services et de tags, la qualité du setup et du prompt pèsera davantage que le skill lui-même.

Pourquoi ce skill est plus utile qu’un prompt générique

Un prompt classique pourrait dire « regarde les logs Datadog ». Ce skill donne à l’agent un chemin d’exécution au niveau commande : logs search, logs tail, logs trace, logs context, logs patterns, logs compare, metrics query, errors, services, ainsi que les opérations sur dashboards. Il renvoie aussi vers les documentations de référence qui comptent vraiment pour exécuter correctement les commandes, en particulier la syntaxe des requêtes et les avertissements liés aux mises à jour de dashboards.

Les principaux freins à connaître avant de commencer

Les vrais blocages sont surtout opérationnels, pas conceptuels :

• DD_API_KEY et DD_APP_KEY sont obligatoires
• les comptes Datadog hors US peuvent nécessiter --site, par exemple datadoghq.eu
• les résultats dépendent fortement d’une syntaxe de requête Datadog correcte
• les mises à jour de dashboards sont destructrices si certains champs sont omis

Ce sont les premiers points à vérifier avant de juger la qualité d’usage de datadog-cli.

Comment utiliser le skill datadog-cli

Installation et contexte d’exécution

Le skill lui-même se trouve dans softaworks/agent-toolkit, mais la CLI réelle qu’il apprend à l’agent à exécuter est :

npx @leoflores/datadog-cli <command>

Commencez par définir les identifiants :

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

Pour les sites Datadog hors US, ajoutez --site :

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

Pour prendre une décision réaliste sur datadog-cli install, la dépendance à valider est la CLI externe elle-même, plus un accès Datadog API fonctionnel.

Fichiers à lire avant la première utilisation réelle

Ce skill s’appuie fortement sur ses références. Lisez-les dans cet ordre :

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

Cet ordre évite la plupart des erreurs de départ : mauvais filtres, fenêtres temporelles peu pertinentes et modifications de dashboards risquées.

Les entrées dont le skill a besoin pour bien fonctionner

Le datadog-cli skill donne les meilleurs résultats quand votre demande contient au moins une partie des éléments suivants :

• nom de service, nom d’équipe ou environnement
• fenêtre temporelle comme 15m, 1h ou 24h
• type de symptôme : erreurs, latence, requêtes en échec, régression après déploiement
• trace ID, request ID ou timestamp si vous en avez un
• si vous voulez des logs, des métriques, des dashboards ou un workflow de triage
• le site Datadog si vous n’êtes pas sur le site US par défaut

Entrée faible : « Vérifie Datadog. »
Entrée solide : « Enquête sur les erreurs 5xx de payment-api en prod sur la dernière heure, compare avec l’heure précédente, puis récupère les traces associées et les métriques CPU. »

Transformer un objectif flou en prompt exploitable

Un bon prompt de type datadog-cli guide doit indiquer à l’agent à la fois l’objectif et les dimensions de cadrage.

Essayez ce modèle :

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

Pourquoi cela fonctionne :

• cela donne à l’agent un workflow, pas une commande isolée
• cela inclut des tags de requête que la CLI peut réellement exploiter
• cela évite à l’agent de chercher trop large

Les meilleures premières commandes pour les cas les plus courants

Pour le triage d’incident, commencez large, puis resserrez :

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

Ensuite, recentrez sur le service :

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

Si vous avez déjà une trace :

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

Pour l’état de santé d’un service :

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

Avec datadog-cli, la syntaxe de requête compte plus qu’on ne l’imagine

Beaucoup de résultats décevants avec datadog-cli viennent en réalité de requêtes mal formulées. Le skill repose sur la syntaxe de recherche Datadog, par exemple :

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

Si vous connaissez vos champs, indiquez-les explicitement. Sinon, demandez à l’agent de commencer avec des requêtes de découverte plus larges, puis de resserrer selon les attributs remontés.

Workflow pratique de réponse à incident

Une bonne boucle d’investigation avec datadog-cli ressemble à ceci :

1. obtenir une vue d’ensemble des erreurs avec errors
2. comparer la période actuelle à la précédente avec logs compare
3. regrouper les échecs récurrents avec logs patterns
4. filtrer par service/env avec logs search
5. inspecter l’activité autour des événements avec logs context
6. basculer vers le flux distribué avec logs trace
7. valider les signaux de charge ou de capacité avec metrics query

C’est nettement plus efficace que de redemander sans cesse « plus de logs », car chaque commande répond à une question de diagnostic différente.

Les dashboards demandent davantage de prudence

Le point de sécurité le plus important de ce dépôt est le suivant : dashboards update remplace le dashboard complet, et pas seulement les champs modifiés. Si des champs comme les variables de template, la description ou la notify list sont omis, ils peuvent être supprimés.

Avant toute mise à jour, le workflow sûr est :

1. récupérer le dashboard dans un fichier temporaire avec --output
2. conserver les champs existants
3. mettre à jour en réutilisant la structure complète conservée

Le datadog-cli skill n’est donc adapté au travail sur les dashboards que si vous êtes rigoureux sur les sauvegardes et les mises à jour en état complet.

Conseils de qualité de sortie qui changent vraiment les résultats

Pour obtenir de meilleures réponses de l’agent :

• précisez si vous voulez de la découverte, une explication ou des commandes exactes
• incluez ensemble les tags de service et d’environnement quand c’est possible
• choisissez d’abord une fenêtre temporelle bornée ; n’élargissez que si nécessaire
• demandez une comparaison avec une période précédente pour analyser une régression
• privilégiez un trace ID ou un timestamp si vous en avez déjà un
• demandez --pretty quand une relecture humaine est importante

Le plus gros gain de qualité vient généralement d’une cible de requête précise, pas d’une demande d’analyse plus verbeuse.

Quand utiliser les logs, les métriques ou les dashboards

Utilisez les logs quand vous avez besoin d’événements concrets, d’erreurs ou de détails de requêtes.
Utilisez les métriques quand vous cherchez des tendances, de l’usage de ressources ou des signaux de débit/latence.
Utilisez les dashboards quand vous voulez récupérer un contexte opérationnel existant ou construire une vue à partager avec une équipe.

Si vous demandez les trois à la fois à l’agent, indiquez clairement le but de la décision : cause racine, périmètre d’impact, vérification de régression ou création de dashboard.

FAQ sur le skill datadog-cli

Le skill datadog-cli est-il adapté aux débutants ?

Oui, si vous avez déjà accès à Datadog et maîtrisez les notions de base comme les services, tags et fenêtres temporelles. Non, si vous êtes encore en train d’apprendre ce que représentent logs, traces et métriques. Le skill réduit l’incertitude sur les commandes, mais ne remplace pas la connaissance de vos noms d’environnement et de vos conventions d’observabilité.

Qu’est-ce qui le distingue de l’utilisation directe de l’interface Datadog ?

datadog-cli est meilleur quand vous voulez des étapes d’investigation reproductibles, scriptables et générées par un agent. Il est particulièrement utile pour un triage rapide, du debugging piloté par prompt et le partage de commandes exactes. L’interface reste supérieure pour l’exploration visuelle approfondie et la navigation ad hoc.

Dans quels cas datadog-cli n’est pas un bon choix ?

N’utilisez pas ce skill si :

• votre organisation bloque l’usage des clés API Datadog
• vous avez besoin de fonctionnalités uniquement disponibles dans l’interface et non exposées par le workflow CLI
• vous cherchez de la théorie générale sur l’observabilité plutôt qu’une exécution spécifique à Datadog
• vous ne pouvez pas donner assez de contexte pour permettre à l’agent de formuler des requêtes valides

Faut-il installer autre chose que le skill ?

Oui. La dépendance d’exécution essentielle est la Datadog CLI invoquée ainsi :

npx @leoflores/datadog-cli <command>

Vous avez aussi besoin de DD_API_KEY et DD_APP_KEY. Pour certains comptes, il faut également passer --site.

datadog-cli sert-il seulement à l’observabilité, ou peut-il aussi modifier des éléments ?

Il aide surtout à inspecter et enquêter, mais les commandes sur dashboards peuvent modifier l’état. C’est là que la prudence est la plus importante. Lisez references/dashboards.md avant d’autoriser tout workflow de mise à jour.

Est-ce mieux que de demander simplement à un agent de « vérifier les logs » ?

Oui, parce que le skill fournit à l’agent des familles de commandes concrètes et les documents de référence associés. Cela se traduit généralement par un cadrage plus rapide, moins de requêtes mal formées et des workflows d’incident plus utiles qu’un prompting libre classique.

Comment améliorer le skill datadog-cli

Commencez vos prompts par les contraintes opérationnelles

Le moyen le plus rapide d’améliorer les sorties de datadog-cli consiste à inclure les contraintes dont la CLI a réellement besoin :

• site Datadog
• environnement
• noms de service
• plage temporelle
• identifiants comme trace ID ou dashboard ID
• si la tâche est en lecture seule ou si la modification de dashboards est autorisée

Sans cela, l’agent a souvent tendance à partir sur des commandes larges et peu informatives.

Demandez un workflow, pas seulement une commande

Un échec fréquent consiste à demander une recherche unique alors que le problème nécessite une séquence. Meilleur 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.

Cela produit de meilleures investigations, car le prompt s’aligne sur les références de workflow du dépôt.

Fournissez de meilleurs ingrédients de requête

Les bonnes entrées incluent de vrais champs Datadog :

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

Si vous ne fournissez qu’un langage naturel du type « l’API est lente », l’agent doit deviner les noms de champs et les filtres. Des entrées plus précises au niveau champ améliorent nettement l’usage de datadog-cli.

Pour les modifications de dashboards, imposez un prompt orienté sécurité

Si votre tâche touche aux dashboards, exigez explicitement un workflow avec sauvegarde préalable :

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.

Cela réduit fortement le principal risque destructeur de ce skill.

Itérez après la première sortie au lieu d’élargir à l’aveugle

Après le premier jeu de commandes, améliorez les résultats en resserrant :

• de toutes les erreurs vers un seul service
• de 24h vers la fenêtre exacte de défaillance
• de logs génériques vers un regroupement par patterns
• du symptôme vers des preuves au niveau trace
• des logs vers des métriques de confirmation

C’est bien plus efficace que de demander à l’agent « plus de détails », ce qui ajoute souvent surtout du bruit.

Erreurs courantes à éviter

Les problèmes d’adoption et de qualité de sortie les plus fréquents sont :

• DD_API_KEY ou DD_APP_KEY manquant
• oubli de --site pour Datadog hors US
• syntaxe de requête faible ou invalide
• plage temporelle trop large dès le départ
• traitement de la mise à jour de dashboard comme un patch au lieu d’un remplacement complet
• demande d’aide en observabilité sans préciser le service ou l’environnement concernés

Que vérifier dans le dépôt quand les résultats semblent faibles

Si l’agent reste trop générique, revenez à :

• references/query-syntax.md pour améliorer la précision des filtres
• references/logs-commands.md pour le choix des commandes
• references/workflows.md pour l’ordre d’investigation
• references/dashboards.md pour les schémas de modification sûrs

Ce parcours de lecture corrige généralement plus vite les prompts faibles qu’une réécriture complète de la demande.

La meilleure façon d’évaluer datadog-cli après l’installation

Un test d’acceptation concret pour datadog-cli install consiste à :

1. exécuter un logs search connu
2. lancer un metrics query bien cadré
3. tester une commande de workflow comme errors ou logs patterns
4. vérifier le comportement de --site si vous êtes hors US
5. éviter toute écriture sur les dashboards tant que le workflow de sauvegarde n’a pas été validé

Si tout cela fonctionne, le datadog-cli skill est probablement prêt pour un usage réel en incident et en observabilité.