Что такое observability и tracing в ИИ-агентах

Короткое объяснение

Observability - это наблюдаемость ИИ-системы: способность понять, что произошло внутри запроса, почему агент дал такой ответ, какие шаги выполнил, какие документы нашел, какие tools вызвал, сколько это стоило и где возникла ошибка.

Если совсем просто:

1. пользователь задает вопрос;
2. агент получает run_id;
3. система записывает каждый шаг;
4. trace показывает путь одного запуска;
5. logs фиксируют события и ошибки;
6. metrics показывают цифры по многим запускам;
7. dashboard помогает увидеть тенденции;
8. alerts сообщают, если качество, стоимость или ошибки вышли за пределы нормы.

Без observability ИИ-продукт выглядит как черный ящик: пользователь жалуется на плохой ответ, а команда не понимает, модель ошиблась, RAG не нашел документ, tool упал или guardrail заблокировал действие.

Зачем observability нужна ИИ-системам

Обычный backend можно проверить по HTTP-статусу, логам и ошибкам. С ИИ сложнее: запрос может завершиться успешно с точки зрения сервера, но ответ будет неверным, неполным, дорогим или небезопасным.

Observability помогает:

1. расследовать плохие ответы;
2. видеть путь агентного запуска;
3. находить ошибки RAG;
4. понимать, какой tool был вызван;
5. считать стоимость model calls;
6. измерять latency;
7. видеть повторы и ретраи;
8. ловить prompt injection;
9. анализировать human approval;
10. пополнять eval dataset реальными ошибками;
11. сравнивать версии промпта;
12. принимать решения по качеству продукта.

Главная задача observability - не просто хранить логи, а быстро отвечать на вопрос: что именно пошло не так и что чинить.

Чем observability отличается от мониторинга

Мониторинг отвечает на вопрос "система здорова или нет". Observability помогает понять "почему она ведет себя именно так".

Мониторинг показывает:

1. сколько ошибок;
2. какая задержка;
3. сколько запросов;
4. сколько стоит работа модели;
5. есть ли алерты;
6. растет ли очередь;
7. падают ли tools;
8. доступен ли сервис.

Observability добавляет контекст:

1. какой prompt ушел модели;
2. какие документы попали в RAG-контекст;
3. какие tools выбрал агент;
4. какой результат вернул tool;
5. почему сработал guardrail;
6. почему потребовался handoff;
7. какие шаги заняли время;
8. какая версия промпта использовалась.

Мониторинг говорит "у нас выросли ошибки". Observability показывает, что ошибки выросли после новой версии промпта и падают на сценариях с поиском по базе знаний.

Три опоры: traces, logs, metrics

Для ИИ-приложений обычно нужны три типа данных.

Traces:

1. показывают путь одного запуска;
2. связывают шаги по run_id;
3. помогают расследовать конкретный плохой ответ;
4. показывают model calls, RAG, tools и ошибки.

Logs:

1. фиксируют события;
2. помогают искать ошибки;
3. сохраняют важные решения;
4. дают материал для audit log.

Metrics:

1. показывают агрегированную картину;
2. помогают строить dashboards;
3. нужны для alerts;
4. показывают динамику качества, стоимости и задержки.

Если оставить только metrics, непонятно, почему произошла ошибка. Если оставить только logs, трудно увидеть тенденции. Если есть traces, logs и metrics вместе, система становится управляемой.

Что такое trace

Trace - это запись полного пути одного запроса или одного запуска агента.

Хороший trace показывает:

1. входной запрос;
2. id пользователя или сессии;
3. версию промпта;
4. модель;
5. параметры модели;
6. найденные документы;
7. chunks, переданные в контекст;
8. вызовы tools;
9. аргументы tools;
10. результаты tools;
11. ошибки;
12. retries;
13. latency каждого шага;
14. стоимость model calls;
15. финальный ответ;
16. оценку пользователя или оператора.

Trace нужен, когда надо понять не только что ответил агент, но и как он к этому пришел.

Что такое run_id

Run_id - это уникальный идентификатор одного запуска. Он связывает все события внутри запроса.

Например, один run_id может объединять:

1. HTTP request;
2. входной текст;
3. retrieval request;
4. найденные chunks;
5. model call;
6. tool call;
7. approval request;
8. финальный ответ;
9. user feedback;
10. ошибку или retry.

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

Что писать в trace

В trace нужно писать достаточно данных для диагностики, но не превращать его в свалку.

Полезно сохранять:

1. run_id;
2. user_id или account_id;
3. scenario;
4. prompt version;
5. model name;
6. input length;
7. output length;
8. token usage;
9. cost;
10. retrieved document ids;
11. tool name;
12. tool arguments без секретов;
13. tool status;
14. guardrail verdict;
15. approval status;
16. latency;
17. error code;
18. final status.

Полный текст входа и ответа можно хранить не всегда. Для production часто нужны маскирование, sampling и отдельные правила хранения.

Что не стоит писать в trace

Observability не должна создавать новую дыру в безопасности.

Осторожно с такими данными:

1. пароли;
2. API keys;
3. access tokens;
4. персональные данные;
5. платежные данные;
6. медицинская информация;
7. коммерческая тайна;
8. приватные документы;
9. внутренние ключи доступа;
10. полный system prompt без контроля доступа.

Если такие данные нужны для расследования, используйте redaction, маскирование, ограничения доступа и короткий срок хранения.

Structured logs

Structured logs - это логи в структурированном формате, чаще всего JSON. Они лучше обычного текста, потому что по ним можно фильтровать и строить метрики.

Плохой лог:

Ошибка при вызове модели.

Хороший structured log содержит:

1. timestamp;
2. run_id;
3. user_id;
4. scenario;
5. component;
6. event_type;
7. model;
8. latency_ms;
9. status;
10. error_code;
11. cost_usd;
12. prompt_version.

По таким логам можно быстро найти все ошибки конкретной версии промпта или все дорогие запросы в одном сценарии.

Metrics для ИИ-продукта

Метрики показывают здоровье системы в целом.

Базовый набор:

1. количество запросов;
2. error rate;
3. average latency;
4. p95 latency;
5. cost per request;
6. total model cost;
7. token usage;
8. tool error rate;
9. retrieval success rate;
10. no-answer rate;
11. hallucination reports;
12. approval rate;
13. handoff rate;
14. user rating;
15. eval pass rate.

Метрики нужно смотреть по сценариям. Средняя оценка по всему продукту может быть хорошей, а один важный сценарий будет регулярно ломаться.

Model calls

Model call - это отдельный вызов языковой модели. В одном агентном запуске их может быть несколько: классификация, поиск плана, генерация ответа, проверка формата, финальная редактура.

Для model call полезно хранить:

1. provider;
2. model;
3. prompt version;
4. input tokens;
5. output tokens;
6. temperature;
7. latency;
8. cost;
9. finish reason;
10. error status.

Если стоимость резко выросла, часто причина в лишнем model call, слишком длинном контексте или повторных retries.

RAG diagnostics

Для RAG важно видеть не только ответ, но и поиск.

RAG diagnostics должны показывать:

1. запрос к поиску;
2. embedding model;
3. top-k;
4. найденные document ids;
5. score каждого chunk;
6. примененные filters;
7. версию индекса;
8. длину контекста;
9. пропущенные документы;
10. использованные цитаты.

Если агент ответил плохо, trace должен помочь понять: документ не найден, найден не тот фрагмент или модель проигнорировала правильный фрагмент.

Tool call logs

Для AI-агента tool calls - самая важная часть observability. Текст можно переписать, а действие в CRM, почте или базе данных может иметь последствия.

Для каждого tool call полезно хранить:

1. tool name;
2. tool version;
3. arguments schema;
4. очищенные arguments;
5. caller;
6. policy verdict;
7. approval status;
8. idempotency key;
9. execution status;
10. duration;
11. result summary;
12. error code;
13. rollback status.

Если агент сделал неправильное действие, без tool log будет трудно понять, это ошибка модели, policy gate, executor или внешнего API.

Guardrails events

Guardrails тоже должны оставлять события. Иначе команда не увидит, что именно блокируется.

Полезно логировать:

1. какой guardrail сработал;
2. на каком шаге;
3. входное действие;
4. решение: allow, block, rewrite, approval, handoff;
5. причину решения;
6. уровень риска;
7. ссылку на run_id;
8. итоговый результат.

Если guardrails часто блокируют нормальные запросы, их надо смягчить. Если почти никогда не срабатывают, стоит проверить, не слишком ли они слабые.

Human approval и handoff

Observability должна показывать, где агент передает управление человеку.

Для approval полезно видеть:

1. какое действие требовало подтверждения;
2. почему оно рискованное;
3. кто подтвердил;
4. кто отклонил;
5. сколько ждали решения;
6. что изменил человек;
7. был ли повторный запуск;
8. чем завершился кейс.

Для handoff полезно видеть:

1. почему агент передал случай;
2. как часто это происходит;
3. какие темы уходят людям;
4. сколько времени занимает обработка;
5. что оператор исправил.

Эти данные помогают постепенно автоматизировать безопасные сценарии и не трогать рискованные.

Связь observability и evals

Production traces - один из лучших материалов для evals.

Рабочий цикл:

1. пользователь получает плохой ответ;
2. команда открывает trace;
3. находит причину;
4. добавляет случай в eval dataset;
5. исправляет prompt, RAG, tool или guardrail;
6. прогоняет regression evals;
7. выкатывает изменение;
8. следит за production metrics.

Так ошибки не просто чинятся вручную, а превращаются в постоянную защиту от повторения.

Связь observability и audit log

Observability и audit log похожи, но решают разные задачи.

Observability нужна, чтобы отлаживать и улучшать систему:

1. latency;
2. errors;
3. traces;
4. стоимость;
5. качество;
6. диагностика RAG;
7. tool failures.

Audit log нужен, чтобы доказать, что произошло:

1. кто запустил действие;
2. что изменилось;
3. кто подтвердил;
4. какие данные затронуты;
5. когда это случилось;
6. можно ли откатить.

Для рискованных actions audit log должен быть надежнее обычного debug trace и храниться по правилам бизнеса.

Dashboard качества

Dashboard должен помогать принимать решения, а не просто красиво показывать графики.

Для AI-продукта полезны блоки:

1. качество ответов;
2. eval pass rate;
3. user feedback;
4. no-answer rate;
5. handoff rate;
6. hallucination reports;
7. tool failures;
8. RAG misses;
9. cost per successful task;
10. latency by scenario;
11. approval queue;
12. top failure categories.

Хороший dashboard показывает не только среднее, но и разбивку по сценариям, версиям промпта, моделям и типам пользователей.

Alerts

Alerts нужны, чтобы команда узнала о проблеме до того, как она станет большой.

Примеры alerts:

1. error rate выше нормы;
2. p95 latency выросла;
3. стоимость за час выросла;
4. tool часто падает;
5. handoff rate резко вырос;
6. no-answer rate вырос;
7. eval pass rate упал;
8. guardrail начал блокировать слишком много запросов;
9. approval queue зависла;
10. появилась серия одинаковых ошибок.

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

Privacy и хранение данных

Observability почти всегда касается чувствительных данных, поэтому правила хранения надо продумать заранее.

Что стоит определить:

1. какие поля маскируются;
2. какие поля не пишутся вообще;
3. кто имеет доступ к traces;
4. сколько хранятся production traces;
5. как удаляются данные пользователя;
6. где хранятся логи;
7. можно ли отправлять traces во внешний сервис;
8. как отличать dev, staging и production;
9. как работать с персональными данными;
10. как проводить расследование без раскрытия лишнего.

Иначе observability может помочь разработке, но создать риск для безопасности и соответствия требованиям.

Минимальная observability для старта

Для первой версии AI-продукта не обязательно строить сложную платформу.

Минимально нужно:

1. run_id для каждого запуска;
2. trace основных шагов;
3. structured logs;
4. model name и prompt version;
5. token usage;
6. latency;
7. cost;
8. retrieved document ids;
9. tool calls;
10. errors;
11. user feedback;
12. связка с eval dataset.

Этого уже достаточно, чтобы расследовать большинство плохих ответов и не гадать вслепую.

Когда observability особенно важна

Без наблюдаемости можно жить только в маленьком прототипе. Как только ИИ начинает влиять на реальные процессы, traces становятся обязательными.

Observability особенно нужна, если агент:

1. отвечает клиентам;
2. работает с CRM;
3. вызывает внешние tools;
4. использует RAG;
5. имеет память;
6. работает с персональными данными;
7. требует approval;
8. стоит заметных денег;
9. меняет документы;
10. работает в production.

Чем выше автономность агента, тем важнее видеть его внутренний путь.

Типичные ошибки

Observability часто внедряют слишком поздно.

Частые ошибки:

1. нет run_id;
2. логи только текстовые;
3. не хранится версия промпта;
4. не видны retrieved chunks;
5. не логируются tool calls;
6. не считается стоимость;
7. нет связи с evals;
8. traces содержат секреты;
9. доступ к логам слишком широкий;
10. dashboard показывает среднее без сценариев;
11. alerts слишком шумные;
12. production-ошибки не превращаются в тесты.

Главное правило: если плохой ответ нельзя объяснить по trace, observability пока недостаточна.

Мини-чеклист

Перед production-запуском проверьте:

1. у каждого запуска есть run_id;
2. trace показывает все важные шаги;
3. model calls логируются;
4. RAG diagnostics доступны;
5. tool calls логируются;
6. guardrails events видны;
7. human approval и handoff записываются;
8. стоимость считается;
9. latency измеряется по шагам;
10. production traces защищены;
11. есть dashboard по сценариям;
12. есть alerts;
13. ошибки попадают в eval dataset;
14. есть владелец качества и мониторинга.

Этот чеклист помогает не запускать агента как черный ящик.

Что изучать дальше

После observability полезно разобраться с соседними темами:

1. evals;
2. monitoring;
3. LLMOps;
4. audit log;
5. guardrails;
6. RAG diagnostics;
7. tool calling;
8. human-in-the-loop;
9. incident response;
10. prompt versioning.

Observability - это основа спокойного развития AI-продукта. Без нее каждое изменение промпта, модели или RAG превращается в риск.

Частые вопросы

Observability нужна только разработчикам?

Нет. Разработчику нужен trace, чтобы найти ошибку. Владельцу продукта нужны метрики качества, стоимости и пользовательских оценок. Руководителю поддержки нужны темы handoff и скорость обработки. Без observability все эти люди видят только жалобы и общие ощущения.

Нужно ли хранить полный текст всех запросов?

Не всегда. Полные traces полезны для отладки, но в production нужно учитывать персональные данные, коммерческую тайну и правила хранения. Часто используют redaction, sampling и разные уровни детализации для dev, staging и production.

Чем trace отличается от обычного лога?

Лог фиксирует отдельное событие. Trace связывает события одного запуска в цепочку: вход, RAG, model calls, tool calls, guardrails, approval, ошибки и финальный ответ. Для ИИ-агента trace обычно полезнее отдельной строки лога.

Можно ли начать без LangSmith или Langfuse?

Да. Можно начать с run_id, structured logs, таблицы ошибок и простого dashboard. Специализированные инструменты становятся полезны, когда появляется много traces, версий промптов, evals, tool calls и production-сценариев.

Что важнее: evals или observability?

Нужны оба слоя. Evals показывают, проходит ли система контрольные проверки. Observability объясняет, что произошло в реальном запуске. Вместе они помогают не только ловить ошибки, но и понимать их причину.