agent-observability-replay-trace

Этот навык Datadog Labs предназначен для итерации над одним конкретным trace из Agent Observability или LLM Observability, если разработчику не понравился его результат. Он не ставит общий диагноз по всем сбоям и не является кнопкой браузерного Replay: его задача — взять идентификатор одного trace, выполнить тот же вход на локальном коде и показать компактную разницу между исходным и новым результатом. Такой режим подходит для проверки исправления, воспроизведения регрессии и последовательного цикла «изменить код → повторить trace → сравнить вывод». Без изменения кода навык может выполнить только воспроизведение и сравнение, после чего предложить продолжить итерацию. Работа начинается с определения trace-id и, при необходимости, описания изменения. Нужен backend доступа к трассам: предпочтительно datadog-llmo MCP, а при его отсутствии — CLI pup с настроенной авторизацией. Если ни одного backend нет, workflow должен остановиться, а не имитировать результат. Источник входа может содержать metadata.replay_input и metadata.replay_entrypoint; если их нет, entrypoint и JSON-сериализуемый input выводятся из корневого span и сигнатуры кода, причём неоднозначный вариант необходимо подтвердить. Навык ориентирован на приложения с ddtrace или LLM Observability и доступным вызываемым entrypoint; Python поддерживается как первый класс, а для других языков runner должен соответствовать контракту проекта. Перед запуском нужно найти самый внутренний вызываемый seam корневого span. Если бизнес-логика уже представлена обычной функцией, не требуется поднимать весь сервис; если она скрыта за handler или зависимостью от deployed-only окружения, сначала подготавливается локальный путь запуска по отдельной инструкции. Для будущих replay в настоящем entrypoint добавляется минимальная аннотация с устойчивым идентификатором entrypoint и извлекателем replay_input. Аннотация ставится в начале span, чтобы вход оставался доступен и у неуспешного запуска. Сам результат в исходный trace не записывается: он используется как baseline для сравнения. Безопасность изоляции является частью workflow. Runner загружает окружение, получает имя приложения и обязан запускать его только с ml_app, заканчивающимся на -local; он также должен печатать это имя, отправлять один JSON-вход, сбрасывать telemetry на каждом пути выхода и отказываться стартовать без локального суффикса. До replay проверяются overrides ml_app на уровне отдельных span и очищаются случайные ключи провайдеров, которые могут обойти настроенный gateway. Для доступа к Datadog нужны DD_API_KEY и DD_SITE, а DD_APP_KEY относится к другому сценарию Experiments. Первый replay требует предупреждения: повторный запуск действительно выполняет код, может расходовать средства модели и совершать реальные записи. Trace Observability нельзя удалить, поэтому ошибочный ml_app или неверный scope необратимо загрязняет production-дашборды; replay должен попадать только в изолированное локальное приложение. Если корневой trace разветвляется на много одинаковых ветвей, обычно достаточно выбрать одну представительскую ветвь, которая дошла до terminal или side-effecting tool. Это уменьшает стоимость и не скрывает проверяемую разницу за шумом остальных no-op ветвей; вход восстанавливается из дочернего span, а не автоматически берётся из root. Для сравнения фиксируются старый trace URL и новый локальный trace URL, длительность помогает определить окно ожидания, а после завершения runner новый trace ищется по replay_run_id. Одного совпадения тега недостаточно: фактический ml_app каждого найденного span проверяется отдельно, и trace под production app не считается успешным replay. Если trace не найден, сначала выполняется поиск без tag-фильтра, чтобы отличить задержку ingest от ошибочного запроса. Навык предполагает два явных пользовательских решения: перед первым replay подтвердить предложенные изменения, а после каждого diff выбрать остановку или следующую правку. Автоматические изменения после отчёта не выполняются без такого решения. В diff сравниваются только значимые поля, а для недетерминированных агентов рекомендуется два локальных запуска и сравнение replay с replay: если их разброс сопоставим с разницей относительно production, изменение нельзя уверенно приписать исправлению. Side-effecting интеграцию, отключённую в dry-run, нельзя трактовать как структурную разницу. При неправильном ml_app, отсутствии flush, ошибочной авторизации или отсутствующем trace workflow останавливает diff и сначала исправляет harness. Ограничения также включают зависимость от разрешений Datadog, доступности metadata и содержимого span, корректной локальной callable-точки и JSON-сериализуемого входа; отсутствие messages, documents, metadata или дочерних span уменьшает детализацию, но не даёт права выдумывать результат.