Instrumentation en Observabilité LLM Datadog

Cette skill évalue le projet actuel (runtime backend, framework LLM/agent, instrumentation existante) et vous oriente vers le bon fichier de référence sous references/ pour les étapes de configuration réelles. Elle est complètement autonome — elle n'appelle aucun serveur MCP Datadog. Le provisionnement des credentials utilise l'outil local CreateApiKey, et tous les changements de code sont effectués par vous directement, en utilisant vos propres outils d'édition de fichiers.

Restez dans le périmètre d'Observabilité LLM. N'ajoutez pas d'instrumentation RUM, APM application, ni d'autres produits Datadog non liés. RUM et un Agent Datadog ne sont pertinents que parce qu'ils modifient ce qui est réalisable en termes de liaison session/trace (voir la section « Beyond SDK init » dans les fichiers de référence).

Ne pas inventer de noms d'outils. Utilisez uniquement CreateApiKey tel que décrit dans references/common-credentials.md ; toutes les autres étapes sont effectuées avec vos outils normaux de recherche/édition de fichiers.

Ne rien écrire en mémoire pendant ou après cette skill. Les chemins de projet, les frameworks, les credentials et les noms d'applications ML sont spécifiques au projet et ne doivent pas être stockés en mémoire persistante.

Règles de base lors de l'instrumentation

• Vérifiez avant d'affirmer. Si vous n'êtes pas sûr du contenu d'un fichier ou de la structure du codebase, lisez les fichiers — ne devinez pas.
• Vérifiez d'abord l'instrumentation existante. Avant de toucher au backend, vérifiez si ddtrace/dd-trace est déjà initialisé avec l'Observabilité LLM activée. Si c'est le cas, n'ajoutez pas un deuxième appel init/enable concurrent. Cela signifie uniquement sauter la réinit — cela ne veut pas dire sauter le travail. La présence du SDK n'est pas la même qu'une trace bien formée ou un ID de session qui circule réellement ; exécutez l'audit du câblage de l'ID de session en Phase 1d et fermez tout écart qu'il découvre, même quand le SDK est déjà présent.
• Utilisez uniquement les packages/features qu'on vous a explicitement dit d'ajouter. Ne décidez pas de votre propre initiative d'activer un produit Datadog ou une feature SDK supplémentaire au-delà de ce que cette skill spécifie.
• Persistez les dépendances ajoutées dans le manifeste du déploiement. Tout package Datadog que vous ajoutez (ddtrace, dd-trace) doit être écrit dans le manifeste de dépendances que le déploiement/la construction installe — celui identifié en Phase 1e — et non seulement installé dans l'environnement local. Une installation de déploiement propre ne lit que le manifeste et s'arrêtera avec une erreur de module manquant (ex : ModuleNotFoundError: No module named 'ddtrace') si le package n'y est pas déclaré.
• Ne faites pas de changements stylistiques au code que vous ne modifiez pas par ailleurs.
• Pas d'alias de package lors de l'importation de packages Datadog.
• Copiez verbatim les noms de packages SDK Datadog, les chemins d'import et les arguments mot-clé d'init de la section de référence applicable — ne les paraphrasez pas de mémoire. L'import Observabilité LLM Python est exactement from ddtrace.llmobs import LLMObs — le module est ddtrace.llmobs, pas ddtrace.llm_observability (ce module n'existe pas et produit une ModuleNotFoundError au déploiement). Le package Node est dd-trace, initialisé avec la forme qui correspond au projet : CommonJS require('dd-trace').init(...), une forme basée sur import ESM pour les projets "type": "module"/.mjs, ou le dd-trace/initialize.mjs de Next.js dans instrumentation.ts — tous affichés dans references/llmobs-nodejs.md ; ne forcez jamais require(...) dans un projet ESM. Utilisez les arguments mot-clé LLMObs.enable(...) / .init({...}) exactement tels que montrés ; n'ajoutez, ne supprimez ni ne renommez les kwargs d'après des connaissances Datadog générales.
• Utilisez un vrai outil d'édition pour les fichiers existants (Edit/Write, pas sed -i, awk, ou find/replace scriptée via Bash). Si une édition par correspondance de texte échoue, relisez d'abord le fichier plutôt que de réessayer l'édition identique.
• Discipline de checklist. Avant de commencer les étapes d'instrumentation, postez une courte checklist des étapes que vous êtes sur le point de prendre. Cochez les éléments au fur et à mesure, et revoyez la checklist à la fin de la course.
• Après tout changement de code, vérifiez package.json pour un script lint:fix, fix, ou format (ou config eslint --fix / prettier --write) et exécutez-le automatiquement — pas besoin de demander la permission.
• Vérifiez que l'app se construit/s'exécute toujours avant de déclarer le succès (voir references/common-verify-report.md).
• Les IDs de session Observabilité LLM se propagent uniquement depuis le span racine. Ne passez jamais un ID de session à un span/décorateur enfant — voir la section « Adding spans » dans references/llmobs-python.md / references/llmobs-nodejs.md.
• Ne promettez pas ce que l'environnement ne supporte pas. Si aucun SDK RUM n'est détecté, ne revendiquez pas la liaison de session RUM ; si aucun dd-agent n'est détecté, ne revendiquez pas la liaison de trace APM navigable. Énoncez l'écart et le chemin de mise à niveau plutôt (voir la section « Beyond SDK init » dans les fichiers de référence).

Phase 1 : Analyse

Inspectez le répertoire d'application pertinent avant de poser des questions ou de modifier des fichiers.

1a. Détection du runtime LLM/agent backend

• Signaux Python : requirements.txt, pyproject.toml, Pipfile, ou fichiers *.py → runtime python
• Signaux Node.js : un point d'entrée backend (server.js, index.js, une app Express/Next.js/Fastify) → runtime nodejs
• Si les deux existent (ex : une app Next.js avec un worker Python), instrumentez chaque runtime backend indépendamment.
• Si aucun n'est présent, il n'y a rien à instrumenter — arrêtez et informez l'utilisateur.

1b. Détection du framework/SDK LLM (optionnel, informatif)

Vérifiez les fichiers de dépendances pour les signaux de : openai, @anthropic-ai/sdk / anthropic, langchain, langgraph, ai (Vercel AI SDK), boto3 + utilisation Bedrock, google-generativeai / google-genai, crewai, litellm, pydantic-ai, un SDK MCP, google-adk. Cela ne change pas le code d'init (ddtrace/dd-trace auto-instrumentent ces SDKs une fois que le tracer est initialisé) — c'est utilisé uniquement pour confirmer la configuration avec l'utilisateur et pour les frameworks à cas particulier notés dans les fichiers de référence (Next.js, Vercel AI SDK).

1c. Détection du framework d'application backend

• Python : dépendance fastapi, flask, ou django
• Node.js : dépendance express, ou next (routes API Next.js / server actions)

1d. Détection de l'instrumentation existante et audit du câblage d'ID de session

• Grep pour l'init ddtrace (LLMObs.enable(, ddtrace-run) en Python, ou l'init dd-trace (require('dd-trace').init(, dd-trace/initialize) en Node.js.
• Vérifiez également un SDK RUM frontend (datadogRum.init(, @datadog/browser-rum) — non pour le configurer, mais parce que sa présence détermine si le pivot opt-in RUM↔LLMObs est disponible (ce pivot réutilise l'ID de session RUM comme ID de session LLMObs).
• Si l'init LLMObs est déjà présent, n'ajoutez pas un deuxième appel enable/init — mais ne vous arrêtez pas là. La présence du SDK signifie uniquement « ne pas réinitialiser » ; cela ne dit rien sur le fait qu'un ID de session circule réellement. Exécutez cet audit chaque fois que ses surfaces préalables apparaissent :
  • Câblage d'ID de session — applicable chaque fois que la Phase 1a a trouvé un backend LLM/agent. Vérifiez si un ID de session stable, d'envergure conversation/opération, circule à partir de la source appropriée : pour les apps web, le frontend envoie un ID par conversation et le modèle/route de requête backend le lit ; pour les jobs CLI/background, le backend réutilise un ID job/requête/tâche existant ou en émet un UUID par invocation. Un span racine agent/workflow doit alors le définir comme session_id/sessionId (voir « Beyond SDK init » et « Session ID intake by environment » dans references/llmobs-python.md / references/llmobs-nodejs.md). LLMObs.enable()/dd-trace().init() seul ne l'établit pas. Si un SDK RUM est aussi présent, le pivot RUM↔LLMObs est disponible comme opt-in — réutilisant l'ID de session RUM comme session_id — mais c'est un compromis délibéré (la session LLMObs s'étend alors à la session navigateur entière), pas le défaut ; ne signalez pas son absence comme un écart.
  • Si la vérification trouve un écart, dites à l'utilisateur ce qui manque et corrigez-le (mêmes fichiers de référence, mêmes règles de base) même si le SDK lui-même n'a pas besoin de réinit. S'il passe, dites-le explicitement. Notez le pivot RUM comme non applicable plutôt qu'un écart quand il n'y a pas de SDK RUM.

1e. Détection du manifeste de dépendances à persister

Pour chaque runtime backend trouvé en 1a, identifiez le manifeste de dépendances que le déploiement/la construction installe réellement à partir de. C'est là que tout package Datadog que vous ajoutez (ddtrace/dd-trace) doit être persisté pour qu'une installation de déploiement propre l'inclue. Ce n'est pas nécessairement « quel fichier manifeste se trouve être présent » : un repo peut en avoir plusieurs (ex : un requirements.txt vide à côté d'un pyproject.toml, ou plusieurs package.json où seul un est l'espace de travail déployé), et éditer un non-autorisé est un non-op silencieux au déploiement.

Résolvez-le dans cet ordre :

1. Commande d'installation de déploiement/construction d'abord (autoritaire). Lisez la configuration de déploiement/construction du projet et utilisez la source d'installation qu'elle nomme : render.yaml (buildCommand), Procfile, Dockerfile (RUN … install …), Makefile, workflows CI, scripts package.json. Exemples : pip install -r <file> → ce fichier requirements ; poetry install / uv sync / pdm install → pyproject.toml (+ son lockfile) ; pipenv install → Pipfile ; npm ci / yarn install / pnpm i → package.json.
2. Sinon, le manifeste de priorité la plus élevée présent. Python : un gestionnaire soutenu par lockfile (uv.lock ou poetry.lock → pyproject.toml) > pyproject.toml [project.dependencies]/[tool.poetry.dependencies] > requirements*.txt > Pipfile > setup.py/setup.cfg. Node.js : package.json (toujours).

Enregistrez le chemin du manifeste et le gestionnaire qui le possède. Les commandes de persistance (poetry add, uv add, pdm add, pipenv install, npm/yarn/pnpm/bun add) écrivent le manifeste. Les commandes non-persistantes (pip install, uv pip install, conda install) ne modifient que l'environnement actuel — avec celles-ci vous devez aussi aussi éditer manuellement le manifeste. Si requirements.txt est généré à partir d'un requirements.in (pip-tools), éditez le .in et recompliez. Après avoir édité manuellement un manifeste qui a un lockfile, régénérez le verrou pour qu'une installation de déploiement gelée récupère le nouveau package.

Phase 2 : Instrumentation — table de routage

Provisionnez DD_API_KEY via references/common-credentials.md, puis suivez la référence pour chaque runtime backend trouvé en Phase 1a :

Si la Phase 1d a trouvé une instrumentation LLMObs existante sur un runtime, sautez uniquement l'appel init/enable et le provisionnement de credentials de ce runtime — agissez toujours sur tout écart que l'audit de câblage d'ID de session de Phase 1d a trouvé, en utilisant les mêmes fichiers de référence.

Phase 3 : Vérification et Rapport

Voir references/common-verify-report.md pour l'étape de vérification et la forme du rapport JSON.