Когда операция проходит через HTTP-запрос, очередь и один или несколько внешних сервисов, её записи оказываются распределены между разными процессами. Без общего атрибута при расследовании инцидента приходится искать данные по времени, пользователю или содержимому — эти критерии могут быть неоднозначными или чувствительными. Идентификатор корреляции в PHP позволяет группировать события, связанные с одной операцией, и восстанавливать её путь.
Чтобы это работало, у идентификатора должен быть определённый источник; он должен явно передаваться через границы асинхронных операций и единообразно появляться в логах. Это не полноценное решение для наблюдаемости и не учётные данные: идентификатор нужен для связи событий, но сам по себе не объясняет, что пошло не так, и не определяет, кто имеет доступ.
Какие задачи он решает и что остаётся за рамками
Идентификатор корреляции — это непрозрачное значение, связанное с запросом или операцией. Если добавлять его в логи приложения, он помогает находить сообщения из разных компонентов, в которых указано это значение. Например, так можно связать получение запроса с отправкой задачи, её обработкой и ответом внешнего API.
Это упрощает диагностику, если логи централизованы и поддерживают поиск по полям. Однако идентификатор не гарантирует, что все компоненты записали его правильно, и не измеряет длительность, объём или совокупное число ошибок. Метрики нужны для анализа тенденций и настройки оповещений; распределённые трассировки показывают связи и временные характеристики взаимодействия компонентов; логи содержат события и контекст. Это взаимодополняющие сигналы.
Корреляцию также не следует путать с аутентификацией, авторизацией или идентификацией пользователя. Само знание идентификатора не должно давать доступ к данным или позволять выполнять операцию. Если значение раскрыто в URL или сторонней системе, его могут увидеть люди, которым оно не предназначалось.
Определите, где создавать идентификатор и как его проверять
В приложении контекст обычно создаётся в HTTP middleware, принимающем запрос. Middleware может принять входящий идентификатор, чтобы сохранить непрерывность контекста при прохождении через прокси или предыдущий сервис, либо создать новый, если идентификатора нет. Политика должна быть явной: доверие всем внешним значениям может привести к приёму некорректных или чрезмерно длинных значений, а также значений, специально подготовленных для загрязнения логов.
Для публичного трафика безопасный вариант — всегда создавать внутренний идентификатор, а входящее значение, если необходимо его сохранить, считать недоверенными данными и строго проверять. Другой вариант — принимать значение из заголовка только от доверенных компонентов, настроив правила на периметре. Выбор зависит от архитектуры и от того, кто может вызывать сервис.
Формат должен быть простым для проверки и совместимым с системами, через которые он передаётся. Можно использовать случайное значение, созданное криптографически стойким генератором системы, например random_bytes(), и закодированное ограниченным набором символов. Не следует формировать его из временных меток, IP-адресов или персональных данных. Уникальному идентификатору не нужно раскрывать бизнес-информацию.
$correlationId = bin2hex(random_bytes(16));
Этот пример создаёт случайное значение в шестнадцатеричном формате; он не задаёт универсальный формат. Определите максимальную длину, допустимые символы и заголовок, который будут использовать компоненты, например X-Correlation-ID. Если платформа уже использует стандарт трассировки, не создавайте без необходимости параллельный механизм: корреляция логов и контекст трассировки могут сосуществовать, но это не одно и то же.
Передавайте контекст через каждую границу
В middleware проверьте или создайте идентификатор в начале запроса и добавьте его в контекст логирования. Если он возвращается клиенту в ответе, убедитесь, что при этом не раскрывается дополнительная информация и что политика доверия понятна. Остальные части приложения должны получать контекст как явную зависимость, а не полагаться на глобальные переменные, которые сложно тестировать.
Внутри PHP-процесса передавайте идентификатор сервисам, записывающим важные события. Для асинхронных задач включайте его в метаданные сообщения или в отдельное поле полезной нагрузки — в соответствии с соглашениями, принятыми в системе очередей. При обработке сообщения восстановите контекст до выполнения задачи и очистите его по завершении. Это особенно важно для долгоживущих процессов, в которых один и тот же worker обрабатывает последовательные сообщения: неочищенный контекст может попасть в другую операцию.
При вызове внешнего API передавайте значение в согласованном заголовке, только если поставщик его поддерживает и передача уместна. Не отправляйте лишние внутренние данные. Для интеграций, которые не сохраняют заголовки, записывайте идентификатор вместе с локальным результатом вызова; не рассчитывайте на то, что удалённая система вернёт его в собственных логах.
Если запрос порождает несколько независимых задач, каждая из них может сохранять идентификатор исходной операции. Если же нужно различать подоперации, создавайте для каждой собственный идентификатор и сохраняйте связь с помощью контекста трассировки или бизнес-полей, не содержащих чувствительных данных. Не используйте одно и то же значение для разных смыслов без документирования этого решения.
Используйте структурированные логи, не подменяя ими наблюдаемость
Записывайте идентификатор в отдельном структурированном поле, например correlation_id, а не только в текстовой фразе. Тогда платформа логирования сможет фильтровать и группировать события без приблизительного поиска. Используйте единое соглашение в приложении, workers и интеграциях и убедитесь, что сериализатор не отбрасывает это поле.
Добавляйте идентификатор в события, полезные для диагностики: получение запроса, создание сообщения, начало и завершение задачи, результат вызова внешнего сервиса. Необязательно повторять его в каждой строке, если система поддерживает постоянный контекст операции. В таком случае проверьте, что контекст сбрасывается между запросами и что логи остаются понятными, даже если какой-либо компонент не поддерживает его.
Не используйте идентификатор как метку метрик с высокой кардинальностью. Создание временного ряда для каждого запроса может увеличить затраты и снизить полезность метрик. Также не записывайте рядом с идентификатором токены, пароли, платёжные данные, полное содержимое сообщений и ненужную персональную информацию. Соблюдайте правила организации по минимизации данных, доступу к логам и срокам их хранения.
Повторные попытки, отложенное выполнение и сбои
При повторной попытке выполнить ту же задачу обычно сохраняют исходный идентификатор корреляции: задача по-прежнему относится к той же логической операции. Чтобы различать попытки, записывайте номер попытки или отдельный идентификатор попытки, не заменяя исходный контекст. Так можно исследовать и весь путь операции, и причины каждого выполнения.
Если выполнение задачи запланировано на гораздо более позднее время, сохраняйте идентификатор как постоянные метаданные; не полагайтесь на память процесса или уже завершившуюся HTTP-сессию. Если задача запускает новую автономную операцию, определите, наследует ли она исходный контекст или получает новый, и зафиксируйте связь между ними. Это решение не позволит слишком широкой корреляции смешивать несвязанные задачи.
Если очередь или внешний сервис отбрасывает метаданные, задокументируйте это ограничение и сохраняйте контекст в компоненте, который находится под вашим контролем. Приложение должно оставаться работоспособным и без идентификатора: создавайте его при входе в процесс или явно записывайте, что контекст недоступен.
Тестирование и операционные проверки
- Проверьте middleware на отсутствие идентификатора, корректный и некорректный идентификаторы; убедитесь, что применяется заданная политика и значение не превышает установленные ограничения.
- Убедитесь, что идентификатор запроса присутствует в логах внутренних сервисов и метаданных сообщения, отправленного в очередь.
- Обработайте сообщение в worker и проверьте, что контекст попал в логи и очищается до обработки следующего сообщения.
- Смоделируйте повторную попытку и убедитесь, что исходная корреляция сохраняется, а попытки можно различить.
- Проверьте результат вызова внешнего сервиса и обработку ошибок, не раскрывая в логах секреты и чувствительные тела запросов.
- Убедитесь, что дашборды и оповещения не зависят от поиска отдельных идентификаторов в метриках.
Сквозная проверка должна проследить тестовую операцию от входящего HTTP-запроса до задачи и интеграции, выполняя поиск в логах по одному и тому же полю. Если на каком-то этапе идентификатор отсутствует, определите точную границу: middleware, сериализация сообщения, потребитель, HTTP-клиент или конфигурация системы логирования. Так вы поймёте, где исправить передачу контекста, вместо того чтобы без разбора добавлять новые записи в логи.
Практический подход — поддерживать небольшой, явный контекст, не содержащий чувствительных данных, с чёткими правилами доверия и жизненного цикла. Так идентификатор корреляции в PHP сокращает время поиска при инциденте, не подменяя средства безопасности, трассировки, метрики и продуманное проектирование логов.
