Reliability and Routing22 июня 2026 г.Big Y

Логи наблюдаемости AI API: что фиксировать для инцидентов маршрутизации моделей

Используйте логи наблюдаемости AI API, чтобы разбирать инциденты маршрутизации моделей по request ID, маршрутам, повторам, fallback, токенам, задержке, стоимости и privacy-safe метаданным.

Наблюдаемость AI API — это то, что позволяет инженерной команде восстановить инцидент с маршрутизацией модели без догадок. Пользователь сообщает о тайм-ауте, резервная модель отвечает иначе, провайдер возвращает 429, или расходы резко растут после переключения на вышестоящем уровне. Разбор инцидента требует большего, чем просто сырой prompt и код статуса. Нужна запись лога, которая показывает запрос, маршрут, цепочку повторных попыток, выбранную модель, профиль задержек, использование, стоимость и средства защиты конфиденциальности вокруг того, что было сохранено.

Это руководство — чек-лист по полям для логов наблюдаемости AI API в инцидентах маршрутизации. Оно написано для команд, использующих AI gateway, маршрутизатор с несколькими провайдерами или слой совместимости, где один запрос приложения может пройти через несколько возможных вышестоящих путей. Цель не в том, чтобы хранить каждый prompt вечно. Цель — сохранять достаточно метаданных, чтобы доказать, что произошло, при этом удерживая под контролем чувствительные входные данные, выходные данные, аргументы инструментов и идентификаторы клиентов.

Flatkey подходит для этой задачи, потому что в его публичных материалах акцент сделан на одном API-ключе, базе URL, совместимой с OpenAI, по адресу https://router.flatkey.ai/v1, едином биллинге и одной панели для ключей, использования и маршрутизации. Flatkey также упоминает автоматическое переключение и балансировку нагрузки между вышестоящими аккаунтами. Это полезные функции надежности только тогда, когда логи позволяют постфактум ответить на вопрос о маршрутизации.

Наблюдаемость AI API начинается с вопросов к инциденту

Прежде чем выбирать поля, определите вопросы, на которые должен ответить руководитель инцидента. Для маршрутизации моделей наблюдаемость AI API должна позволять ответить на эти вопросы по одной записи запроса или одной связанной трассировке:

Какое приложение, окружение, команда, ключ, рабочий процесс и безопасный для клиента владелец отправили запрос?
Какое семейство endpoint'ов, запрошенная модель, политика маршрутизации и правило fallback применялись в момент запроса?
Какой провайдер, модель, upstream-аккаунт или маршрут фактически обслужили ответ?
Был ли запрос повторно отправлен, переключён, ограничен по скорости, поставлен в очередь, заблокирован или прерван?
Какой код статуса, класс ошибки провайдера, заголовок rate-limit, тайм-аут или событие потока изменили результат?
Сколько было посчитано токенов входа, выхода, кэша и reasoning, и сколько стоил маршрут?
Сохраняли ли настройки приватности сырые payload'ы, отредактированные payload'ы, только метаданные или вообще не создавали запись журнала?

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

Контрольный список журнала инцидентов маршрутизации модели

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

Группа полей	Поля для сбора	Почему это важно при инциденте маршрутизации	Примечание о конфиденциальности
Correlation IDs	ID запроса приложения, `X-Client-Request-Id`, `x-request-id` провайдера, W3C `traceparent`, ID лога шлюза, ID события.	Связывает ошибку, видимую пользователю, решение шлюза, запрос к провайдеру, span трассировки и тикет в поддержку.	Используйте непрозрачные ID. Не кодируйте email, IP, имя арендатора или текст промпта в полях трассировки.
Арендатор и владелец	Проект, среда, ID или хэш API-ключа, команда, workflow, безопасный для клиента ID аккаунта, центр затрат.	Показывает, кто был затронут и кто отвечает за квоту, затраты и устранение.	Предпочитайте стабильные внутренние ID вместо исходных имён клиентов или email пользователей.
Запрошенный маршрут	Семейство endpoint, запрошенная модель, предпочтение провайдера, политика маршрута, политика fallback, версия алиаса модели, версия каталога/ценообразования.	Восстанавливает, что запросил клиент и что роутеру было разрешено делать в тот момент.	Не включайте промпты в объект маршрута, если только не активен отдельно одобренный режим отладки.
Выбранный маршрут	Итоговый провайдер, итоговая модель, upstream-аккаунт или канал, регион, если уместно, причина решения маршрута, ID правила политики.	Доказывает, обслуживала ли ответ основная модель или путь fallback изменил поведение или стоимость.	Идентификаторы аккаунтов должны быть внутренними ссылками, а не секретами провайдера или полными учётными данными.
Цепочка повторных попыток и fallback	Индекс попытки, количество повторов, предыдущий провайдер/модель, класс сбоя, код статуса, цель fallback, итоговый результат.	Предотвращает слепые повторы и показывает, сработала ли лестница failover так, как задумано.	Храните класс ошибки и безопасные фрагменты. Избегайте сохранения полных тел ошибок провайдера, если они могут повторять содержимое промпта.
Задержка и streaming	Время начала запроса, длительность шлюза, длительность провайдера, время до первого токена/фрагмента, начало стрима, завершение стрима, причина прерывания, отключение клиента.	Разделяет задержку провайдера, время маршрутизации шлюза, зависание стрима и отмену на стороне клиента.	Фрагменты стрима — это контент. По умолчанию логируйте метаданные времени, а контент — только в управляемом режиме отладки.
Использование и стоимость	Входные токены, выходные токены, кэшированные токены, токены рассуждений, единицы изображений/видео, если применимо, количество запросов, строка счета, оценочная или итоговая стоимость.	Объясняет влияние на бюджет, когда fallback переводит трафик к другому провайдеру, модели или уровню сервиса.	Для обычных дашбордов агрегируйте по ключу, workflow и команде; ограничьте представления на уровне пользователя.
Форма ответа	Причина завершения, ID/имена tool call, тип вывода, статус ответа, сведения об усечении или incomplete, уровень сервиса.	Показывает, завершилась ли модель нормально, вызвала ли инструмент, достигла ли лимита или вернула неполный ответ.	Аргументы и результаты инструментов могут содержать чувствительные данные. По умолчанию храните ID и имена.
Ошибки и rate limits	HTTP status, код ошибки провайдера, класс таймаута, retry-after, заголовки remaining/limit/reset request, заголовки remaining/limit/reset token.	Различает некорректные запросы, сбои аутентификации, инциденты провайдера, исчерпание квоты и всплески rate limit.	Нормализуйте ошибки провайдера в безопасные классы перед отправкой в широкие аналитические инструменты.
Управление и хранение	Действие DLP, ID политики, режим логирования контента, флаг redaction, хэш payload, класс хранения, право на удаление.	Позволяет безопасности и compliance проверить, почему контент был сохранён, редактирован, заблокирован или исключён.	По умолчанию используйте логи только с метаданными, если сырой контент не требуется для определённого workflow поддержки или аудита.

Сначала зафиксируйте ID, а уже потом отлаживайте провайдера

Первая задача наблюдаемости AI API — корреляция. В справке по API OpenAI рекомендуется логировать идентификаторы запросов в production и документируются как значения x-request-id, генерируемые провайдером, так и значения X-Client-Request-Id, переданные вызывающей стороной. Последнее особенно важно, когда тайм-аут или сбой сети не позволяет вашему клиенту получить заголовки ответа провайдера.

Для gateway добавьте ещё один уровень: идентификатор запроса gateway, который сохраняется при внутренних повторных попытках и fallback. Если один пользовательский запрос сначала обращается к провайдеру A, затем к провайдеру B и, наконец, к резервной модели, ID gateway должен связывать все попытки между собой. ID запроса провайдера должен оставаться привязанным к конкретной попытке. Trace ID должен связывать этот вызов AI с остальной частью запроса приложения.

W3C Trace Context определяет traceparent и tracestate для передачи контекста распределённой трассировки между сервисами. Используйте эти заголовки для корреляции трассировки, а не для идентификации клиента. Раздел W3C о конфиденциальности говорит прямо: поля трассировки не должны содержать персональные или иные чувствительные данные.

Регистрируйте запрошенный маршрут и выбранный маршрут отдельно

Распространённая ошибка в мониторинге AI gateway — логировать только конечного провайдера и модель. Так теряется самое важное доказательство маршрутизации: что запросил клиент и что разрешила политика до того, как шлюз принял решение.

Держите эти два объекта отдельно:

Запрошенный маршрут: семейство endpoint, запрошенная модель или алиас, политика маршрута, предпочтение провайдера, политика fallback, версия каталога, версия ценообразования и режим запроса, например streaming или batch.
Выбранный маршрут: конечный провайдер, конечная модель, upstream account или канал, регион, когда это уместно, причина решения маршрутизации и ID правила политики.

Такое разделение важно, когда ответ по fallback допустим, но неожиданен. Если запрошенный маршрут был chat/completions с включённым streaming, а выбранный маршрут после тайм-аута переключился на другую модель, разбор инцидента сможет увидеть и исходный путь, и фактический путь. Это также помогает финансам понять, почему использование отразилось под другой моделью или статьёй.

Покупателям Flatkey стоит применять тот же подход к оценке. Начните с чек-листа требований к AI API gateway, затем используйте плейбук по балансировке нагрузки и failover, чтобы определить, какие изменения маршрута разрешены, прежде чем просматривать журналы.

Записывайте цепочку повторных попыток и резервного перехода

Повторные попытки — это то место, где неполные журналы становятся дорогими. Если единственные сохраняемые поля — это итоговый статус и итоговая модель, команда не сможет понять, был ли запрос выполнен с первой попытки, после одной повторной попытки или после пяти попыток у разных провайдеров. Наблюдаемость AI API уровня инцидентов рассматривает повторные попытки и резервный переход как цепочку.

Каждая попытка должна включать:

Индекс попытки и идентификатор родительского запроса шлюза.
Провайдер, модель, upstream-аккаунт и семейство конечных точек для этой попытки.
Время начала, длительность, класс тайм-аута и состояние потоковой передачи.
Код статуса, класс ошибки провайдера, идентификатор запроса провайдера и метаданные ограничения по скорости.
Целевой fallback и причина решения, если попытка не завершает цепочку.

Эта цепочка не позволяет шлюзу скрывать реальные сценарии отказов. Некорректный запрос должен завершаться с ошибкой, а не проходить по кругу через провайдеров. Ошибка 500 у провайдера может оправдывать одну повторную попытку. Ограничение квоты может переключать на одобренный upstream-аккаунт. Несоответствие модели для клиента может требовать контролируемой ошибки, а не тихого fallback.

Измеряйте задержку для потоков, а не только для завершенных вызовов

Потоковые ответы требуют большего, чем просто общая длительность. В документации по observability AI Gateway от Vercel отмечаются время до первого токена, длительность запроса, количество токенов и расходы как метрики шлюза. Семантические соглашения GenAI от OpenTelemetry включают gen_ai.response.time_to_first_chunk и gen_ai.request.stream. Эти поля полезны, потому что многие инциденты маршрутизации — это инциденты потоковой передачи: провайдер принял запрос, первый фрагмент пришел поздно, поток завис или клиент отключился.

Как минимум, логируйте время начала запроса, длительность работы шлюза, длительность работы провайдера, время до первого токена или фрагмента, флаг запуска потока, флаг завершения потока, причину прерывания и состояние отключения клиента. Для непотоковых ответов те же поля могут оставаться null или false. Это позволяет использовать одну схему для Chat Completions, Responses и семейств конечных точек, специфичных для провайдера.

По умолчанию не храните фрагменты потока. Фрагменты потока — это содержимое ответа, а содержимое ответа может включать пользовательские данные, извлеченный контекст, результаты инструментов или регулируемую информацию. Для обычного AI API observability временных метаданных обычно достаточно, чтобы диагностировать зависание.

Свяжите использование и стоимость с решением о маршрутизации

Использование и стоимость — это инцидентные поля, а не только финансовые поля. Примеры OpenAI для Responses API включают входные данные, выходные данные, кэшированные, рассуждения и общее использование токенов. Эндпоинт OpenAI для использования организации поддерживает группировку по проекту, пользователю, API-ключу, модели, batch и уровню сервиса; эндпоинт затрат поддерживает группировку по проекту, строке позиции и API-ключу. Документация Vercel по AI Gateway аналогично описывает сводки запросов по проекту и API-ключу, количество токенов, P75 duration, P75 TTFT и стоимость.

Для наблюдаемости AI API фиксируйте использование и стоимость на уровне попытки, когда это возможно, и всегда на уровне финального запроса. Резервный вариант может быть операционно корректным и финансово неожиданным. Без модели, маршрута, использования и стоимости в одном событии финансовый отдел может увидеть скачок расходов раньше, чем инженеры смогут его объяснить.

Публичные цены Flatkey и текст на главной странице указывают на прозрачное ценообразование, единый биллинг, аналитику использования и панель для ключей, использования и маршрутизации. Снимок цен от 18 июня 2026 года, сохранённый для этой задачи, вернул 638 строк моделей, 23 вендора и семейства эндпоинтов, включая OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini generateContent, генерацию изображений и OpenAI video. Рассматривайте эти числа как устаревшее свидетельство, а затем проверьте живую страницу цен и записи панели для конкретных моделей в вашем рабочем процессе.

Используйте журналирование только метаданных по умолчанию

Сырые промпты и ответы — мощные инструменты отладки, но это также и рискованные логи. Документация Cloudflare AI Gateway по логированию — полезный ориентир: в ней описываются журналы запросов с промптом, ответом, провайдером, временной меткой, статусом, использованием токенов, стоимостью, длительностью и user agent, а также документируется заголовок, который может подавлять хранение сырых тел запроса и ответа, сохраняя при этом метаданные, такие как количество токенов, модель, провайдер, код статуса, стоимость и длительность.

Это правильная настройка по умолчанию для логов LLM API: собирать метаданные по умолчанию, а затем требовать явного режима отладки или процедуры поддержки, прежде чем будет сохраняться сырое содержимое. Семантические конвенции OpenTelemetry GenAI помечают входные сообщения, выходные сообщения, системные инструкции, аргументы вызовов инструментов и результаты вызовов инструментов как поля, которые могут содержать конфиденциальную информацию. Ваша политика логирования должна это отражать.

Практическая политика имеет четыре режима:

Нет логов: используется для запросов, которые не должны сохраняться дольше, чем требуется для транзитной обработки.
Только метаданные: маршрут, ID, задержка, статус, использование, стоимость и флаги редактирования.
Редактированная полезная нагрузка: выбранные поля запроса/ответа после удаления ПДн и секретов.
Сырая полезная нагрузка: краткоживущий, ограниченный доступом отладочный захват для конкретного инцидента или случая поддержки, одобренного клиентом.

Пример события журнала маршрутизации

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

{
  "gateway_request_id": "gw_01jz_route_abc",
  "app_request_id": "req_9a7c",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "client_request_id": "7c2c1b3a-4b55-4e36-bd47-8d1c2e2f2e11",
  "owner": {
    "project": "checkout-ai",
    "environment": "production",
    "api_key_id": "key_hash_6f12",
    "team": "platform",
    "workflow": "customer-chat"
  },
  "requested_route": {
    "endpoint_family": "chat_completions",
    "model": "primary-chat-model",
    "stream": true,
    "route_policy_id": "chat-prod-v8",
    "fallback_policy_id": "chat-prod-safe-fallback-v3",
    "catalog_version": "2026-06-18"
  },
  "selected_route": {
    "provider": "provider_b",
    "model": "backup-chat-model",
    "upstream_account": "acct_pool_2",
    "decision_reason": "primary_timeout",
    "policy_rule_id": "fallback_on_timeout_once"
  },
  "attempts": [
    {
      "index": 1,
      "provider": "provider_a",
      "model": "primary-chat-model",
      "provider_request_id": "req_provider_a_123",
      "status_code": 504,
      "error_class": "timeout",
      "duration_ms": 12000,
      "fallback_target": "provider_b"
    },
    {
      "index": 2,
      "provider": "provider_b",
      "model": "backup-chat-model",
      "provider_request_id": "req_provider_b_456",
      "status_code": 200,
      "duration_ms": 2400,
      "time_to_first_chunk_ms": 620,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "input_tokens": 1284,
    "output_tokens": 312,
    "cached_input_tokens": 0,
    "reasoning_output_tokens": 0
  },
  "cost": {
    "currency": "usd",
    "estimated_amount": 0.0048,
    "line_item": "backup-chat-model"
  },
  "privacy": {
    "content_logging_mode": "metadata_only",
    "payload_redacted": true,
    "retention_class": "30_day_incident_metadata"
  }
}

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

10-минутный рабочий процесс сортировки

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

Найдите связанный запрос: выполните поиск по ID запроса приложения, ID запроса шлюза, ID ошибки для пользователя, ID запроса провайдера или trace ID.
Сравните запрошенные и выбранные маршруты: подтвердите запрошенную модель, политику маршрута, правило fallback, финального провайдера и финальную модель.
Прочитайте цепочку попыток: определите первый сбой, количество повторных попыток, целевой fallback и итоговый результат.
Проверьте контекст rate-limit и квот: изучите заголовки remaining, limit и reset, когда провайдеры возвращают 429 или возникает давление по токенам.
Разделите задержку и потоковую передачу: сравните длительность шлюза, длительность провайдера, время до первого чанка, окончание потока и отключение клиента.
Сопоставьте использование и стоимость: проверьте количество токенов, service tier, строку затрат и принадлежность команде/ключу.
Проверьте режим конфиденциальности: подтвердите, является ли лог только с метаданными, с редактированием, сырым или намеренно опущенным.
Определите действие для маршрута: откатите политику, отключите маршрут, уменьшите вес трафика, увеличьте квоту, поставьте фоновую работу в очередь или завершите с ошибкой закрыто.

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

Как Flatkey вписывается в наблюдаемость AI API

Flatkey позиционируется для команд, которым нужны один API-ключ, один совместимый endpoint роутера, прозрачное ценообразование, единый биллинг и одна панель управления для ключей, использования и маршрутизации. Для этой статьи релевантный путь проверки практичен: направьте staging-клиент на https://router.flatkey.ai/v1, отправляйте запросы через непроизводственный ключ, по возможности вызовите контролируемый сбой и подтвердите, какие записи об использовании, маршрутизации, ошибках и затратах отображаются в панели.

Используйте отслеживание использования AI по ключам, чтобы разделять трафик staging, production, клиентов и рабочих процессов. Используйте управление квотами AI API, чтобы fallback не сжигал общий бюджет. Используйте распределение затрат AI API по командам, когда изменения маршрутизации требуют ответственного со стороны финансов.

CTA прост: если ваша команда хочет протестировать наблюдаемость AI API под одним ключом, получите ключ, прогоните staging-маршрут через Flatkey и проверьте, отвечают ли логи на указанные выше вопросы по инциденту, прежде чем полагаться на автоматическое переключение в production.

Часто задаваемые вопросы

Что такое наблюдаемость AI API?

Наблюдаемость AI API — это возможность анализировать трафик API моделей по request ID, трассировкам, моделям, провайдерам, решениям маршрутизации, повторным попыткам, fallback, использованию, стоимости, задержке, ошибкам и настройкам конфиденциальности. При инцидентах маршрутизации она должна объяснять и то, что запросил клиент, и то, что фактически выбрал шлюз.

Что должны фиксировать логи API LLM?

Логи API LLM должны фиксировать correlation ID, метаданные владельца, запрошенный маршрут, выбранный маршрут, цепочку повторных попыток, задержку, состояние стриминга, использование токенов, стоимость, причину завершения, класс ошибки, контекст rate limit и режим логирования контента. Сырые промпты и ответы должны быть опциональными, с контролем доступа и по возможности с редактированием.

Зачем отдельно логировать запрошенную модель и модель ответа?

Запрошенная модель показывает намерение клиента. Модель ответа показывает, что фактически обслужило запрос. При инциденте с fallback эти значения могут различаться. Логирование обоих параметров критически важно для оценки качества, сверки затрат и коммуникации с поддержкой.

Как request ID помогают поддержке провайдера?

Provider request ID идентифицируют исходящий вызов API. Request ID, заданный вызывающей стороной, может помочь, если тайм-аут не позволяет заголовку ответа дойти до вашего клиента. Храните оба ID в записи об инциденте вместе с gateway request ID и trace ID.

Должен ли мониторинг AI gateway хранить сырые промпты?

По умолчанию — нет. Мониторингу AI gateway обычно в первую очередь нужны метаданные: маршрут, модель, статус, длительность, использование, стоимость и режим конфиденциальности. Храните сырые промпты или ответы только в рамках определённого процесса отладки, поддержки или аудита с контролем хранения и доступа.

Использованные источники

Окончательная проверка перед изменением маршрутизации

Прежде чем полагаться на автоматический fallback, сделайте наблюдаемость API ИИ частью release gate. Проверьте policy маршрута, ladder повторных попыток, поля токенов и затрат, заголовки rate limit, метки времени стриминга, идентификаторы запросов провайдера, режим конфиденциальности и класс хранения. Затем запустите контролируемый инцидент в staging и убедитесь, что журналы могут объяснить результат без доступа к raw prompt.

Flatkey сокращает поверхность интеграции до одного ключа и одного совместимого base URL. Чтобы оценить этот уровень надежности на своем трафике, получите ключ, запустите workflow в staging и изучите записи маршрутизации, использования, затрат и ошибок, которые вашей команде понадобятся во время реального инцидента.