agent-observability-trace-rca

Agent Observability Trace RCA — официальный навык Datadog Labs для разбора того, почему LLM-приложение или AI-агент работает неправильно. Он ищет проблему в production LLM traces и проходит по дереву span от наблюдаемого симптома к месту, где возникло решение или данные, приведшие к сбою. В качестве сигнала могут использоваться вердикты LLM-evaluator, сообщения и стеки runtime-ошибок, а также структурные аномалии: необычная задержка, длинный цикл агента, пустой результат retrieval или пропущенный этап workflow. Поэтому карточка описывает не универсальный совет по отладке, а конкретный маршрут исследования трассировки. Режим анализа выбирается по доступным сигналам. Если для приложения настроены evaluators, навык использует Eval Signal: рассматривает pass/fail, значения оценок, reasoning судьи и конфигурацию evaluator. Если evaluator недоступен, присутствуют ошибки или пользователь явно просит разобрать ошибки и падения, используется Error Signal: собираются тип ошибки, сообщение, stack trace и контекст распространения по соседним и дочерним span. Generic Signal предназначен для структурных отклонений, когда сильного eval- или error-сигнала нет, либо когда явно выбран generic mode. Выбранный режим объявляется в начале результата и может быть заменён явным указанием режима. Основной вход — имя приложения "ml_app"; вместо него можно передать "eval_name", а список evaluator позволяет сосредоточиться на нескольких оценках. По умолчанию рассматривается период "now-24h", но timeframe можно сузить или расширить. Параметр "failure_filter" ограничивает поиск ошибками, высокой задержкой, низкими оценками конкретного evaluator, именем инструмента или span. Доступны явные режимы "eval", "errors" и "generic". Такой набор входов помогает отделить вопрос о качестве ответа от вопроса о сбое выполнения и не смешивать разные временные окна. Рабочий процесс начинается с разрешения входов и выбора режима, затем переходит к поиску проблемных span, определению профиля приложения, открытой и осевой классификации отказов, навигации по trace tree и подготовке рекомендаций. Для обзора evaluators используются обнаружение, агрегированная статистика и полная конфигурация evaluator. Для трасс применяются поиск span с фильтрами, получение деталей и содержимого, чтение полной иерархии, поиск error span, раскрытие свернутых дочерних узлов и, когда это возможно, хронология agent loop. Содержимое можно извлекать адресно: первое сообщение часто содержит system prompt, последнее — ответ ассистента, а отдельные поля input, output, documents и metadata позволяют проверить контекст, retrieval и пользовательские метаданные. При поиске span важно передавать @ml_app:"<ml_app>" прямо в query: исходник отдельно предупреждает, что структурный параметр ml_app ненадёжен и сам по себе может вернуть трассы другого приложения. Для наличия ошибки используется "@status:error"; наличие evaluator в индексе проверяется отдельным условием, но pass/fail читается из деталей span. Результаты поиска пагинируются. Детали группируются по trace, а содержимое независимых span можно получать параллельно. Если agent loop пуст, последовательность восстанавливается по дочерним span и времени запуска, поэтому пустой ответ этого метода не считается доказательством отсутствия действий агента. Главное правило RCA — сигнал указывает на симптом, а не обязательно на первопричину. Для LLM-span нужно смотреть system prompt и полный контекст, соседний retrieval, вход соседнего tool и инструкции родительского agent или workflow. Для agent-span проверяется timeline и дочерние решения; для tool-span — параметры вызова и сообщения родительского LLM; для workflow — первый отклонившийся дочерний шаг. В результате причина может быть в неполной или противоречивой инструкции, отсутствующем инструменте, неправильном выборе или параметрах инструмента, ошибке routing или handoff, нерелевантном retrieval, переполнении контекста, плохих upstream-данных, timeout или другой runtime-ошибке. В Eval Signal отдельно проверяется, не создаёт ли сам evaluator ложные срабатывания из-за слишком строгих или неоднозначных критериев. Рекомендации должны опираться на найденные trace evidence: возможны правка system prompt с конкретным before/after, исправление tool gap или misuse, корректировка routing, retrieval или evaluator. При наличии доступа к кодовой базе навык может найти prompt, определения инструментов и routing-логику, но перед изменением файлов он должен запросить подтверждение. Полный отчёт является основным результатом и включает сигнал, классификацию отказов, trace-контекст, вероятную точку возникновения и следующие действия. Автоматические изменения после отчёта не выполняются. Для запуска нужен один из предусмотренных backend: активные Datadog LLM Observability MCP-инструменты или доступный CLI "pup"; флаг "--backend pup" принудительно выбирает CLI. При отсутствии обоих способов навык должен остановиться, а не имитировать диагноз. Доступ к данным также ограничен правами и аутентификацией Datadog, а вывод зависит от того, какие поля trace действительно доступны. Поэтому отсутствие messages, documents, metadata, дочерних span или agent-loop снижает детализацию и требует использовать оставшиеся span details. Структурная аномалия, evaluator-оценка или статус ошибки сами по себе не доказывают причинность: связь подтверждается только сопоставлением симптома с родительскими, соседними и дочерними span.