Строка POST /graphql показывает транспортный маршрут, но не объясняет, какую операцию выполнял клиент. Добавьте к серверному идентификатору запроса безопасное описание выбранной операции и исход исполнения. Начните с искусственного запроса на стенде: его запись должна находиться по одному идентификатору от входа HTTP до завершения обработки.

Не включайте запись полного тела всех запросов ради поиска: variables могут содержать персональные данные и секреты. Практическая цель — отличить неизвестный документ, ошибку выбора операции, отказ исполнения и успешный ответ. Для расследования обычно полезнее согласованные поля журнала, чем большой JSON без связи с другими событиями.

Одно имя ещё не определяет документ

Руководство GraphQL over HTTP описывает query, operationName, variables и extensions в теле POST. operationName обязателен при нескольких операциях в документе; в остальных случаях поле может отсутствовать. Проверено 15 октября 2026 года. Поэтому нельзя считать его гарантированным уникальным ключом мониторинга. Клиент может повторно использовать имя или прислать анонимную операцию.

Поле журналаЧто различаетОграничение
request_idКонкретную серверную попыткуПовтор получит другой ID
operation_nameВыбранную именованную операциюИмя не уникально для документа
document_idИзвестный документ приложенияНужен согласованный реестр или нормализация
execution_outcomeДанные и ошибки исполненияНе заменяется одним HTTP-кодом

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

Журнал проходит те же этапы, что обработчик

Условная запись без тела запроса:
request_id: <серверная попытка>
operation_name: <имя или anonymous>
document_id: <известный ID либо unknown>
phase: parse / validate / execute / complete
result: success / partial / rejected
variables: <не записываются>

Поставьте запись начала на входе обработчика, а итог — в пути завершения, включая исключение и отмену. Если документ не разобран, имя операции может ещё не существовать. Такое событие должно оставаться видимым как ошибка ранней фазы, а не исчезать из журнала из-за отсутствующего operationName. Для отказов до GraphQL понадобятся записи прокси и HTTP-обработчика с той же согласованной связью.

Ответ GraphQL может содержать одновременно data и errors. Это прямо показано в официальном описании ответа. Отдельно учитывайте ошибки полей: транспортный успех не доказывает полноту бизнес-результата. Сообщения исключений перед записью проходят безопасную обработку; путь поля и класс ошибки часто полезнее исходного текста с данными пользователя.

Контрольный прогон ищет неоднозначность

  1. Отправить именованный искусственный запрос и найти все его фазы.
  2. Повторить его и убедиться, что сервер различает попытки.
  3. Выполнить другой документ с тем же именем операции.
  4. Проверить анонимную операцию и ошибку валидации.
  5. Получить контролируемую ошибку одного поля и увидеть неполный результат.

При параллельном запуске двух запросов контекст журнала не должен переходить из одного в другой. Идентификатор логической пользовательской операции, если он нужен для повторов, храните отдельно от серверной попытки и не принимайте его за доказательство полномочий. Откат диагностической доработки не должен менять ответы API. Для разбора подготовьте версию сервера, безопасный документ, ожидаемые фазы и пример обезличенных записей: по ним можно найти потерянный участок без выгрузки рабочих variables.

Проверенные источники