Observability и трассировка пайплайна

Каждое сообщение клиента, поступающее в Sales Assistant, запускает детерминированный пайплайн из нескольких фаз: извлечение заказа, маршрутизация, AI-обработка, колбэки и пост-эффекты. QuotyAI собирает подробную телеметрию по каждой фазе, чтобы вы могли точно видеть, что произошло, когда и почему.

Что записывается

Каждый прогон пайплайна (одно сообщение клиента → один ответ ассистента) формирует запись прогона из пяти фаз:

Клиент отправляет сообщение
        ↓
┌───────────────────────────────────┐
│  1. Извлечение заказа              │
│  Что ассистент извлёк из сообщения │
└───────────────────────────────────┘
        ↓
┌───────────────────────────────────────┐
│  2. Детерминированный маршрутизатор    │
│  Какие инструкции сработали,           │
│  сгенерированный код,                  │
│  действия, длительность                │
└───────────────────────────────────────┘
        ↓
┌────────────────────────────────┐
│  3. AI-агент (LLM)             │
│  Использованная модель, токены, │
│  превью ответа, ссылка на      │
│  полный водопад LLM-трейса     │
└────────────────────────────────┘
        ↓
┌────────────────────────────────────┐
│  4. Детерминированные колбэки      │
│  Какие колбэки выполнились,        │
│  сгенерированный код, действия     │
└────────────────────────────────────┘
        ↓
┌───────────────────────────────┐
│  5. Пост-эффекты              │
│  Отправленные вложения,       │
│  изменения состояния,         │
│  события передачи оператору   │
└───────────────────────────────┘

Каждая фаза фиксирует время начала, время окончания, длительность и статус (успех / ошибка / пропущена). Ошибки записываются на уровне фазы, не прерывая пайплайн.

Обзор пайплайна

Из любого AI-сообщения в диалоге нажмите кнопку observability, чтобы открыть модальное окно Sales Assistant Observability. По умолчанию отображается Pipeline Overview — вертикальная временная шкала всех пяти фаз для данного сообщения.

Карточки фаз

Каждая фаза представлена сворачиваемой карточкой:

Индикатор статуса (зелёный = успех, красный = ошибка, серый = пропущено)
Название фазы и длительность
Раскрывающиеся детали

Извлечение заказа

Показывает входное состояние диалога и структурированные данные заказа, которые извлёк ассистент. Это исходные данные, с которыми будут работать маршрутизаторы и AI.

Маршрутизатор (пре-AI автоматизация)

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

Содержание инструкции (исходное бизнес-правило)
Сгенерированный TypeScript-код (превью с подсветкой синтаксиса)
Возвращённые действия (send_message, update_state, short_circuit и т.д.)
Длительность и успех/ошибка по каждой инструкции
Флаг, прервал ли маршрутизатор работу AI

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

AI-агент (LLM)

Показывает:

Использованную модель (например, gpt-4o)
Расход токенов (промпт, ответ, всего)
Превью ответа
Флаг передачи оператору-человеку
Ссылку на полный водопад LLM-трейса — полную трассировку LangChain с каждым вызовом инструмента, шагом цепочки и LLM-вызовом

Кнопка «View Full LLM Trace Waterfall» переключает на вкладку трейса и фильтрует до нужного трейса. ID связанного LLM-трейса хранится в записи прогона, так что вы всегда можете выполнить перекрёстную проверку.

Колбэки (пост-AI автоматизация)

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

Пост-эффекты

Показывает:

Отправленные вложения — какая инструкция инициировала каждое вложение и успешно ли оно отправлено
Изменения состояния — diff «до/после» для каждого изменённого ключа состояния диалога
События передачи оператору — если прогон завершился передачей человеку, включая причину

Водопад LLM-трейса

Вторая вкладка модального окна observability — LLM Trace Waterfall — визуализация в виде диаграммы Ганта всего, что происходило внутри AI-агента:

LLM-вызов — span с моделью, токенами промпта и ответа, длительностью
Вызов инструмента — span с именем инструмента, входными аргументами и возвращаемым значением
Шаг цепочки — span с порядком выполнения
Типовая раскраска — span’ы раскрашены по типу (LLM, Tool, Chain, Retriever, Other)
Детали — любой span можно раскрыть, чтобы увидеть входные данные, выходные, теги и ошибки

Водопад — это классическое представление LLM-observability, но теперь связанное напрямую с обзором пайплайна через массив llmRunIds, хранящийся в фазе AI-агента. Это позволяет отслеживать несколько LLM-вызовов за один прогон.

Поиск и фильтрация

Поиск — фильтрация span’ов по имени, типу или тегам
Фильтр по типу — показывать только LLM-вызовы, вызовы инструментов, цепочки и т.д.
Сортировка — по времени начала, длительности, имени или типу
Панель статистики — агрегированные метрики: общее количество span’ов, средняя/макс/мин длительность, процент успеха, разбивка по типам

Экспорт

Полный трейс можно экспортировать в JSON или CSV, либо скопировать все span’ы в буфер обмена для отладки или внешнего анализа.

Когда что-то пошло не так

Ошибка фазы

Если фаза завершилась ошибкой (статус = красный), сообщение об ошибке записывается и отображается в карточке фазы. Пайплайн продолжается — одна упавшая инструкция не блокирует остальные. Общий статус прогона отражает, завершился ли весь прогон успешно или с ошибкой.

Прерывание AI (Short-Circuit)

Когда инструкция маршрутизатора возвращает short_circuit, фаза AI-агента полностью пропускается. В обзоре пайплайна на фазе маршрутизатора отображается предупреждающий значок, а фаза AI-агента показывает статус «пропущено» без данных. Это ожидаемое поведение — маршрутизатор намеренно обошёл AI для данного сообщения.

Отсутствие записи прогона

Если модальное окно observability показывает «No pipeline data», но водопад трейса существует, значит прогон мог начаться до включения observability, или сообщение было обработано старой версией ассистента. Запись пайплайна появилась вместе с функцией Sales Assistant Observability — у существующих сообщений не будет записей прогона.

Техническая архитектура

Модель данных

Записи прогонов хранятся в отдельной MongoDB-коллекции sales-assistant-runs (независимо от записей LLM-трейсов). Каждая запись содержит:

{
  runId: string,           // UUID — связь с LLM-трейсом
  status: string,          // "completed" | "failed"
  totalDurationMs: number,
  customerMessage: string,
  channelType: string,
  phases: {
    orderExtraction?: { ... },
    deterministicRouter?: {
      status: string,
      startTime: number,
      endTime: number,
      durationMs: number,
      instructionResults: [{
        instructionId: string,
        instructionContent: string,
        category: string,
        generatedCode: string,
        actions: [{ type, ... }],
        durationMs: number,
        success: boolean,
        error?: string
      }],
      shortCircuited: boolean,
      totalActionsProduced: number
    },
    aiAgent?: {
      status: string,
      modelUsed: string,
      tokenUsage: { prompt, completion, total },
      responsePreview: string,
      llmRunIds: string[],  // перекрёстная ссылка на LLM-трейс(ы)
      handoverOccurred: boolean
    },
    deterministicCallback?: { ... },
    afterRun?: {
      attachmentsSent: [{ instructionId, attachmentId, success }],
      stateChanges: [{ key, from, to }],
      handoverOccurred: boolean,
      handoverReason?: string
    }
  },
  createdAt: string,
  completedAt?: string
}

Пайплайн записи

Сервис-рекордер оборачивает каждую фазу замером времени, фиксацией статуса и обработкой ошибок:

Начало фазы — запись времени начала и метаданных фазы
Выполнение фазы — запуск фактической логики (функции маршрутизатора, AI-инвок, колбэки)
Конец фазы — запись времени окончания, длительности, статуса и результата
Обработка ошибок — если фаза выбрасывает исключение, ошибка фиксируется в записи фазы, а прогон продолжается

Рекордер никогда не выбрасывает исключений — ошибки всегда записываются в статус фазы, чтобы последующие фазы могли выполниться.

Корреляция

Идентификатор прогона _id является ключом корреляции для всей системы:

Sales Assistant Run (фазы пайплайна) —— _id
        ↓
LLM Observability run —— assistantPipelineRunId
        ↓
LangChain run tree —— child_runs (рекурсивно)

Массив llmRunIds в фазе AI-агента связывает напрямую с LLM-observability-прогонами, так что вы можете перейти от «AI сказал это» к «вот каждый LLM-вызов, вызов инструмента и шаг цепочки, которые это сформировали».

Лучшие практики

Отладка инструкций маршрутизатора

Если инструкция маршрутизатора ведёт себя не так, как ожидалось, откройте обзор пайплайна:

Проверьте фазу Router — выполнилась ли инструкция? (зелёная галочка) Завершилась ли ошибкой? (красный крест)
Разверните инструкцию и посмотрите сгенерированный код — соответствует ли он вашему замыслу?
Проверьте возвращённые действия — что на самом деле произвела функция?
Если сгенерированный код неверен, перепишите инструкцию более чётким языком и пересоберите ассистента

Аудит поведения AI

Если AI-ответ выглядит некорректным:

Откройте Pipeline Overview — проверьте, какие условные промпты были активны
Переключитесь на LLM Trace Waterfall — разверните LLM-спаны, чтобы увидеть, что именно было отправлено модели
Проверьте входные и выходные данные вызовов инструментов — вызвал ли AI нужный инструмент с правильными аргументами?

Мониторинг производительности

Панель статистики в водопаде трейса показывает агрегированные метрики. Используйте её, чтобы:

Выявлять медленные LLM-вызовы или вызовы инструментов
Отслеживать тенденции расхода токенов
Следить за процентом успешных операций во времени

Перекрёстные ссылки

Запись прогона включает как сообщение клиента, так и превью AI-ответа. В сочетании с изменениями состояния из пост-эффектов вы можете восстановить полный контекст диалога для любого автоматизированного взаимодействия — полезно для аудита соответствия и урегулирования споров с клиентами.