Request ID: корреляция очереди в API gateway

Создайте локальный идентификатор до вызова

Сгенерируйте operation ID до помещения задачи в очередь и сохраните его вместе с project ID, типом операции, версией адаптера и минимальным статусом. Этот ID принадлежит вашему приложению, поэтому он остаётся доступен, даже если запрос не дошёл до gateway или ответ не содержит внешнего идентификатора. Не используйте в нём e-mail, prompt, API-ключ или предсказуемый счётчик. Клиент получает только безопасный публичный идентификатор либо ссылку на собственный статус-эндпоинт. Когда задача переходит из queued в sending, accepted, completed, failed или cancelled, сервер пишет событие в журнал с временем и причиной без тела запроса.

Привяжите внешний request ID как необязательный атрибут

После получения заголовка или поля ответа проверьте формат и сохраните его как внешний correlation ID, не заменяя локальный operation ID. Иногда внешний идентификатор отсутствует, меняет имя или относится только к одному транспортному вызову; это нормальная ветка, а не причина придумывать значение. Связывайте один operation ID с несколькими попытками, если ваш retry безопасен, и сохраняйте отдельный attempt ID. Не логируйте raw headers: в них могут оказаться Authorization, cookie или чувствительные диагностические данные. Для поддержки достаточно показать время, локальный статус, код ошибки, ограниченную категорию причины и оба безопасных идентификатора, если второй доступен.

Сделайте очередь наблюдаемой по состояниям

Очередь должна отвечать на вопрос не только «сколько ждём», но и «что уже могло произойти». Явно задайте переходы queued, leased, sending, accepted, waiting_result, completed, failed, cancelled и review_required. Каждому переходу назначьте допустимого исполнителя и дедлайн. Если worker погиб после отправки, не запускайте слепой повтор: сначала проверьте локальную запись операции и правила идемпотентности. Для асинхронного результата сопоставляйте callback или polling с operation ID, а подпись и формат события валидируйте до изменения статуса. Внешний request ID помогает расследованию, но не должен быть единственным ключом бизнес-состояния.

Логируйте минимум, достаточный для диагностики

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

Коррелируйте retry и отмену без дублей

Повтор допустим только для операции, которую ваша policy считает безопасной. Перед новой попыткой возьмите lock по operation ID, проверьте статус предыдущей и назначьте ограниченный бюджет retry с jitter и общим дедлайном. Не маскируйте validation_error, отказ прав или неизвестное состояние повтором. При отмене сохраните намерение пользователя локально и остановите ожидание, но не обещайте, что внешний процесс можно отменить без подтверждённого контракта. Если результат придёт позже, обработчик сверяет operation ID, версию попытки и разрешённый переход состояния; устаревшее событие не меняет уже завершённую задачу.

Подготовьте сценарий для поддержки

В карточке инцидента оператору нужен понятный путь: запросить operation ID, проверить проект и права, увидеть обезличенную временную шкалу и при наличии внешний request ID. Не просите прислать API-ключ, полный prompt, cookie или скриншот с секретами. Если задача зависла, сначала определите её локальное состояние и срок дедлайна, затем решите, разрешён ли retry, отмена или ручной review. Тестируйте этот процесс на синтетической задаче перед выпуском новой очереди. Времена выполнения, доступность модели и формат внешних ID могут меняться, поэтому они не становятся обещанием SLA в статье или интерфейсе.

Server-side пример

Пример рассчитан на Node.js 18+ и защищённый server-side запуск. Он не содержит реального ключа и показывает логику приложения; перед интеграцией подтвердите текущую схему, маршрут и ограничения в документации.

export function recordAttempt(operation, response) {
  const requestId = response.headers?.get?.('x-request-id') ?? null;
  return {
    operationId: operation.id,
    attempt: operation.attempt + 1,
    state: response.ok ? 'accepted' : 'failed',
    externalRequestId: typeof requestId === 'string' && requestId.length <= 200 ? requestId : null,
    loggedAt: new Date().toISOString()
  };
}
// Store only approved diagnostic fields on the server; header names vary by current contract.

Проверьте синтаксис через node --check, добавьте аутентификацию, лимиты и отрицательные тесты. Не записывайте в журнал тело запроса целиком или заголовки авторизации.

Перед production выполните тест в отдельном environment, назначьте владельца проверки и зафиксируйте результат без чувствительных данных. Повторяйте проверку при смене версии клиента, модели или серверной policy.

Граница ответственности

Это руководство описывает защитные механизмы вашего приложения, а не гарантии конкретного провайдера или модели. Не передавайте в браузер, статьи, тикеты или логи API-ключи, заголовки Authorization, cookie, исходные ключи поставщиков либо полные пользовательские данные.

Материалы для сверки

Внешние источники ниже поясняют общие инженерные и безопасностные принципы. Они не подтверждают конкретные функции, тарифы или доступность RussiaAPI либо сторонних моделей.

• RFC 9110: HTTP semantics
• OpenTelemetry: основы наблюдаемости