Строка 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. Это прямо показано в официальном описании ответа. Отдельно учитывайте ошибки полей: транспортный успех не доказывает полноту бизнес-результата. Сообщения исключений перед записью проходят безопасную обработку; путь поля и класс ошибки часто полезнее исходного текста с данными пользователя.
Контрольный прогон ищет неоднозначность
- Отправить именованный искусственный запрос и найти все его фазы.
- Повторить его и убедиться, что сервер различает попытки.
- Выполнить другой документ с тем же именем операции.
- Проверить анонимную операцию и ошибку валидации.
- Получить контролируемую ошибку одного поля и увидеть неполный результат.
При параллельном запуске двух запросов контекст журнала не должен переходить из одного в другой. Идентификатор логической пользовательской операции, если он нужен для повторов, храните отдельно от серверной попытки и не принимайте его за доказательство полномочий. Откат диагностической доработки не должен менять ответы API. Для разбора подготовьте версию сервера, безопасный документ, ожидаемые фазы и пример обезличенных записей: по ним можно найти потерянный участок без выгрузки рабочих variables.