Логирование запросов

Что такое логирование

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

Логирование запросов решает эту проблему. При включении сервис записывает полные данные о каждом обращении к API: метаданные (статус, задержка, модель, ключ), потребление (токены с разбивкой по типам), а также полное содержимое запросов и ответов — включая промпты, ответы модели и сообщения об ошибках.

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

Как включить

1. Перейти в раздел «Логи» в боковом меню личного кабинета
2. Нажать «Включить логирование»
3. Выбрать период хранения (3, 7, 30 или 365 дней)
4. Подтвердить активацию

Логирование действует на уровне аккаунта — записываются запросы по всем API-ключам. Новые запросы начнут логироваться сразу после активации.

Историческая информация после активации не переносится в логи — записи накапливаются с момента включения.

X-Request-ID

Каждый запрос к API ProxyAPI возвращает заголовок X-Request-ID с уникальным идентификатором (UUID):

X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

Этот идентификатор можно использовать для:

• Поиска в логах — в фильтрах на странице «Логи» есть поле «Request ID»
• Обращения в поддержку — по Request ID запрос находится быстрее всего

Пользовательские метаданные (X-Log-*)

К каждому запросу можно прикрепить произвольные метаданные с помощью HTTP-заголовков с префиксом X-Log-. Метаданные сохраняются в логе и доступны в детальном просмотре и экспорте.

Префикс X-Log- удаляется, остаток приводится к нижнему регистру:

X-Log-Session: abc123       → session: abc123
X-Log-Environment: staging  → environment: staging
X-Log-Tag: experiment-42    → tag: experiment-42

Пример запроса с метаданными:

curl "https://api.proxyapi.ru/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <КЛЮЧ>" \
    -H "X-Log-Session: abc123" \
    -H "X-Log-Environment: production" \
    -d '{
        "model": "openai/gpt-5-mini",
        "messages": [{"role": "user", "content": "Привет"}]
    }'

Ограничения метаданных

• Не более 10 заголовков X-Log-* на запрос
• Длина ключа (после удаления префикса) — не более 64 символов
• Длина значения — не более 256 символов

Заголовки, превышающие лимиты, молча игнорируются — запрос никогда не отклоняется из-за метаданных.

Фильтрация по метаданным пока не поддерживается — они доступны только при просмотре отдельной записи и в экспорте.

Что логируется

Статусы запросов

Каждая запись в логах имеет один из четырёх статусов:

Данные в каждой записи

• Идентификация: API-ключ (название и маскированный), модель, вендор, endpoint, IP-адрес клиента
• Производительность: HTTP-код ответа, общая задержка (мс), время до первого токена (для стриминга), флаг стриминга
• Потребление: разбивка по типам токенов (ввод, вывод, размышления, кэш и др.), размер запроса и ответа в байтах
• Биллинг: списанная сумма (для отклонённых запросов — пусто, так как списания не происходит)
• Ошибки: тип и текст ошибки (от конечного сервиса или от ProxyAPI)
• Содержимое запросов и ответов: промпт, ответ модели или сообщение об ошибке
• Пользовательские метаданные: произвольные данные, переданные через заголовки X-Log-*

Для запросов, отклонённых на уровне ProxyAPI (proxy_error): нет ответа от конечного сервиса, нет потребления токенов, задержка отражает время обработки на стороне ProxyAPI. Содержимое ответа — сообщение об ошибке от ProxyAPI.

Тарифы

Стоимость логирования зависит от выбранного периода хранения:

Бесплатный лимит

На тарифе с хранением 3 дня первые 10 000 запросов в месяц — бесплатно. После исчерпания лимита запросы продолжают логироваться и оплачиваются по стандартной ставке 8 ₽ за 1 000 запросов. Счётчик обнуляется в начале каждого месяца.

При переходе на любой другой период хранения (7, 30, 365 дней) оплата начинается с первого запроса.

Как происходит оплата

• Списание происходит с баланса ProxyAPI — того же, с которого оплачиваются запросы к моделям
• Биллинг ежедневный: каждую ночь в 04:00 МСК начисляется оплата за запросы предыдущего дня по текущему тарифу
• Смена тарифа влияет только на будущие списания — пересчёта за прошлые дни не происходит

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

Период хранения — это скользящее окно: хранятся все логи за последние N дней. Очистка устаревших записей выполняется автоматически каждую ночь.

При увеличении периода хранения существующие логи будут храниться дольше.

При уменьшении периода хранения записи за пределами нового окна будут удалены в ближайшую ночную очистку (04:00 МСК). До этого момента изменение можно отменить.

Отключение логирования

При отключении логирования:

1. Новые запросы сразу перестают логироваться
2. Существующие логи остаются доступны до 04:00 МСК — этого времени достаточно, чтобы экспортировать данные
3. В 04:00 МСК: начисляется оплата за последние запросы, затем все логи удаляются

Если решение изменилось — включите логирование обратно до 04:00 МСК, и все существующие логи сохранятся, запись возобновится.

Экспорт

Экспорт позволяет скачать логи в машиночитаемом формате для внешнего анализа или архивирования.

Как экспортировать

1. На странице «Логи» нажать кнопку экспорта (иконка скачивания)
2. Выбрать вариант включения содержимого запросов и ответов (см. ниже)
3. Нажать «Экспортировать»
4. Ссылка на скачивание придёт на почту аккаунта (действует 24 часа)

Экспорт выгружает все логи за выбранный на странице диапазон дат и времени (или за всё время, если диапазон не указан).

Варианты включения содержимого

Формат файла

Экспорт — zip-архив, содержащий:

• logs.ndjson — по одной JSON-строке на каждую запись
• payloads/ — папка с крупным содержимым запросов и ответов. Появляется только при варианте «все» и только если крупное содержимое действительно было

Ограничения экспорта

• Не более 10 экспортов в сутки
• Только один экспорт одновременно — нужно дождаться завершения текущего

Поля экспорта

Каждая строка в файле logs.ndjson — это JSON-объект со следующими полями:

usage_breakdown

Массив объектов, описывающих потребление ресурсов в рамках запроса. Один запрос может содержать несколько элементов — например, при использовании модели с поиском в интернете будет отдельная запись на потребление модели и отдельная на поиск.

Каждый элемент имеет четыре поля:

• type — тип продукта: MODEL_TEXT, MODEL_IMAGE, MODEL_VIDEO, MODEL_TTS, MODEL_STT, MODEL_EMBEDDING, SERVICE
• vendor — вендор продукта
• product — строка вида продукт/снапшот (например, gpt-5-mini/gpt-5-mini-2025-08-07) или просто продукт для сервисных продуктов (например, web-search)
• breakdown — объект с парами «тип потребления → количество»

Пример:

[
    {
        "type": "MODEL_TEXT",
        "vendor": "openai",
        "product": "gpt-5-mini/gpt-5-mini-2025-08-07",
        "breakdown": {
            "input_tokens": 150,
            "output_tokens": 420,
            "reasoning_tokens": 100
        }
    },
    {
        "type": "SERVICE",
        "vendor": "openai",
        "product": "web-search",
        "breakdown": {
            "search": 1
        }
    }
]

Типы потребления в breakdown

Ключи с приставкой batch_ — то же потребление в пакетной обработке, с приставкой extended_ — в расширенном контексте. Тарифицируются они по своим ценам.

Ограничения

На данный момент не логируются:

• Некоторые клиентские ошибки валидации (неизвестная модель, некорректное содержимое запроса), которые отклоняются до начала обработки запроса — такие ошибки не попадают в логи
• Повторные попытки: если запрос был перенаправлен после отказа конечного сервиса, в логи попадает только итоговая попытка

Логирование действует на уровне аккаунта. Включение логирования для отдельных API-ключей пока не поддерживается.