OpenTelemetry для ИИ-сервиса: что добавить в трассировку до запуска агента

Обычная метрика «ответ занял шесть секунд» не объясняет, где именно потерялось время. Может быть, модель ждала долгий поиск, повторно вызывала функцию или получила слишком большой контекст. Подход OpenTelemetry помогает связать шаги распределённого запроса в трассу: от входа до внешнего инструмента и итогового ответа. Для ИИ-систем это полезно только тогда, когда разработчики заранее выбирают безопасные атрибуты и не превращают трассировку в хранилище пользовательских диалогов.

Что считать одним запуском

Начните с границ: входящий запрос — родительский span, обращение к модели — дочерний, поиск по базе — ещё один дочерний, а запись черновика — отдельное действие. Добавьте стабильный идентификатор запуска, среду, версию приложения и маршрут сценария. Тогда по одному ID можно увидеть, что поиск занял 4,8 секунды, модель — 1,2 секунды, а ошибка возникла при получении ответа от внешнего сервиса.

Для измерения полезны длительность, число попыток, тип инструмента, код завершения, приблизительный размер входа и выхода, а также версия модели, если она доступна и её допустимо хранить. Не обязательно сохранять исходный prompt. Вместо него может хватить шаблона, идентификатора набора инструкций и хеша очищенных параметров. Если требуется исследовать содержание, помещайте обезличенную копию в ограниченное хранилище с отдельным сроком жизни и журналом доступа.

Чем это отличается от счётчика запросов

Метрика показывает частоту или среднее, трасса — последовательность внутри конкретного запуска. Для владельца продукта важны p95 latency и доля ошибок, для инженера — какой span их вызвал, для отдела контроля — был ли человек до действия. Нельзя смешивать эти вопросы одним dashboard. Сперва выберите 3–5 решений, которые команда будет принимать по данным: например, убрать медленный ретрай, сузить область поиска или передать нестандартный запрос оператору.

Соберите несколько типовых прогонов и один намеренно ошибочный: пустой результат поиска, тайм-аут инструмента, отказ модели, повтор запроса и отклонённое подтверждение. При каждом сценарии трасса должна показать, где произошла остановка и не было ли после неё внешнего действия. Для воспроизводимой проверки журнала действий агента сохраните разделение между наблюдаемыми событиями и скрытым содержимым модели.

Как не превратить телеметрию в утечку

Самый опасный дефолт — писать в span полное содержимое prompt, ответа, документов и HTTP-заголовков. В них могут быть персональные сведения, коммерческая тайна, cookies и токены. Поставьте фильтр на уровне instrumentation до отправки данных в сборщик, проверьте исключения и аварийные сообщения, а затем протестируйте на искусственных секретах. Проверьте и downstream-копии: экспортер, резервная система, полнотекстовый индекс и доступ аналитиков.

Разделите роли. Дежурный инженер может видеть длительность и код сбоя, но не клиентский текст. Разработчику может понадобиться временный доступ к редактированному примеру по заявке. Не храните данные «на всякий случай». Установите срок, процедуру удаления и ответственного владельца. Порог семплирования тоже нужно продумать: редкий запуск может быть важнее массового успешного, поэтому для ошибок и опасных действий часто полезно сохранять более полные технические сведения — но всё ещё без секретов.

Чек-лист перед включением

Проверьте, что спаны связаны одним trace ID, значения таймингов записаны в одной временной зоне, а ошибки не маскируются успешным ответом родительского процесса. Убедитесь, что пользовательский ввод не попадает в низкокардинальные метрики: иначе система создаст огромное число уникальных временных рядов и повысит стоимость хранения. В метрику обычно лучше вынести тип операции, а не свободную строку.

Пилотируйте на небольшой доле обезличенных запросов. Сравните задержку до и после инструментирования, проверьте поведение при недоступном коллекторе и убедитесь, что приложение не зависает из-за отправки логов. На время расследования увеличивайте детализацию управляемо, с автоматическим возвратом к обычному режиму.

Вывод

OpenTelemetry полезен не потому, что делает ответы умнее, а потому что показывает путь запроса через систему. Начинайте с времён, версии компонентов, безопасных идентификаторов и кодов ошибок. Содержимое диалога добавляйте лишь при понятной цели и контролируемом доступе. Для оценки зрелости агента сопоставьте трассу с негативными тестами опасных действий, а требования к платформенным границам — с разбором архитектуры доверия.

FAQ

Достаточно ли сохранять trace ID и время? Для первичной диагностики это начало, но нужны ещё тип шага, статус, версия приложения и связь с внешними вызовами.

Нужно ли трассировать каждый запрос? Не обязательно; частоту и выборку подбирают по нагрузке и риску, отдельно обеспечивая видимость ошибок.

Можно ли писать prompt для отладки? Только при обоснованной необходимости, с очисткой данных, ограниченным доступом и заданным сроком удаления.

Как читать трассу во время инцидента

Начните с границ одного запуска, а не с поиска по всем логам. Найдите корневой идентификатор, затем пройдите дочерние spans в порядке времени и сопоставьте их с версиями приложения, модели и инструмента. Отдельно отметьте интервалы ожидания: длительная пауза может объясняться сетью или очередью, а не «медленным рассуждением». Если шаг повторился, выясните, был ли это безопасный retry или второе внешнее действие.

Сохраните краткую выжимку расследования рядом с трассой: симптом, первый подтверждённый сбой, влияние на пользователя, временную меру и владельца следующего шага. Не копируйте в неё большие фрагменты закрытого запроса. Полезно вести словарь собственных атрибутов: одинаковые имена для статуса инструмента, типа шага и результата позволят строить дашборд без отдельных исключений для каждого сервиса. Начните с нескольких критичных показателей и постепенно расширяйте покрытие.