Eval RCA — Root Cause Analysis from Production Trace Signal

Effectuez une analyse structurée des causes premières sur les traces LLM de production. Supporte deux modes selon le signal disponible :

Si le mode ne peut pas être déduit du contexte, posez une seule question de clarification avant de procéder : « Voulez-vous que j'analyse les patterns de pass/fail des évals, ou que j'examine les erreurs runtime et exceptions dans les traces ? »

Méthodologie

Contexte → Observer → Open Coding → Axial Coding → Root Cause Analysis → Recommandations

Utilisation

What's wrong with <ml_app> based on its evals over the last <timeframe>
Analyze eval failures for <eval_name> over the last <timeframe>
Look at the errors on <ml_app> over the last <timeframe>

Entrées

Soit ml_app, soit eval_name doit être fourni. Si aucun n'est donné, demandez à l'utilisateur.

Outils Disponibles

Découverte & Aperçu des Evals

Exploration des Traces & Spans

Patterns clés de get_llmobs_span_content

Utilisez le param path pour extraire des données ciblées sans chercher les payloads complets :

Comment utiliser search_llmobs_spans

Pattern de requête principal — présence d'eval :

@evaluations.custom.<eval_name>:*

Vous pouvez uniquement chercher la présence d'eval, pas des résultats spécifiques (ex., @evaluation_assessments.custom.<name>:fail ne fonctionnera PAS). Pour déterminer pass vs fail, lisez le verdict depuis get_llmobs_span_details.

Les filtres additionnels se combinent avec espace (AND) : @evaluations.custom.<name>:* @status:ok. Les params dédiés (span_kind, root_spans_only, ml_app) fonctionnent aux côtés de query, mais query prend la précédence sur tags.

Règles de Parallélisation

1. get_llmobs_span_details : Groupez span_ids par trace_id. Un appel par trace_id avec TOUS ses span_ids. Lancez TOUS les appels pour une page dans un seul message.
2. get_llmobs_span_content : Chaque appel est indépendant — toujours lancer TOUS dans un seul message.
3. get_llmobs_trace / find_llmobs_error_spans / get_llmobs_agent_loop : Parallélisez across différentes traces dans un seul message.
4. Pipeline parallelism : Lancez get_llmobs_span_details pour les résultats de la page 1 immédiatement — ne pas attendre de collecter toutes les pages.

Workflow d'Analyse

Discipline de sortie : Les phases 0–5 sont des analyses internes. Les seules sorties visibles par l'utilisateur pendant ces phases sont les brèves mises à jour de checkpoint (Phases 2, 3) et l'Aperçu des Evals (Phase 1a). Ne NARREZ PAS votre raisonnement, ne résumez PAS les découvertes intermédiaires, et ne produisez PAS les résultats de deep-dive Phase 4 en prose. Tous les découvertes détaillées vont exclusivement dans le rapport Phase 6.

Phase 0 : Résoudre les Entrées & Mode

1. Si ni ml_app ni eval_name fourni → demandez à l'utilisateur.
2. Si timeframe pas fourni → défaut now-24h.
3. Résoudre le mode :
   • eval_name fourni → Eval Signal. Procédez à Phase 1 pour l'eval spécifié.
   • L'utilisateur mentionne explicitement les erreurs, exceptions, crashes, défaillances runtime, ou « regarder les erreurs » → Error Signal.
   • ml_app fourni, pas de signal explicite → appelez list_llmobs_evals(ml_app) :
     • Evals existent → Eval Signal (défaut). Obtenez les stats agrégées pour chaque eval en parallèle.
     • Pas d'evals configurés → Error Signal automatiquement ; informez l'utilisateur.
     • Evals existent mais contexte ambigu → posez une question : « Voulez-vous que j'analyse les patterns de pass/fail des evals, ou que j'examine les erreurs runtime et exceptions dans les traces ? »
4. Notez tout filtre additionnel (tags, span_kind) pour toutes les requêtes suivantes.

Phase 1 : Rassembler le Contexte & Collecter les Preuves

Objectif : Obtenir la vue d'ensemble, échantillonner les spans en défaut, et déterminer le profil de l'app.

Si mode = Error Signal, remplacez les Étapes 1a–1b ci-dessous par le chemin Error Signal :

Étape 1a (Error Signal) : Échantillonner les error spans Appelez search_llmobs_spans(query="@ml_app:{ml_app} @status:error", from=timeframe, limit=50). Paginez jusqu'à ≥ 30 error spans ou pas plus de pages. Groupez les spans par tag error_type pour construire une table de fréquence initiale. Rapportez : Trouvé {N} error spans across {K} types d'erreur distincts : {type1} ({count}), {type2} ({count}), ...

Étape 1b (Error Signal) : Récupérer les stack traces par type d'erreur Pour les 3–4 types d'erreur principaux, sélectionnez 2–3 trace IDs représentatifs et appelez find_llmobs_error_spans(trace_id) en parallèle. Extrayez le message d'erreur, la stack trace, et le span kind/name où l'erreur a commencé. Notez si les erreurs se propagent des enfants aux parents (cascade vs. isolée).

Étape 1c (Error Signal) : Déterminer le profil d'app Inspectez les noms de spans, kinds, et tags des error spans pour comprendre la structure de l'app (identique à Eval Signal Étape 1c). Puis procédez à Phase 2 (Open Coding) en traitant chaque pattern d'erreur distinct comme une catégorie de défaut — le error_type + span d'origine + condition déclenchante est l'équivalent du « raisonnement du juge ».

Le Output Format du mode Error Signal utilise la même structure mais remplace Eval Overview / Judge reasoning par Error type counts / Stack trace excerpts.

Étape 1a : Aperçu des evals (parallèle)

Pour chaque eval analysé, appelez les deux en parallèle :

• get_llmobs_eval_aggregate_stats(eval_name, from, to)
• get_llmobs_eval_config(eval_name)

Quand vous analysez plusieurs evals (entrée ml_app), lancez TOUS les appels pour tous les evals dans un seul batch parallèle.

Interprétez les stats agrégées :

• total_count == 0 → Notez « pas de données ». Sautez cet eval.
• Boolean avec pass_rate == 1.0 → Notez « 100% pass ». Sautez sauf si c'est le seul eval.
• Boolean avec défauts → Notez les décomptes et pass_rate. Continuez.
• Score eval avec critères d'évaluation → Notez la distribution et les décomptes pass/fail. Continuez.
• Score eval SANS critères d'évaluation → Analysez quand même. Utilisez la distribution des scores pour identifier les low-performers : traitez le quartile inférieur comme « défauts », ou les scores sous la médiane si la distribution est bimodale. Notez que le seuil est inféré, pas configuré.
• Categorical avec critères d'évaluation → Notez top_values et pass/fail. Continuez.
• Categorical SANS critères d'évaluation → Analysez quand même. Examinez la distribution des valeurs. Demandez à l'utilisateur quelles catégories représentent les défauts si ambigu, ou déduisez du contexte (ex., « error », « incomplete », « off_topic » sont probablement des défauts).

Interprétez eval config :

• Config retournée (custom/BYOP) → Stockez prompt_template, assessment_criteria, parsing_type, output_schema.
• Config nil (OOTB) → Notez que le prompt n'est pas inspectable.

Rapportez à l'utilisateur :

## Eval Overview: `{eval_name}`

**Timeframe**: {from} → {to}  |  **Type**: {boolean/score/categorical}  |  **Eval**: {Custom/OOTB}
**Total spans**: {total_count}  |  **Pass rate**: {pass_rate}% ({pass_count}/{fail_count})
{Si pas de critères d'évaluation : **Note**: No pass/fail criteria configured. Using inferred threshold: {threshold_description}.}

{Si custom : résumé en 1-2 phrases de ce que l'eval mesure.}

Quand plusieurs evals sont analysés, présentez d'abord une table d'aperçu combinée :

## Eval Overview: `{ml_app}`

| Eval | Type | Total | Pass Rate | Status |
|------|------|------:|:---------:|--------|
| eval_1 | boolean | 4,891 | 37,3% | ⚠ Investigating |
| eval_2 | score | 1,200 | — (no criteria) | ⚠ Investigating (inferred threshold) |
| eval_3 | boolean | 500 | 99,2% | ✓ Healthy |

Étape 1b : Collecter les spans en défaut

Pour chaque eval analysé :

1. search_llmobs_spans(query="@evaluations.custom.<eval_name>:*", from, limit=50) + filtres utilisateur.

   • Paginez jusqu'à ≥15–20 défauts OU pas plus de pages. Plafonner à 200 spans total par eval.

2. get_llmobs_span_details par batch trace_id (suivez les Règles de Parallélisation).

   • Extrayez : assessment, value, reasoning, span_id, trace_id, span_kind, content_info.

3. Séparez en buckets pass/fail.

   • Avec critères d'évaluation : Utilisez le seuil pass/fail configuré.
   • Sans critères d'évaluation : Utilisez le seuil inféré de l'Étape 1a (quartile inférieur pour les scores, catégories déduites pour categorical). Labelisez-les comme « inferred failures » dans le rapport.

4. Rapportez : Collecté {N} spans pour {eval_name} : {pass_count} réussis, {fail_count} échoués.

5. Cas limites : 0 défaut dans l'échantillon → essayez une slice temporelle différente. < 10 défauts → procédez, notez faible confiance.

Étape 1c : Déterminer le Profil d'App & Étendue d'Eval

Inspectez content_info et span_kind dans les spans collectés. Cela guide la stratégie d'investigation Phase 4.

Profil d'app (depuis content_info) :

Span kind évalué — détermine où vit probablement la cause première :

Insight clé : L'eval juge un span unique isolément. Le raisonnement du juge est un rapport de symptôme, pas un diagnostic. La cause première vit souvent dans un span différent de la même trace — un parent qui a donné des mauvaises instructions, un sibling qui a fourni un mauvais contexte, ou un child qui a pris une mauvaise décision. Phase 4 doit naviguer l'arbre des traces pour la trouver.

Phase 2 : Open Coding — Catégorisation Initiale des Défauts

Objectif : Lire la preuve de défaut et proposer des catégories de défaut initiales, concrètes. Quand vous analysez plusieurs evals, mettez en commun tous les défauts ensemble — les catégories doivent décrire les comportements d'app, pas quel eval les a attrapés. Notez quel(s) eval(s) a signalé chaque catégorie.

Raccourcis :

• < 15 défauts : Combinez Phases 2 et 3 en un seul passage. Produisez quand même la sortie de checkpoint.
• > 80% partagent le même raisonnement : Passez à Phase 4 avec pattern dominant. Produisez quand même le checkpoint.
• > 50 défauts : Échantillonnez ~50, construisez la taxonomie, puis vérifiez spot 10–15 de plus.

1. Utilisez le raisonnement de l'Étape 1b — ne recalculez PAS.

   • Appelez seulement get_span_content(field="input"/"output") pour les spans où le raisonnement est insuffisant (générique ou vide).

2. Si eval config chargée, distinguez tôt :

   • App failures : La sortie viole vraiment les critères de l'eval
   • Eval failures : La sortie semble raisonnable mais les critères d'eval sont trop stricts/ambigus

3. Chaque pattern doit être spécifique : « Agent a appelé search au lieu de calculator pour calcul de prix » — PAS « problème d'outil ».

MANDATORY CHECKPOINT — Brève Mise à Jour de Progression

Vous DEVEZ afficher un bref résumé avant de procéder. Gardez-le court — le rapport complet en Phase 6 est le vrai livrable. Pas de descriptions ou d'exemples ici.

**Open coding** : {N} défauts → {K} catégories initiales : {Category1} ({count}), {Category2} ({count}), ...

Phase 3 : Axial Coding — Affiner la Taxonomie des Défauts

Objectif : 3–8 catégories finales, classées par impact.

1. Fusionner : Catégories avec < 3 occurrences → catégorie parent ou supprimer comme bruit.
2. Scinder : Catégories avec > 30% des défauts → sous-catégories plus spécifiques. Tirez du contenu de span additionnel si nécessaire.
3. Valider : 2–3 exemples représentatifs par catégorie confirment que le label convient.
4. Classer : priority = count × severity (severity : high / medium / low).

MANDATORY CHECKPOINT — Brève Mise à Jour de Progression

Vous DEVEZ afficher la taxonomie affinée avant de procéder. Gardez-le court — montrez ce qui a changé et la liste classée. Les détails vont dans le rapport final.

**Axial coding** : {merges/splits/drops}. Catégories finales :
1. {Category} ({count}, {pct}%) — {severity}
2. ...

Phase 4 : Root Cause Analysis — Naviguer du Symptôme à la Cause Première

Objectif : L'eval a signalé un span. C'est le symptôme. Trouvez maintenant la cause première réelle en naviguant l'arbre des traces — elle est souvent dans un span différent.

Pour chacune des 3 principales catégories, choisissez 2–3 traces représentatives :

Étape 4a : Structure de trace + erreurs (parallèle)

Pour chaque trace représentative, appelez dans un seul message :

• get_trace(trace_id) — obtenez la hiérarchie des spans ; localisez le span évalué et son parent/siblings/children
• find_error_spans(trace_id) — vérifiez les erreurs runtime partout dans la trace

Runtime vs comportemental : Si find_llmobs_error_spans retourne des erreurs sur le span évalué ou sur des spans proches, la cause première peut être une défaillance runtime (timeout, erreur API) plutôt qu'une défaillance comportementale. Vérifiez d'abord.

Étape 4b : Naviguer vers la cause première (parallèle)

Utilisez le span kind évalué (de l'Étape 1c) pour décider où regarder. Lancez TOUS les appels dans un seul message.

Si eval est sur un span llm (plus courant) :

• get_span_content(field="messages", path="$.messages[0]") sur le span évalué — obtenez son system prompt
• get_span_content(field="messages") sur le span évalué — vérifiez quel contexte il a reçu
• get_span_content(field="documents") sur les spans retrieval siblings (s'il y en a) — le contexte récupéré était-il pertinent ?
• get_span_content(field="input") sur les spans tool siblings (s'il y en a) — les outils ont-ils fourni de bonnes données ?
• get_span_content(field="messages", path="$.messages[0]") sur le span agent/workflow parent — le parent a-t-il donné des instructions claires ?

Si eval est sur un span agent :

• get_agent_loop(trace_id, span_id) — timeline de décision complète
• get_llmobs_span_details sur les child spans — quels appels d'outils/LLM l'agent a-t-il faits ?
• get_span_content(field="input"/"output") sur les child spans qui semblent mauvais — qu'est-ce qui a déraillé ?

Si eval est sur un span tool :

• get_span_content(field="input") sur le span évalué — avec quels paramètres a-t-il été appelé ?
• get_span_content(field="messages") sur le span LLM parent — le LLM a-t-il correctement construit l'appel ?

Si eval est sur un span workflow :

• get_llmobs_span_details sur les all child spans — trouvez quelle étape a d'abord dévié du comportement attendu
• get_span_content(field="input"/"output") sur le child déviant — qu'est-ce qui a mal tourné ?

Toujours aussi récupérer :

• get_span_content(field="metadata") sur le span évalué — vérifiez les signaux de clustering (version de prompt, feature flags)

Étape 4c : Diagnostiquer — du symptôme à la cause première

Pour chaque catégorie, tracez la chaîne causale :

1. Symptôme — ce que le juge a signalé (raisonnement de l'Étape 1b). Rappelez-vous : le juge n'a vu qu'un seul span d'entrée/sortie, donc son raisonnement peut être superficiel.
2. Contexte de trace — ce que les spans environnants révèlent (instructions du parent, données de sibling, décisions de child)
3. Cause première — le span spécifique et le point de décision où la défaillance a commencé. Ce n'est souvent PAS le span évalué lui-même.

Pour défaillances d'eval supposées (si config chargée) : Comparez les critères de l'eval contre la preuve. Le prompt est-il ambigu ? Critères trop stricts ?

Catégories de causes premières :

Phase 5 : Générer les Recommandations

Objectif : Recommandations concrètes, actionnables ancrées dans la preuve de trace. Pas de conseils génériques — des changements de texte/code réels avec citations avant/après depuis la trace.

Types de recommandations : System Prompt Edit (citez le prompt réel, fournissez avant/après), Tool Gap/Misuse (référencez les étapes de la boucle d'agent), Routing/Handoff Fix, Retrieval Fix (montrez récupéré vs nécessaire), Evaluator Prompt Edit (signalez que les changements d'eval nécessitent une re-validation), Other.

Quand exécuté dans Claude Code avec accès codebase : Cherchez le codebase pour le system prompt, les définitions d'outils, ou la logique de routage. Proposez des diffs spécifiques. Toujours demander avant de modifier les fichiers.

Phase 6 : Compiler le Rapport RCA

Écrivez le rapport complet en suivant le Output Format ci-dessous. C'est le livrable principal — affichez-le directement dans le chat.

Phase 7 : Actions Post-Analyse

Ne prenez AUCUNE action automatiquement. Après avoir présenté le rapport, demandez à l'utilisateur ce qu'il aimerait faire ensuite. Suggérez des options :

1. Sauvegarder le rapport en eval-rca-{eval_name}-{date}.md
2. Appliquer les corrections (si codebase disponible)
3. Investigation plus approfondie des catégories restantes
4. Exporter le rapport vers un notebook Datadog
5. Exécuter sur une plage de temps étendue (re-lancer l'analyse complète de Phase 1 avec une timeframe plus large, ex. now-7d si la fenêtre actuelle était now-24h)

Si l'utilisateur choisit l'option 4, appelez mcp__datadog-mcp-core__create_datadog_notebook avec :

• name : Eval RCA: {eval_name or ml_app} — YYYY-MM-DD
• type : report
• time_span : 1w
• cells : une cell par section (voir Notebook Cell Structure ci-dessous) — ne mettez PAS le rapport entier dans une seule cell

Après création, affichez l'URL sur sa propre ligne : RCA report exported to notebook: <url>

Affichez l'URL en évidence — si /eval-bootstrap s'exécute ensuite dans la même session, il détectera cette URL et proposera d'ajouter la suite d'évaluateurs au même notebook.

Notebook Cell Structure

Divisez le rapport en cells séparées — une par section majeure. Cela s'affiche beaucoup mieux qu'une seule cell grande.

Cell 1 — Overview

**Date**: YYYY-MM-DD | **Timeframe**: {from} → {to} | **App**: {ml_app} | **Signal**: {Eval | Error}
**App profile**: {description}

{Résumé exécutif en 2-3 phrases}

Cell 2 — Error/Eval Health Summary (table)

Cell 3 — Failure Taxonomy (table)

Cells 4…N — une cell par Failure Mode

Cell N+1 — Prioritized Action Plan + Limitations

Règles de formatage des notebooks (appliquez à chaque cell) :

• Pas de blocs de code triple-backtick — ils se rendent sous forme de blocs de texte brut séparés dans les notebooks Datadog. Utilisez blockquotes (>) pour les prompts/rubrics, et code inline (`) pour les courtes valeurs.
• Preuve comme tables — pas de listes à puces. Voir Output Format.
• Entrées d'outils comme tables — Argument | Valeur passée (mauvaise) | Approche correcte.
• Plan d'action comme table — Priority | Action | Confidence | Impact.

Output Format

Le rapport en-chat (Phase 6) et l'export notebook (Phase 7) utilisent la même structure. Les différences sont notées en ligne.

En-tête

# Eval RCA Report: `{eval_name or ml_app}`

**Date**: YYYY-MM-DD | **Timeframe**: {from} → {to} | **App**: {ml_app} | **Signal**: {Eval | Error}
**App profile**: {LLM | RAG | Agent | Multi-agent, avec brève description}

{Résumé exécutif en 2-3 phrases : santé globale, découverte la plus importante avec chiffres.}

Error / Eval Health Summary

Table — une ligne par type d'erreur ou eval :

| Error Type | Spans | Traces | Versions Affected | Status |
|---|:---:|:---:|---|:---:|
| `monitor_groups_search` 400 | ~21 | 4+ | All | ⚠️ Active |
| `CancelledError` | ~25 | 12+ | All | ⚠️ Active |
| `load_datadog_skill` | ~7 | 7 | v1.0–v1.3 only | ✅ Resolved |

Failure Taxonomy

| # | Failure Mode | Traces | % | Severity | Root Cause |
|---|---|:---:|:---:|:---:|---|
| 1 | Short description | 4+ | ~20% | **High** | Tool Misuse |

Failure Mode Sections (une par mode)

## Failure Mode N: [Name]

**Count**: {n} spans, {t} traces | **Severity**: High/Medium/Low | **Root Cause**: [Category]

[3-5 phrases : qu'est-ce qui va mal, quand, ce qui le déclenche, la chaîne causale.]

**Evidence**

| Trace | Behavior | Version |
|---|---|---|
| [69de86a7...](https://app.datadoghq.com/llm/traces?query=trace_id:{full_id}) | 7 parallel calls, all 400 | v107624932 |
| [69de473f...](https://app.datadoghq.com/llm/traces?query=trace_id:{full_id}) | 7x 400 + CancelledError after 153s | v107574104 |

{Pour tool misuse : ajoutez une table d'entrées d'outils}
**Tool inputs (100% des appels échantillonnés ont ce pattern)**

| Argument | Valeur passée (mauvaise) | Approche correcte |
|---|---|---|
| `query` | `"monitor_id:123 group_status:alert"` | `"monitor_id:123"` (name/tag seulement) |
| `group_states` | *(not passed)* | `["alert"]` (param séparé) |

{Pour eval signal : ajoutez le raisonnement du juge comme blockquote}
> "{cited judge reasoning}"

**Root cause**: [POURQUOI cela se produit, lié à la preuve de trace — span spécifique, paramètre, ou prompt.]

**Fix**: [Action concrète. Pour les changements de schéma/prompt, montrez avant/après en ligne — pas de blocs de code :
  BEFORE: query: string  # "Search query"
  AFTER: query: string  # Name/tag filters only — do not embed state filters here
         group_states: array[enum]  # ["alert", "warn", "no data", "ignored", "ok"]
]

**Impact**: Eliminates ~{n} spans/timeframe{; also describe secondary effects if any}.

Colonnes de la table Evidence — utilisez le sous-ensemble le plus informatif :

• Error Signal : Trace | Behavior | Version
• Eval Signal : Trace | Judge verdict | What the trace revealed
• Omettez toujours les colonnes qui n'ajoutent pas d'info pour un mode donné.

Prioritized Action Plan

Table — pas une liste numérotée :

| Priority | Action | Confidence | Impact |
|:---:|---|:---:|---|
| 1 | Fix `monitor_groups_search` schema — add `group_states` param | High | Eliminates ~21 spans/7d |
| 2 | Cap `max_retries` + handle `CancelledError` gracefully | High | Reduces retry storms |
| 3 | Upgrade pydantic-ai for cross-task cancel scope fix | Medium | Fixes ~8 spans/7d |

Limitations & Follow-ups

Liste à puces — inchangée par rapport à avant :

- **{Topic}** — {ce qui a besoin de plus de données ou d'actions de suivi}

Operating Rules

• Ancrez dans la preuve : Chaque affirmation référence les span IDs avec des liens de trace cliquables : [Trace {first_8}...](https://app.datadoghq.com/llm/traces?query=trace_id:{full_32_char_id}).
• Cause première plutôt que symptôme : « Le system prompt ne spécifie pas le format de date » pas « le modèle a donné la mauvaise réponse ».
• Montrez votre math : « 47 défauts (34%) » pas « beaucoup de défauts ».
• Honnête sur l'incertitude : < 5 exemples = provisoire. Signalez-le.
• Anonymisez les PII : Pas d'emails ou de noms. Les IDs utilisateurs/organisations sont ok.