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

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

## Что записывать

Один запуск агента — это дерево шагов. Минимальный набор полей на шаг:

| Поле | Зачем |
| --- | --- |
| Идентификатор запуска | Связать шаги в одну трассу |
| Шаг и его тип | Понять маршрут |
| Вход и выход шага | Воспроизвести решение |
| Модель и версия промпта | Объяснить изменение поведения |
| Токены и стоимость | Посчитать цену запуска |
| Задержка | Найти узкое место |
| Ошибка и её тип | Отделить технический сбой от логического |

Без версии промпта разбор бесполезен: поведение изменилось, а причина неизвестна.

## Трасса вместо логов

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

## Приватность в логах

Трасса содержит входы и выходы, то есть пользовательские данные. Требования:

- очищать персональные данные до записи — см.
  [21. PII Sanitization](https://wpcraft.ru/aia/examples/21-pii-sanitization-agent.md);
- ограничивать срок хранения;
- разграничивать доступ: не все инженеры должны видеть содержимое диалогов;
- не писать ключи и заголовки авторизации.

## Метрики

- Число шагов на задачу и его распределение.
- Стоимость на запуск и на успешный запуск.
- Доля запусков, завершившихся ошибкой, по типам.
- p50 и p95 задержки.
- Доля запусков, потребовавших вмешательства человека.

Разница между стоимостью на запуск и на успешный запуск показывает цену неудач.

## Разбор инцидента

Порядок, который работает:

1. Найти запуск по идентификатору или времени.
2. Посмотреть маршрут: где отклонился от ожидаемого.
3. Сравнить с предыдущей успешной трассой.
4. Проверить, менялись ли промпт, модель или инструмент.
5. Воспроизвести на том же входе.
6. Добавить вход в eval-набор.

Шестой пункт превращает инцидент в защиту от повторения.

## Алерты

Алерт ставят не на «ошибка», а на отклонение от нормы:

- доля ошибок выше обычной;
- стоимость запуска выше порога;
- задержка p95 выросла;
- число шагов упёрлось в лимит;
- рост доли эскалаций.

Алерт на каждую ошибку быстро превращается в шум и перестаёт читаться.

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

- [WPCraft KB: наблюдаемость](https://wpcraft.ru/kb/infrastructure/observability) — общие практики SRE.