К содержимому
Блог

Что записывать в логи LLM API и отправлять поддержке

Что записывать в логи LLM API и отправлять поддержке

Для разбора ошибки API обычно полезнее время, идентификатор модели, HTTP-статус, код ошибки и request_id, чем полный дамп запроса. Сохраняйте эти поля отдельно от пользовательского текста и секретов.

Свяжите операцию продукта с вызовом API

У приложения есть собственная задача: сообщение чата, обработка файла или фоновая операция. Присвойте ей внутренний идентификатор и запишите его рядом с request_id, который вернул API, если такое поле присутствует.

Сохраняйте номер попытки. Если SDK и приложение повторяют вызов, одна пользовательская задача может соответствовать нескольким запросам. Без этой связи сложно понять, почему в журнале Relay больше операций, чем действий в интерфейсе.

Привяжите запрос к ключу, функции и пользователю

Журнал Relay знает ключ, модель, токены и результат каждого запроса, дошедшего до модели, но не знает, какая функция вашего продукта или какой пользователь его вызвал. Отказы шлюза до отправки модели, например неверный ключ, лимит или баланс, в журнале искать не стоит: для них опирайтесь на статус, тело ошибки и x-request-id, которые сохранил ваш клиент. Функции вы разделяете сами: выдайте отдельный ключ на каждую функцию или команду и назовите его понятно, например support-bot или nightly-digest. Тогда фильтр журнала по ключу и разбивка расхода по дням отвечают на вопрос «кто и на что» без единой строки кода. Пользователя связываете тоже вы: пишите в свои логи внутренний идентификатор пользователя рядом с request_id, а не внутри промпта и не в имени ключа. По такой связке жалобу можно сопоставить с запросом в журнале Relay.

Записывайте время и состояние

Время должно включать часовой пояс. Для потока полезны начало, первый фрагмент и завершение. Отдельно укажите, кто остановил запрос: пользователь, таймаут приложения или сетевой клиент.

Не называйте любой обрыв «ошибкой модели». API мог начать ответ, а соединение мог закрыться позже на другом участке. Сценарии потока разобраны в документации streaming.

Исключите секреты до записи

Не логируйте Authorization, x-api-key, Cookie или полный файл настроек клиента. Фильтр должен применяться до отправки в систему сбора логов: исправление текста после загрузки не удалит все копии.

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

Соберите обращение, которое можно воспроизвести

Укажите клиент и версию, протокол, модель, время, статус и request_id. Добавьте ожидаемое поведение и краткую последовательность действий. Сообщение «не работает» без времени и операции нельзя надёжно сопоставить с серверным событием.

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

Ограничьте срок хранения технических журналов и круг сотрудников с доступом по правилам вашего продукта. Логирование всех сообщений навсегда не требуется для качественной диагностики подключения.

Превратите логи в бюджет и алерты

Сырые записи сами ничего не решают, решают правила поверх них. Считайте три вещи: расход по ключу за день, число токенов входа на запрос и долю повторов на задачу. Для каждой берите порог от собственной нормы, например «в несколько раз выше медианы прошлой недели». Числа подбирайте по своим данным: универсальных нет. Для старта хватит трёх правил:

  • расход ключа за сутки заметно выше обычного: сообщите дежурному;

  • вход на запрос вырос после выката: проверьте, не попал ли в промпт лишний контекст;

  • у одной задачи больше двух повторов подряд: откройте request_id последнего отказа.

От тихого перерасхода страхует сам ключ. У него есть лимиты расходов на весь срок, день и месяц, и запрос сверх лимита получает key_limit_exceeded без списания, даже если алерт молчит. Для разбора в таблице журнал выгружается в CSV за период, до 100 000 строк с теми же фильтрами. Тексты запросов и ответов Relay не хранит, поэтому содержимое для отладки живёт только в ваших логах, ровно столько, сколько вы решите.

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.