﻿---
title: "Наблюдаемость: трассировка и стоимость"
description: "Трассы и spans, OpenTelemetry, стоимость токенов и задержки: как разобрать поведение агента и превратить production-ошибки в датасет для оценки."
---

## Что делает слой

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

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

## Трасса и spans

**Трассировка (trace)** объединяет один запуск. Отдельные операции внутри него записываются как **spans**: запрос пользователя → вызов модели → поиск → вызов инструмента → ответ.

Из такой структуры видно:

- **Почему ответ неверный** — какие документы извлекли и что передали модели.
- **Что замедлило работу** — на каком шаге выросла задержка.
- **Где выросли затраты** — какой шаг съел токены.
- **Где упало** — какой вызов вернул ошибку и как её обработали.

OpenTelemetry помогает передавать такие данные в совместимые системы, но способ подключения зависит от платформы: SDK, автоинструментация или AI-шлюз.

## Платформы

| Платформа | Особенность |
|---|---|
| **Langfuse** | SDK или OpenTelemetry-инструментация, иерархическая трассировка, входы и выходы шагов, токены, стоимость, задержки |
| **Arize Phoenix** | Open-source, приём трассировок по OpenTelemetry/OTLP, OpenInference-инструментация LLM-вызовов, retrieval и инструментов |
| **LangSmith** | Интеграции с фреймворками и SDK, связывание вызовов в трассировки агента; неудачные запуски переносятся в датасеты |
| **Helicone** | AI Gateway: вызовы моделей идут через шлюз и автоматически логируются — прежде всего слой обращений к моделям |

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

## Что обязательно логировать

- **Модель и версия** на каждом шаге — иначе сравнение «до и после» невозможно.
- **Промпт и ответ** с маскированием секретов и персональных данных.
- **Результат retrieval** — идентификаторы найденных документов, score, применённые фильтры.
- **Вызовы инструментов** — имя, аргументы, результат, длительность.
- **Стоимость и токены** по шагам, а не по запросу целиком.

Маскирование — не опциональная настройка: в трассировку не должны попадать ключи, пароли, персональные данные клиентов.

## Связка с оценкой

Наблюдаемость и [оценка качества](https://wpcraft.ru/kb/ai/agents/evaluation.md) работают в паре:

```text
production-трасса с ошибкой → разбор → добавление в датасет → регрессионная проверка
```

Без трассировки набор для оценки пополняется вручную и быстро устаревает. С ней каждый инцидент превращается в тест, а качество растёт от реального использования.

## Что проверить в проекте

- **Виден ли один запрос целиком.** Если шаги живут в разных системах без общего идентификатора, разбор невозможен.
- **Есть ли стоимость по шагам.** Общая сумма за месяц не отвечает на вопрос, какой сценарий убыточен.
- **Маскируются ли данные.** Проверьте это до первого инцидента, а не после.
- **Настроено ли оповещение.** Рост доли ошибок и задержек должен поднимать сигнал, а не ждать, пока его заметит пользователь.
- **Хватает ли срока хранения.** Разбор сложного инцидента занимает дни; срок хранения трасс должен это покрывать.

## Связанные материалы

- [Evals](https://wpcraft.ru/kb/ai/evals.md) — слои проверок и покомпонентные evals, в которые превращаются трассы.
- [Распределённая трассировка](https://wpcraft.ru/kb/infrastructure/observability/tracing.md) — общая модель traces, spans и propagation.
- [OpenTelemetry](https://wpcraft.ru/kb/infrastructure/tools/open-telemetry.md) — переносимая инструментация и конвейер телеметрии.

## Материалы и источники

- [Системное мышление для агентного ИИ](https://wpcraft.ru/blog/systems-thinking-for-agentic-ai) — статья WPCraft, раздел «Observability»
- [Arize Phoenix](https://arize.com/docs/phoenix) — open-source платформа трассировки
- [LangSmith: observability](https://docs.langchain.com/langsmith/observability) — трассировка агентных запусков
- [Helicone](https://docs.helicone.ai/) — шлюз с автоматическим логированием вызовов моделей