Как читать трейс

Трейс - это дерево вызовов, которое описывает логику работы, отображает ошибки и время выполнения операций. Каждый узел дерева называется спан или observation - он соответствует определенному шагу или событию в работе агента.

Схема воркшопа

  • Трейс читается сверху вниз - от наиболее ранних к наиболее поздним событиям
  • На скриншоте мы видим спаны: run-agent, list-tools, choose-model и т.д.
  • Самый первый спан run-agent называют корневым или root спаном
  • Спаны вложены друг в друга, образуя иерархию. Например, если функция А вызвала функцию Б, то спан для Б будет вложен в А. Говорят, что спан Б является дочерним для А. Или что А является родительским для Б.
  • Рядом с каждым спаном отображено время выполнения шага в секундах, например 9.42s. Это позволяет проводить диагностику производительности.
  • Ошибки (необработанные исключения) отображаются в трейсе красным маркером ERROR
  • У каждого спана есть иконка, соответствующая типу спана. Список доступных типов
  • Выбрав спан, можно изучить более детальную информацию...

Схема воркшопа

  • У каждого спана есть детали, в которых отображается метаинформация и точное время события
  • В спане также могут быть зафиксированы входящие input и исходящие output данные шага. Например, запрос и ответ от LLM. Это очень полезно для диагностики работы агента.

В общем случае, для диагностики дефекта:

  1. Смотрим, есть ли в спане явные ошибки ERROR и изучаем их.
  2. Если явных ошибок нет - находим спан с результатом (часто последний)
  3. Изучаем input спана, чтобы понять, насколько корректную информацию мы получили на вход. Если на вход была подана неверная информация, — идем выше по дереву, чтобы найти источник некорректных данных.
  4. Изучаем output спана, чтобы убедиться, что внешняя система или шаг алгоритма ответили правильно.

Как найти трейс на закладке Tracing

На закладке Tracing собраны все спаны всех трейсов: каждый вызов LLM, каждый вызов инструмента и каждый шаг агента - это отдельная строка. Поэтому один запрос к агенту превращается в таблице в несколько строк, и найти нужный трейс бывает непросто.

Чтобы видеть по одной строке на каждый запрос, оставьте в таблице только корневые спаны: в панели Filters в разделе Is Root Observation выберите True. В строке фильтра появится условие isRootObservation:true, а в таблице останутся только спаны run-agent. Откройте любой из них, чтобы увидеть весь трейс целиком.

Корневые спаны

Сессии

Один трейс описывает один запрос к агенту. Но пользователь редко ограничивается одним запросом: он ведет диалог, уточняет, возвращается к предыдущему ответу. Чтобы видеть такие цепочки целиком, в Langfuse есть сессии (Sessions).

Сессия - это группа трейсов с одинаковым идентификатором session_id. Приложение само решает, какие трейсы объединить, и передает session_id вместе с трейсом. Langfuse показывает сессию на закладке Sessions как ленту: трейсы идут по времени, видны суммарная стоимость, длительность и все оценки.

Обычно сессии используют, чтобы:

  • воспроизвести диалог пользователя с чат-ботом от первой до последней реплики;
  • найти место, где разговор пошел не так: например, агент забыл, о чем его просили несколькими сообщениями раньше;
  • посчитать, во что обходится один диалог или один сценарий использования, а не отдельный запрос.

Как сессии используются в воркшопе

В нашем воркшопе каждый сценарий включается флагами в .env, поэтому агент объединяет трейсы в сессии по включенным флагам:

  • NO_STEP - ни один флаг не включен;
  • STEP_1, STEP_3, STEP_4 и т.д. - включен один флаг;
  • STEP_5_1+STEP_5_2 - включено несколько флагов, они перечисляются через +.

Важная деталь: флаги STEP_3 и STEP_4 действуют на MCP-сервер, поэтому агент не берет их из .env, а спрашивает у самого MCP-сервера, с какими флагами тот реально запущен. Сессия отражает то, как система работает на самом деле, а не то, что написано в настройках.

Чем это помогает в диагностике

  • Весь сценарий в одном месте. Откройте сессию STEP_3, и вы увидите подряд все запросы этого сценария, включая упавшие с ERROR.
  • Сравнение до и после. Сравните стоимость и оценки качества в сессиях разных сценариев - например, сколько стоили запросы в сессии STEP_4 и в NO_STEP.
  • Ошибки конфигурации видны сразу. Если вы включили флаг в .env, но забыли перезапустить контейнер, трейсы попадут в сессию NO_STEP, а не в ожидаемую. А сессия вида STEP_1+STEP_3 подскажет, что вы забыли выключить флаг предыдущего сценария.

Не путайте сессии Langfuse с памятью агента из сценария 5. Память привязана к вкладке браузера и сбрасывается при обновлении страницы (F5), а сессия в Langfuse определяется только включенными флагами.