Langfuse Trace: как читать трассировку одного запроса к LLM

Открыли интерфейс Langfuse, видите дерево из вложенных блоков и не понимаете, что где искать? Langfuse trace устроен как папка с вложенными шагами: сверху сам запрос целиком, внутри — span для промежуточных операций и generation для конкретного вызова модели. Ниже разберем эту иерархию на живом примере RAG-агента и покажем, куда смотреть при двух типичных жалобах: неверный ответ и неожиданный счет за токены.

В trace Langfuse три уровня: сам trace (весь запрос), span внутри него (шаги вроде поиска в базе) и generation (конкретный вызов LLM с промптом, ответом и стоимостью). Разберем на примере RAG-агента, что смотреть при неверном ответе и при дорогом запросе.

Что вообще такое trace в Langfuse

Trace — это корневой контейнер одного запроса пользователя, от первого символа вопроса до финального ответа. Все, что произошло внутри этого запроса, живет внутри trace.

Один trace всегда привязан к одному конкретному выполнению, а не к функции в коде. Функцию можно вызвать сто раз в разных контекстах, а trace существует один раз и закрывается, когда обработка запроса завершена. У trace есть общее время выполнения и суммарная стоимость всех вложенных вызовов модели.

Если у вашего бота идет диалог из нескольких сообщений подряд, каждое сообщение получает отдельный trace. Все эти trace можно объединить session ID — тогда в интерфейсе видно всю переписку целиком, а не разрозненные куски. Это удобно, когда пользователь пишет пять адекватных сообщений подряд, но так и не решает свою проблему — на уровне одного trace это не поймать, а на уровне session сразу видно.

Зачем внутри trace нужны span

Span — это именованный отрезок времени внутри trace: поиск в базе данных, вызов инструмента, парсинг файла. Span отвечает на вопрос "сколько это заняло" и может быть вложен в другой span.

Представьте trace горизонтальной шкалой времени. Span — это отрезки на этой шкале, часть из них вложена друг в друга. Например, span "обработать запрос" может содержать внутри себя span "найти документы" и span "собрать промпт" — оба выполнились внутри общего времени родителя.

Ключевое правило: span обязательно принадлежит какому-то trace, сам по себе он существовать не может. Если в коде потерять trace ID при передаче между сервисами, span повиснет сиротой без родителя, и в интерфейсе Langfuse трасса просто развалится на несвязанные куски. Такое реально случается при интеграции с OpenTelemetry, когда фильтрация блокирует нужный scope.

Чем generation отличается от обычного span

Generation — это специальный тип наблюдения именно для вызова языковой модели: с полным промптом, ответом, числом токенов и точной стоимостью в долларах. Span просто мерит время, generation еще и описывает содержание.

Span измеряет длительность, а вот что происходило внутри — не его забота. Для этого существуют observations: описательные данные вроде текста промпта, имени модели, температуры и токенов. Generation — частный случай observation, заточенный под LLM. Через интеграцию с провайдером модели Langfuse автоматически захватывает параметры вызова, включая расход токенов, и сама считает стоимость запроса, если имя модели в коде точно совпадает с прайс-листом платформы.

На практике вызов модели почти всегда обернут в span, а сам промпт и ответ записаны как вложенный generation внутри этого span. Разделять их важно: если склеить время и содержание в одну сущность, аналитика по задержкам начинает врать.

Как выглядит trace на примере RAG-агента

Корневой trace "ответ на вопрос" содержит span поиска документов, span сборки промпта и generation с итоговым ответом модели. Каждый уровень виден отдельно — если ответ неверный, сразу понятно, на каком шаге все сломалось.

Возьмем конкретный сценарий: пользователь спрашивает у RAG-агента что-то по внутренней базе знаний. В Langfuse это разворачивается так:

1. Корневой trace "ответ на вопрос" — открывается в момент отправки сообщения, закрывается на финальном ответе.
2. Дочерний span "поиск документов" — видно, какой запрос ушел в векторную базу и какие фрагменты вернулись обратно.
3. Второй span "сборка промпта" — сюда добавляются найденные документы поверх вопроса пользователя.
4. Вложенный generation — сам вызов модели: полный промпт с документами внутри, ответ модели, число входных и выходных токенов, цена вызова.

Все четыре блока связаны через один trace ID, поэтому в интерфейсе они рисуются вложенной иерархией, а не плоским списком логов. Проблемные шаги Langfuse подсвечивает оранжевым или красным прямо на шкале, так что зависший или упавший span заметен сразу, без чтения деталей.

Что смотреть, если ответ был неверным по фактам

Если RAG-агент выдал неправильный ответ, первым делом открывайте span поиска, а не generation. Часто причина в том, что векторная база вернула не тот документ, а модель честно ответила по контексту, который ей дали.

Отладка начинается с вопроса: агент придумал факт или его подвел поиск. Открываете span "поиск документов" и смотрите, что реально нашлось по запросу. Если там не тот фрагмент базы знаний, генерация ни при чем — модель работала с некорректным контекстом. Если документы верные, а ответ все равно неправильный, тогда смотрите сам generation и проверяйте, не выпал ли нужный фрагмент из промпта из-за лимита контекста.

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

С трассировкой этот процесс идет быстрее в разы. Раньше приходилось гадать и переписывать промпт наугад, а с открытым trace видно ровно тот шаг, где логика свернула не туда.

Что делать, если запрос оказался неожиданно дорогим

Дорогой запрос почти всегда прячется в количестве входных токенов generation, а не в самой модели. Чаще всего причина в разросшейся истории диалога, которую передают целиком на каждом шаге.

Открываете generation и смотрите на разбивку токенов: prompt tokens против completion tokens. Если входных токенов подозрительно много при коротком вопросе пользователя, ищите, что еще попало в промпт: полная история переписки, лишние документы из поиска, старые системные подсказки, которые никто не чистит между шагами.

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

Какие правила именования спасают от хаоса в трассировках

Без пяти базовых привычек trace превращается в нечитаемую кашу: без user ID нельзя считать расходы по пользователю, без session ID теряется связь между сообщениями одного диалога.

Пять привычек, которые стоит завести сразу, а не после первого инцидента в проде:

• Всегда указывать user ID — иначе стоимость по конкретному пользователю не собрать.
• Группировать связанные trace через session ID.
• Следить, чтобы имя модели в коде точно совпадало с прайс-листом Langfuse, иначе расчет стоимости просто сломается.
• Явно помечать span поиска как retrieval, чтобы потом фильтровать их отдельно.
• LLM-судью запускать на корневом наблюдении, где виден полный вход и полный выход, а не на промежуточном шаге.

Trace объединяет generation и span, которые вместе фиксируют полное взаимодействие пользователя с моделью — так это описывает официальная документация Langfuse по трассировке.

Глоссарий

• Trace — корневой контейнер одного запроса пользователя от начала до конца.
• Span — именованный временной отрезок внутри trace, измеряет длительность операции.
• Generation — специальный вид span-наблюдения именно для вызова LLM: промпт, ответ, токены, цена.
• Session — группа из нескольких trace, объединенных одним диалогом или визитом пользователя.
• Observation — общее название для описательных данных внутри trace: промпт, параметры модели, ответ.
• LLM-as-a-judge — оценка качества ответа другой моделью вместо ручной проверки человеком.

FAQ

Чем trace отличается от span?
Trace — это весь запрос целиком, от старта до финала. Span — это один именованный шаг внутри trace, например поиск в базе или вызов инструмента. Span не может существовать без родительского trace.

Можно ли увидеть стоимость одного конкретного вызова модели?
Да, стоимость считается на уровне generation. Там видно точное число входных и выходных токенов и итоговую цену в долларах при условии, что имя модели в коде совпадает с прайс-листом Langfuse.

Почему один span вложен в другой?
Потому что реальные операции вложены друг в друга: обработка запроса вызывает поиск, поиск вызывает обращение к базе. Вложенность span отражает эту иерархию и показывает, где реально потрачено время.

Что делать, если trace разваливается на несвязанные куски?
Обычно причина в потерянном trace ID при передаче между сервисами или в блокировке родительского span настройками OpenTelemetry. Проверьте, что каждый дочерний span явно ссылается на родителя.

Нужно ли смотреть каждый generation вручную?
Нет, для этого в Langfuse есть LLM-as-a-judge — модель, которая сама оценивает качество ответа по корневому наблюдению. Ручной просмотр нужен точечно, при конкретной жалобе или для калибровки автоматической оценки.

Помогает ли session ID при отладке одного запроса?
Не напрямую, но помогает увидеть контекст. Если пользователь получил пять формально верных ответов подряд, но так и не решил проблему, это видно только на уровне session, а не одного trace.

Это работает только с OpenAI?
Нет, Langfuse не привязан к одному провайдеру моделей и захватывает вызовы разных LLM через свои интеграции, включая self-hosted развертывание через Docker.

Разобраться со своим стеком наблюдаемости за час — реальная задача, не неделя чтения документации. Если строите AI-продукт и хотите настроить трассировку правильно с первого раза, посмотрите каталог AI-инструментов на VibeCoderz или запишитесь на консультацию к Максиму.

Больше по теме: Langfuse — обзор платформы, RAG для вайбкодеров простым языком, юнит-экономика AI-продукта. Если настраиваете observability как часть работы AI/DevOps-инженера, в каталоге агентов VibeCoderz есть отдельный разбор под эту роль.

Источники: документация Langfuse по трассировке, обзор архитектуры Langfuse на Y Combinator Launches.

Обновлено: август 2026.