Чек-лист внедрения AI Observability: 20 шагов для продакшена
Чек-лист внедрения AI observability должен отвечать на более сложный вопрос, чем «API доступен?» Продакшен-функция на базе ИИ может возвращать HTTP 200, при этом выдавая неправильный ответ, использовать устаревший контекст retrieval, вызывать не тот инструмент, повторять попытки через дорогой fallback, утекать чувствительные prompt-данные в логи или работать слишком медленно, чтобы быть полезной.
Практическая цель — связать каждый видимый пользователю результат с попытками модели, шагами retrieval, вызовами инструментов, решениями политик, задержкой, использованием токенов и стоимостью, которые его породили. Для этого нужна обычная телеметрия приложения плюс AI-специфический контекст и сигналы оценки.
Это руководство предлагает поэтапный план внедрения для LLM-приложений, агентов, систем retrieval-augmented generation и много-модельных шлюзов. Оно не привязано к конкретному вендору и по возможности использует концепции OpenTelemetry. Также в него включены карта сигналов и решений, матрица приемочных тестов, семидневный план запуска, телеметрический контракт, шаблон инструментации, runbook для алертов и scorecard вендоров, чтобы команда могла перейти от требований к рабочему запуску.
AI Observability в одном предложении
AI observability — это способность объяснять поведение, качество, надежность, безопасность и стоимость AI-workflow на основе коррелированного набора трассировок, метрик, логов, оценок и пользовательских результатов.
Мониторинг сообщает, что порог изменился. Observability помогает понять, почему он изменился и какие запросы, модели, prompts, результаты retrieval, инструменты, tenants или релизы были задействованы.
Используйте чек-лист внедрения AI observability из этого руководства как gate для релиза, а не как разовую документационную задачу. Повторно проходите его каждый раз, когда меняете модель, prompt, retrieval index, схему инструмента, политику маршрутизации или evaluator.
Для AI-приложения один запрос может включать несколько отдельных попыток:
user action
└─ application workflow
├─ retrieval query
├─ model attempt 1
├─ tool call
├─ model attempt 2
└─ validation and user-visible result
Если эти шаги нельзя связать под одной трассировкой или идентичностью запроса, отладка превращается в гадание.
Минимальная модель данных для AI Observability
Модель данных — это основа чек-листа внедрения AI observability, потому что каждая панель, алерт, оценка и incident-запрос зависят от согласованных полей корреляции.
Начните с одной трассировки на уровне workflow и дочерних spans для каждой значимой операции. OpenTelemetry определяет traces, metrics, logs и baggage как основные сигналы. Его семантические соглашения для generative AI дают развивающийся словарь для операций модели и агента и, по состоянию на 4 августа 2026 года, поддерживаются в отдельном репозитории semantic conventions OpenTelemetry. Поскольку эти соглашения могут меняться, зафиксируйте версию, которую вы внедряете, и держите небольшой внутренний слой совместимости вместо того, чтобы разбрасывать vendor-specific имена полей по всему коду.
Как минимум, собирайте эти группы полей.
| Группа полей | Что записывать | Почему это важно |
|---|---|---|
| Correlation | trace_id, request_id, ID сессии, workflow, environment, release |
Объединяет полный путь запроса |
| Route | provider, requested model, resolved model, region, endpoint or route alias | Показывает, где фактически выполнялся запрос |
| Attempt | номер попытки, причина повтора, источник и назначение fallback | Отделяет один запрос пользователя от нескольких тарифицируемых вызовов |
| Performance | время в очереди, время до первого токена, общая задержка, задержка tool и retrieval | Позволяет найти медленный этап |
| Usage | input, cached input, output, reasoning или специфичные для провайдера поля usage | Объясняет нагрузку и стоимость |
| Result | status, нормализованный класс ошибки, причина завершения, результат валидации | Отличает успешную передачу данных от успешного выполнения задачи |
| Quality | версия evaluator, score, pass/fail, feedback пользователя, принятое outcome | Отслеживает, был ли ответ полезным |
| Governance | tenant, решение policy, статус redaction, класс retention | Поддерживает контроль конфиденциальности и аудит |
Не стоит считать raw prompt и response обязательными полями. Во многих системах их следует отключать по умолчанию или хранить только в отдельно контролируемом наборе данных для оценки.
Сопоставьте каждый сигнал с операционным решением
Больше телеметрии не всегда лучше. Прежде чем добавлять атрибут, метрику или дашборд, назовите решение, которое он поддерживает, и человека, который за это решение отвечает.
| Сигнал | На какой вопрос он отвечает | Типичное решение | Основной владелец |
|---|---|---|---|
| Accepted completion rate | Решил ли workflow задачу клиента? | Откатить, изменить prompt/model или расследовать downstream-сбои | Product and AI engineering |
| p95 end-to-end latency | Достаточно ли быстро работает полный пользовательский сценарий? | Изменить route, снизить задержку retrieval/tool или скорректировать streaming | Platform engineering |
| Time to first token | Насколько отзывчивым ощущается streaming? | Настроить очереди, provider route или размер prompt | Platform engineering |
| Fallback rate | Здоров ли основной route и экономичен ли он? | Проверить состояние provider, capacity или policy route | Reliability engineering |
| Cost per accepted outcome | Съедают ли retries и низкое качество экономию? | Изменить mix моделей, caching, размер prompt или validation | Engineering and FinOps |
| Retrieval grounding pass rate | Использовал ли ответ авторизованный, релевантный контекст? | Перестроить index, filters, reranker или validation цитирования | Search/RAG owner |
| Tool reconciliation failures | Завершилось ли внешнее side effect безопасно? | Приостановить tool, сверить state или исправить idempotency | Application owner |
| Redaction failure count | Попадают ли sensitive data в exporter? | Остановить export, поместить telemetry в quarantine или обновить policy | Security/privacy |
Эта таблица предотвращает типичный сценарий отказа, когда на дашборде десятки графиков, но никто не знает, какое действие должно запускать изменение.
Практическая форма трассировки
Используйте одну трассировку для пользовательского workflow, а не отдельную несвязанную трассировку для каждого вызова провайдера. Корень должен описывать задачу клиента, а дочерние span-ы — операции, которые повлияли на результат.
workflow: answer_support_question
attributes: tenant_class, release, accepted_outcome, final_status
├─ retrieval.search
│ attributes: index_version, top_k, authorization_result
├─ gen_ai.attempt
│ attributes: provider, requested_model, resolved_model, attempt=1
├─ tool.lookup_order
│ attributes: tool_schema_version, idempotency_key, result
├─ gen_ai.attempt
│ attributes: provider, resolved_model, attempt=2, fallback_reason
└─ evaluation.validate_answer
attributes: evaluator_version, pass, score_band
Семантические соглашения OpenTelemetry для генеративного AI все еще развиваются. Рассматривайте их как общий словарь, но фиксируйте версию соглашений, записывайте любые локальные расширения и тестируйте обновления в staging. Храните бизнес-результаты, такие как accepted_outcome, в собственном стабильном пространстве имен приложения, чтобы изменение семантических соглашений не ломало продуктовую отчетность.
Фаза 1: Определите результаты до добавления дашбордов
1. Назовите workflow и принятый результат
Не начинайте с общих для провайдера графиков по токенам. Начните с пользовательской задачи, такой как:
- ответ службы поддержки принят без эскалации;
- патч к коду проходит тесты;
- извлечение соответствует требуемой схеме;
- агент выполняет запрошенное действие без ручного восстановления;
- сгенерированный медиаконтент проходит этап проверки продукта.
Создайте машиночитаемое имя workflow и accepted_outcome или эквивалентный результат. Это станет знаменателем для метрик качества, стоимости и надежности.
2. Определите таксономию сбоев
Как минимум разделяйте следующие классы:
- сбой транспорта: таймаут, ошибка соединения или upstream 5xx;
- сбой емкости: лимит запросов, квота, насыщение очереди или ограничение контекста;
- сбой контракта: невалидный JSON, отсутствующее поле, неподдерживаемая схема инструмента или сломанный поток;
- сбой качества: ответ нерелевантен, неверен, неполон или не основан на данных;
- сбой безопасности: нарушение политики, успешная prompt injection или небезопасное выполнение инструмента;
- бизнес-сбой: технически корректный результат, который пользователь отклоняет или бросает.
Одного измерения error=true недостаточно. Оно скрывает, нужен ли вам апдейт инфраструктуры, изменение промпта, смена модели или изменение продукта.
3. Выберите начальные индикаторы уровня сервиса
Начните с небольшого набора, отражающего пользовательский опыт:
workflow availability = accepted workflow completions / eligible workflow starts
quality pass rate = evaluator-passing completions / evaluated completions
p95 end-to-end latency = p95(workflow completed - workflow started)
cost per accepted outcome = total workflow cost / accepted outcomes
Считайте доступность провайдера диагностической метрикой, а не SLI продукта. Провайдер может быть в порядке, в то время как ваш workflow ломается из-за сбоев в retrieval, tools, validation или routing.
Этап 2: Инструментируйте полный путь запроса
4. Создайте один корневой span для каждого видимого пользователю рабочего процесса
Создавайте корневой trace на границе приложения, до начала retrieval или model routing. Передавайте этот контекст через очереди, workers, gateways, tool services и callbacks.
Используйте дочерние spans для:
- retrieval и reranking;
- каждой попытки модели;
- каждого вызова инструмента;
- проверок guardrail или policy;
- парсинга и валидации вывода;
- выбора fallback;
- сохранения и доставки downstream.
5. Записывайте запрошенный и фактически выбранный маршрут
Модель, указанная клиентом, не всегда совпадает с моделью, которая обслужила запрос. Записывайте оба значения:
{
"ai.requested_model": "support-balanced",
"ai.resolved_provider": "provider-b",
"ai.resolved_model": "model-version-2026-07",
"ai.route_reason": "primary_rate_limited",
"ai.attempt": 2
}
Это критически важно для систем с несколькими провайдерами. Это также делает model fallback strategy поддающейся аудиту, а не невидимой.
6. Измеряйте потоковую передачу отдельно
Одна только общая задержка не описывает streaming-опыт. Фиксируйте:
- длительность очереди;
- задержку соединения и провайдера;
- время до первого токена или первого полезного события;
- длительность генерации;
- общее время завершения end-to-end;
- время отмены со стороны клиента.
Запрос может иметь приемлемую общую задержку, но плохое время до первого токена. Он также может быстро выдать первый токен, а затем зависнуть.
7. Считайте повторные попытки и fallback отдельными полноценными попытками
Никогда не перезаписывайте первую неудачную попытку финальным успехом. Один span workflow должен содержать или связываться с каждой оплачиваемой попыткой, включая:
- номер повтора;
- триггер;
- длительность backoff;
- провайдер и модель;
- токены и стоимость;
- статус частичного вывода;
- итоговое решение.
Это предотвращает то, что шторм повторных попыток выглядит как «100% success».
Этап 3: Добавьте контекст качества, специфичный для AI
8. Версионируйте prompts, инструменты, политики и оценщики
Сохраняйте стабильные идентификаторы, а не только сырой контент:
prompt_version
tool_schema_version
retrieval_index_version
policy_version
evaluator_version
route_policy_version
Эти измерения позволяют сравнивать релиз до и после изменения. Без версионирования снижение качества становится трудно атрибутировать.
9. Отслеживайте качество retrieval
Для retrieval-augmented generation записывайте:
- версию запроса и фильтры;
- задержку retrieval;
- document или chunk IDs;
- актуальность источника;
- top-k и версию reranker;
- частоту пустого результата;
- решение контроля доступа;
- результат проверки citation или grounding.
Не помещайте полные приватные документы в общее хранилище trace. Сохраняйте контролируемые ссылки или хэши, если политика отладки явно не разрешает захват содержимого.
10. Отслеживайте вызовы инструментов и побочные эффекты
Каждый span инструмента должен включать название инструмента, версию схемы, решение по авторизации, задержку, нормализованный результат и то, вызвал ли он внешнее побочное действие.
Для инструментов, вызывающих побочные эффекты, также фиксируйте idempotency key и состояние согласования. Это важно, когда вызов модели завершается по тайм-ауту после того, как инструмент уже завершил работу.
11. Объединяйте онлайн- и офлайн-оценки
Онлайн-сигналы быстрые, но шумные: палец вверх, отказ, повторная генерация, исправление, эскалация или завершение задачи. Офлайн-оценки медленнее, но контролируемые: curated test sets, рубрикаторы, исполняемые тесты и ручной review.
Свяжите оба типа с одними и теми же идентификаторами workflow и версии. Не смешивайте оценки из разных версий evaluator в одну линию тренда без указания изменения.
Фаза 4: Контролируйте конфиденциальность, безопасность и хранение
12. Классифицируйте телеметрию до сбора
Определите три уровня:
- Метаданные: маршрут, время, токены, статус, версии и ID.
- Производные сигналы контента: длина, язык, категория безопасности, оценка evaluator или хэш.
- Сырой контент: промпты, ответы, извлеченный текст, аргументы инструмента и результаты инструмента.
Собирайте метаданные широко. Собирайте сырой контент только тогда, когда это поддерживается вариантом использования, уведомлением пользователя, контролем доступа и политикой хранения.
13. Редактируйте на границе сбора
Редактирование должно происходить до экспорта, когда это возможно. Закрывайте:
- API-ключи, bearer tokens, cookies и заголовки авторизации;
- адреса электронной почты, номера телефонов, номера счетов и государственные идентификаторы;
- секреты внутри аргументов инструментов или извлеченных документов;
- signed URLs и строки подключения к базе данных;
- контент, специфичный для tenant'а, запрещенный к хранению в общих хранилищах observability.
Используйте allowlist для экспортируемых атрибутов. Denylist в конечном итоге пропустит новое поле, содержащее секрет. Применяйте ту же дисциплину, что описана в этом руководстве по управлению API-ключами в AI.
14. Настройте хранение и доступ по классу данных
Сырой контент не должен наследовать те же сроки хранения, что и метрики с низким риском. Определите отдельные хранилища, шифрование, роли доступа, журналы аудита и процессы удаления. Проверяйте удаление, а не исходите из того, что документа политики достаточно.
NIST AI Risk Management Framework и его Generative AI Profile подчеркивают непрерывное измерение, документирование и управление рисками на протяжении всего жизненного цикла системы. Observability помогает предоставить доказательства, но безразборное логирование может создать новый риск для конфиденциальности и безопасности.
15. Контролируйте измерения с высокой кардинальностью
Не превращайте user IDs, trace IDs, текст промпта, document IDs или сырые сообщения об ошибках в метки метрик. Храните данные с высокой кардинальностью в traces или logs, а затем выводите ограниченные метрики, такие как workflow, семейство модели, класс ошибки, среда и регион.
Фаза 5: Стройте алерты, которые указывают на действие
16. Настраивайте алерты на симптомы, влияющие на пользователя
Поднимайте страницу по таким симптомам, как:
- accepted completion rate ниже целевого значения;
- quality pass rate падает ниже release guardrail;
- p95 latency или time to first token съедают error budget;
- cost per accepted outcome превышает свой лимит;
- опасный side-effect или сбой policy;
- fallback rate растет выше своего нормального диапазона.
Используйте ошибки провайдера, всплески токенов и пропуски в retrieval как диагностические алерты или сигналы дашборда, если они напрямую не угрожают пользовательской цели.
17. Используйте окна burn rate для оповещений по SLO
Статический порог может быть шумным. Алертинг по burn rate error budget спрашивает, как быстро сервис расходует допустимый бюджет отказов. Рекомендации Google SRE советуют сочетать более короткое окно с более длинным окном подтверждения, чтобы серьезные инциденты быстро попадали в paging, не делая каждый краткий всплеск actionable.
18. Добавляйте аннотации релизов и маршрутов
Каждый дашборд должен показывать релизы prompt, приложения, маршрутизации, модели и evaluator. Добавляйте аннотации деплоя и сравнивайте канареечные и контрольные когорты. Иначе команда увидит, что линия изменилась, не понимая, что именно изменилось.
Этап 6: Проведите проверку перед полным развертыванием
19. Проводите учения по отказам
Проверьте как минимум:
- тайм-аут upstream;
- превышение rate limit и исчерпание quota;
- некорректный structured output;
- частичное прерывание streaming;
- retrieval не возвращает авторизованный контекст;
- tool успешно отрабатывает, но response теряется;
- fallback меняет поведение модели;
- telemetry exporter недоступен;
- правило redaction получает неизвестное поле.
Подтвердите, что workflow безопасно завершается с ошибкой, trace остается согласованным, а alert указывает на нужного владельца.
20. Выполняйте развертывание в четыре этапа
- Shadow: отправляйте telemetry без изменения routing или поведения пользователя.
- Canary: включите для небольшой доли трафика и сравните overhead, cardinality и качество данных.
- Guarded production: задайте пороги релиза и правила отката.
- Full production: расширяйте после прохождения проверок на privacy, reliability и cost.
OpenTelemetry поддерживает шаблоны head и tail sampling. По возможности сохраняйте все ошибки и редкие классы отказов, затем сэмплируйте обычный успешный трафик, чтобы контролировать cost. Правила sampling не должны удалять именно те trace, которые нужны для объяснения инцидента.
Production Acceptance-Test Matrix
Acceptance tests доказывают, что AI observability implementation checklist работает в сценариях с отказами, privacy и потерей telemetry, а не только на успешных запросах.
Не объявляйте observability завершенной только потому, что spans отображаются в trace viewer. Проводите контролируемые тесты и сохраняйте evidence для каждого release gate.
| Тест | Внедрённое условие | Необходимые доказательства телеметрии | Условие прохождения |
|---|---|---|---|
| Тайм-аут upstream | Принудительно превысить дедлайн основного маршрута модели | Спан первой попытки, класс тайм-аута, решение о ретрае или fallback, итоговый результат | Нет осиротевших спанов; видны итоговое решение и общая стоимость |
| Ограничение по rate limit | Вернуть 429 от провайдера или исчерпать тестовую квоту | Исходный код провайдера, нормализованный класс capacity, длительность backoff, смена маршрута | Бюджет ретраев ограничен, а алерт указывает на владельца маршрута |
| Некорректный структурированный вывод | Вернуть некорректный JSON или отсутствующее обязательное поле | Спан проверки контракта, версия валидатора, попытка исправления, итоговый pass/fail | HTTP success не засчитывается как принятый success |
| Сломанный stream | Прервать вывод после первого токена | Время до первого токена, флаг частичного вывода, оплачиваемое использование, решение о ретрае | Дублирование контента и двойное выполнение tool предотвращены |
| Пустой retrieval | Вернуть ни одного авторизованного документа | Фильтры retrieval, результат авторизации, причина пустого результата, политика ответа | Система следует утверждённому поведению без контекста |
| Неоднозначность tool | Дать tool завершиться, пока запрос модели истекает по тайм-ауту | Ключ идемпотентности, состояние side-effect, результат согласования | Tool не выполняется дважды, а состояние можно восстановить |
| Redaction canary | Вставить синтетический секрет в тестовое поле | Локальное событие обнаружения без экспортированного значения секрета | Экспорт блокируется или редактируется до выхода за границу |
| Сбой exporter | Остановить destination телеметрии | Метрики очереди/потерь exporter и состояние приложения | Пользовательский трафик остаётся в пределах своего reliability budget |
| Проверка sampling | Сгенерировать редкие ошибки на фоне высокого успешного трафика | Трейсы ошибок сохранены; обычные успешные запросы sample-ятся согласно настройке | Примеры инцидентов остаются доступными для поиска после sampling |
| Регрессия релиза | Развернуть canary с известным ухудшением задержки или качества | Аннотация релиза, canary cohort, control cohort, сравнение SLI | Порог отката срабатывает с определяемым владельцем изменения |
Для каждого теста фиксируйте владельца, дату теста, trace ID, ожидаемый alert, наблюдаемый alert и тикет на исправление. Это превращает observability в повторяемый контроль релиза, а не в одноразовый проект по инструментированию.
План внедрения на семь дней
Для сфокусированной команды чек-лист внедрения AI observability можно реализовать как последовательность на семь дней, где каждый день завершается проверяемыми доказательствами.
Эта последовательность намеренно узкая. Она даёт надёжный вертикальный срез до того, как команда расширит покрытие.
- День 1 — Контракт на результат: выберите один высокоценный рабочий процесс, определите допустимые точки старта, принимаемые результаты, классы отказов и формулы SLI.
- День 2 — Каркас трассировки: создайте корневой спан рабочего процесса и передавайте контекст через приложение, очередь, шлюз, слой retrieval и инструменты.
- День 3 — Попытки модели: фиксируйте запрошенные и разрешенные маршруты, попытки, задержку, причину завершения, использование провайдера, повторы и fallback-сценарии.
- День 4 — Качество и стоимость: объедините результаты валидатора, версии оценщиков, пользовательские исходы и нормализованную стоимость рабочего процесса.
- День 5 — Контроль конфиденциальности: классифицируйте поля, реализуйте экспорт по allowlist, протестируйте редактирование/маскирование, задайте срок хранения и проверьте границы доступа.
- День 6 — SLO и дашборды: соберите минимальный дашборд, добавьте аннотации релизов, определите alert'ы по burn rate и назначьте ответственных.
- День 7 — Учения по сбоям: прогоните матрицу приемки, устраните пробелы, запустите canary и задокументируйте условия отката.
К концу седьмого дня цель — не универсальная инструментация. Цель — один production-рабочий процесс, поведение, качество, надежность, безопасность и стоимость которого можно объяснить от начала до конца.
Минимальный дашборд для запуска
Дашборд — это операционный взгляд на чек-лист внедрения AI Observability. В нем сначала должны быть показаны пользовательские результаты, а уже затем детали инфраструктуры.
Сделайте первый операционный вид достаточно компактным, чтобы использовать его во время инцидента:
- Строка результатов: допустимые старты, принятые завершения, доля успешных прохождений качества и отказы/эскалации.
- Строка надежности: нормализованные ошибки, доля fallback-сценариев, усиление из-за повторов и расход бюджета ошибок.
- Строка задержек: end-to-end p50/p95/p99, время в очереди, время до первого токена, задержка retrieval и задержка инструментов.
- Строка экономики: input/output/cached токены, общая стоимость рабочего процесса и стоимость на один принятый результат.
- Строка изменений: релизы приложения, prompt'а, политики маршрутизации, модели, retrieval-индекса, схемы инструмента и оценщика.
- Ссылки для расследования: репрезентативные трассы для каждого класса отказов, релиза, маршрута и затронутого рабочего процесса.
Дашборд должен поддерживать путь от симптома к трассе. Если alert показывает падение качества, но команда не может в несколько кликов перейти к трассам затронутого рабочего процесса, цикл расследования неполный.
Оценочная матрица для проверки платформ AI Observability
Коммерческая оценка должна проверять, поддерживает ли платформа вашу операционную модель, а не то, есть ли у нее самый длинный список функций. Оценивайте кандидатов на одном и том же инструментированном пилотном рабочем процессе.
| Критерий | Вес | Что проверить в пилоте |
|---|---|---|
| Корреляция workflow | 20% | Один trace связывает попытки модели, retrieval, инструменты, валидацию и результат пользователя |
| Совместимость с OpenTelemetry | 15% | Стандартный экспорт/импорт работает; локальные расширения остаются доступны для запросов; данные переносимы |
| Связки качества и оценки | 15% | Онлайн-обратная связь и версионированные офлайн-оценки связаны с production trace |
| Конфиденциальность и governance | 15% | Allowlist полей, редактирование, региональные ограничения, роли доступа, audit logs и тесты удаления |
| Операции по надежности | 15% | SLO, алерты по burn rate, контроль семплирования, аннотации релизов и поддержка учений по инцидентам |
| Атрибуция затрат | 10% | Использование провайдера, повторы, fallback, кэшированные токены и стоимость на принятый результат сходятся |
| Покрытие Agent/RAG/tool | 5% | Операции retrieval и инструменты с побочными эффектами имеют spans и фильтры первого класса |
| Операционные затраты | 5% | Ingestion, storage, query, retention и инженерные накладные расходы соответствуют ожидаемому объему |
Используйте оценку от 1 до 5 для каждого критерия, умножайте на вес и требуйте письменные доказательства из пилота. Платформа, которая не может сохранить ваш telemetry contract или экспортировать ваши данные, создает операционный lock-in, даже если ее дашборды выглядят отполированными.
Copyable Telemetry Contract
Самый быстрый способ сделать AI observability implementation checklist рабочим — превратить его в версионируемый telemetry contract. Контракт определяет, что должен отправлять каждый workflow и каждая попытка модели, какие поля являются необязательными, какие значения разрешены и какие поля запрещено включать в индексы с высоким объемом.
Пример ниже использует внутреннее пространство имен. Сопоставьте его с закрепленными соглашениями OpenTelemetry GenAI внутри одного адаптера, а не заставляйте код приложения следить за изменениями соглашений.
telemetry_contract:
version: "2026-08-04"
workflow_span:
required:
- ai.workflow.name
- ai.workflow.version
- ai.request.id
- deployment.environment
- service.version
- ai.outcome.status
- ai.outcome.accepted
- ai.latency.total_ms
optional:
- ai.tenant.tier
- ai.experiment.id
- ai.user.feedback
prohibited:
- end_user.email
- end_user.name
- raw.authorization_header
model_attempt_span:
required:
- ai.attempt.number
- ai.route.requested_model
- ai.route.resolved_provider
- ai.route.resolved_model
- ai.result.status
- ai.usage.input_tokens
- ai.usage.output_tokens
- ai.latency.first_token_ms
- ai.latency.total_ms
conditional:
- ai.fallback.reason
- ai.error.class
- ai.error.provider_code
- ai.usage.cached_input_tokens
content_capture:
default: "off"
allowed_when:
- approved_evaluation_dataset
- explicit_debug_session
controls:
- redact_before_export
- access_logged
- retention_approved
Проверяйте этот контракт в code review так же, как API schema. Новый провайдер модели, инструмент агента, политика fallback или evaluator не должны попадать в продакшен, пока их поля telemetry не будут сопоставлены с контрактом и не пройдут те же acceptance tests.
Instrumentation Pattern for One AI Workflow
Не позволяйте каждой команде самостоятельно придумывать имена span и attributes. Предоставьте небольшой wrapper, который создаёт root workflow span, записывает дочерние попытки, фиксирует нормализованные outcomes и применяет redaction перед export.
Этот пример на Python намеренно не привязан к конкретному provider. Внутренние имена attributes следует перевести на закреплённую версию semantic convention OpenTelemetry в wrapper или collector layer.
from opentelemetry import trace
tracer = trace.get_tracer("checkout-assistant")
def run_ai_workflow(request, router, evaluator):
with tracer.start_as_current_span("ai.workflow.checkout_help") as workflow_span:
workflow_span.set_attribute("ai.workflow.name", "checkout_help")
workflow_span.set_attribute("ai.workflow.version", "2026-08-04")
workflow_span.set_attribute("ai.request.id", request.request_id)
result = None
for attempt_number in range(1, 3):
with tracer.start_as_current_span("ai.model.attempt") as attempt_span:
route = router.resolve(request, attempt_number)
attempt_span.set_attribute("ai.attempt.number", attempt_number)
attempt_span.set_attribute("ai.route.requested_model", request.model)
attempt_span.set_attribute("ai.route.resolved_provider", route.provider)
attempt_span.set_attribute("ai.route.resolved_model", route.model)
result = route.generate(request)
attempt_span.set_attribute("ai.result.status", result.status)
attempt_span.set_attribute("ai.usage.input_tokens", result.input_tokens)
attempt_span.set_attribute("ai.usage.output_tokens", result.output_tokens)
if result.status == "ok":
break
attempt_span.set_attribute("ai.error.class", result.error_class)
evaluation = evaluator.score(request, result)
workflow_span.set_attribute("ai.outcome.status", result.status)
workflow_span.set_attribute("ai.outcome.accepted", evaluation.accepted)
workflow_span.set_attribute("ai.evaluator.version", evaluation.version)
workflow_span.set_attribute("ai.quality.score", evaluation.score)
return result
Production code should also record duration, time to first token, fallback reasons, cancellation, streaming errors, and exceptions. The important design choice is the hierarchy: one customer workflow contains one or more billable attempts, and the workflow records the final accepted outcome.
Alert Policy and First-Response Runbook
Чек-лист внедрения AI observability неполон, если у dashboards нет правил реагирования. Каждой launch metric нужен триггер, владелец и первый диагностический запрос.
| Сигнал | Пример триггера | Первый вопрос | Немедленное действие |
|---|---|---|---|
| Burn для принятого исхода | Быстрое и медленное выгорание error budget | Какой workflow, релиз, маршрут или tenant изменился? | Приостановить rollout или откатить затронутый релиз |
| Регрессия задержки | Задержка workflow по p95 нарушает SLO | Изменилась ли задержка очереди, retrieval, модели или tool? | Обойти медленный этап или снизить нагрузку |
| Всплеск fallback | Fallback rate превышает нормальный диапазон | Первичный провайдер дает сбои, троттлит или не отвечает по таймауту? | Проверить нормализованные и исходные ошибки провайдера |
| Всплеск cost-per-outcome | Стоимость растет, а acceptance остается на месте или падает | Увеличились ли retries, длина вывода или дорогие маршруты? | Ограничить retries и восстановить предыдущую политику маршрутизации |
| Падение quality-score | Снижается pass rate онлайн-оценщика или выборочной проверки | Изменились ли prompt, retrieval, model или версия evaluator? | Сравнить cohort релиза с последним стабильным cohort |
| Неопределенность tool | Результат побочного эффекта не удается согласовать | Завершился ли tool до timeout или отмены? | Остановить автоматический retry и перейти к reconciliation |
| Потеря телеметрии | Падает полнота ожидаемых span или usage | Сломалась ли instrumentation или растет backpressure на export? | Рассматривать отсутствующую телеметрию как операционный инцидент |
Представление для on-call должно вести напрямую от сигнала к trace, отфильтрованным по workflow, релизу, запрошенной модели, разрешенному маршруту и классу ошибки. Если реагирующие на инцидент должны вручную восстанавливать эти фильтры во время инцидента, система не готова к запуску.
Ответственность и передача в продакшен
Назначьте чек-лист на конкретные роли до rollout. Совместная ответственность без явного принимающего решения обычно приводит к дашбордам, которые все могут видеть, но никто не поддерживает.
| Ответственность | Ответственная роль | Требуемое подтверждение передачи |
|---|---|---|
| Определение исхода workflow | Владелец продукта или AI-функции | Правило принятого исхода и примеры отклонения |
| Схема span и метрик | Владелец платформы или observability | Версионированный контракт телеметрии и тесты схемы |
| Поля маршрута и fallback | Владелец gateway или надежности | Проверка запрошенного/разрешенного маршрута и попыток |
| Оценщики качества | Владелец AI engineering | Версия evaluator, датасет, пороги, известные ограничения |
| Конфиденциальность и хранение | Владелец безопасности или privacy | Классификация данных, тест редактирования, утверждение retention |
| SLO и алерты | Владелец сервиса | Документ SLO, правила paging, dashboard, runbook |
| Распределение затрат | Владелец инженерных финансов | Полнота usage и сверка cost-per-outcome |
| Готовность к релизу | Инженерный лидер | Заполненная матрица приемки и триггер rollback |
Запланируйте обзор через 30 дней после запуска. Удалите неиспользуемые поля, переводите часто полезные отладочные запросы в представления дашборда, пересматривайте кардинальность и стоимость хранения, а также обновляйте контракт при изменении поведения workflow.
Copyable AI Observability Implementation Checklist
Используйте этот список как gate для запуска:
- [ ] Определите каждый workflow и приемлемый результат для клиента.
- [ ] Определите транспортные, емкостные, контрактные, качественные, безопасностные и бизнес-сбои.
- [ ] Выберите SLI для доступности, качества, задержки и стоимости на результат.
- [ ] Утвердите версионированный контракт телеметрии с обязательными, необязательными и запрещенными полями.
- [ ] Создайте один root trace для каждого пользовательски видимого workflow.
- [ ] Передавайте context через очереди, инструменты, retrieval и gateways.
- [ ] Записывайте запрошенные и разрешенные маршруты provider/model.
- [ ] Создавайте отдельный span для каждой попытки retry и fallback.
- [ ] Снимайте время в очереди, time to first token и общую задержку.
- [ ] Снимайте объем токенов, сообщаемый provider, и нормализованную стоимость.
- [ ] Версионируйте prompts, tools, retrieval indexes, policies, routes и evaluators.
- [ ] Записывайте ссылки retrieval, свежесть, авторизацию и результаты grounding.
- [ ] Записывайте авторизацию tool, idempotency, результат и состояние side-effect.
- [ ] Связывайте отзывы пользователей и результаты offline evaluation с trace.
- [ ] Классифицируйте телеметрию как metadata, derived signals или raw content.
- [ ] Маскируйте secrets и чувствительные поля перед экспортом.
- [ ] Применяйте отдельные политики хранения и доступа для каждого класса данных.
- [ ] Не включайте значения с высокой кардинальностью в metric labels.
- [ ] Настраивайте alert для SLO, влияющих на пользователей, и burn error budget.
- [ ] Аннотируйте релизы и сравнивайте canary с control.
- [ ] Проводите drills по отказам, privacy, sampling и сбоям exporter.
- [ ] Сохраняйте evidence acceptance-test и trace ID для release gate.
- [ ] Сравнивайте observability platform с одной взвешенной pilot scorecard.
- [ ] Назначьте ответственных владельцев за outcomes, schema, privacy, SLO, quality и cost.
- [ ] Связывайте каждое page-worthy alert с runbook первой реакции и trace query.
Common AI Observability Mistakes
Logging prompts without a data policy
Raw prompts могут быть полезны во время отладки, но они могут содержать данные клиентов, secrets, материалы, защищенные авторским правом, или регулируемую информацию. Начните с metadata и включайте контролируемый сбор content только там, где это оправдано.
Measuring cost per request instead of cost per result
Дешевый запрос, который не проходит validation, не является дешевым. Retry, fallback и human correction должны учитываться в стоимости workflow. Тот же принцип применим к ROI prompt caching: оптимизируйте принятый task, а не изолированную token rate.
Treating every model call as independent
Agents и RAG systems — это workflow. Если spans model, retrieval и tool не коррелируются, команда не сможет восстановить causality.
Depending on one provider dashboard
Provider dashboards полезны для upstream usage и ошибок, но они не видят полный outcome приложения, retrieval system, выполнение tool, feedback пользователя или cross-provider fallback path.
Instrumenting everything before defining decisions
Телеметрия имеет операционные затраты. Каждое поле должно поддерживать решение по отладке, оповещению, оценке, управлению или оптимизации. Удаляйте поля, которыми никто не пользуется.
Where an AI Gateway Fits
LLM gateway может быть полезной границей для корреляции и политик, поскольку через одну точку управления проходят несколько приложений и провайдеров. Он может нормализовать метаданные о маршруте, попытке, использовании, задержке и ошибках перед экспортом телеметрии в ваш стек observability.
Gateway — это не все решение целиком. Код приложения по-прежнему отвечает за результаты workflow, контекст retrieval, семантику инструментов, feedback пользователей и бизнес-конверсию. Наиболее сильная архитектура объединяет телеметрию gateway с этими сигналами на уровне приложения.
Flatkey предоставляет один OpenAI-compatible слой доступа для нескольких AI моделей. Если ваша команда консолидирует интеграции с провайдерами, изучите Flatkey и используйте этот чек-лист, чтобы определить контракт телеметрии вокруг вашего приложения и слоя маршрутизации.
Frequently Asked Questions
What should I implement first for AI observability?
Начните чек-лист внедрения AI observability с одного root trace на каждый customer workflow, child spans для попыток модели, полей запрошенной и фактически использованной модели, задержки, использования, нормализованных ошибок и сигнала о принятом результате. Добавьте захват raw prompt позже, если ваша политика конфиденциальности это позволяет.
Is OpenTelemetry enough for LLM observability?
OpenTelemetry предоставляет transport-neutral основу для traces, metrics и logs, а также развивающиеся semantic conventions для generative AI. Вам все равно нужны определения workflow, evaluations, controls конфиденциальности, SLOs, dashboards и incident processes.
Should prompts and responses be stored in traces?
Не по умолчанию. Сначала используйте metadata, версии, hashes и производные сигналы качества. Храните raw content только в контролируемых системах с явной целью, policy доступа, сроком retention и процессом удаления.
Which AI observability metrics matter most?
Начните с accepted completion rate, quality pass rate, p95 end-to-end latency, времени до первого token для streaming, fallback rate и cost per accepted outcome. Добавляйте workflow-specific метрики после того, как эти показатели станут надежными.
How do I monitor multiple AI providers?
Используйте одну стабильную схему телеметрии для всех providers. Записывайте и запрошенный route, и фактически resolved provider/model в каждой попытке, нормализуйте errors, не отбрасывая raw provider code, и объединяйте все попытки под одним workflow trace.
