Correlation ID в SMS-интеграции: как связать событие, запрос и доставку

SMS проходит через несколько систем: CRM создаёт событие, сервис уведомлений формирует задачу, очередь передаёт её воркеру, провайдер возвращает message ID, а позже webhook приносит DLR. Когда клиент сообщает, что уведомление не пришло, поиск только по номеру и времени быстро превращается в догадки.

Correlation ID — общий идентификатор, который проходит через всю цепочку и связывает записи разных компонентов. Он не заменяет provider message ID или ключ идемпотентности. Его задача — сделать один логический путь наблюдаемым от причины до результата.

Какие идентификаторы нужны

В зрелой интеграции обычно есть несколько ID:

• event_id — исходное бизнес-событие, например смена статуса заказа;
• correlation_id — вся цепочка обработки этого события;
• idempotency_key — защита конкретной отправки от дубля;
• client_message_id — внутренний идентификатор сообщения;
• provider_message_id — значение, выданное SMS-провайдером;
• trace_id и span_id — идентификаторы распределённой трассировки.

Иногда часть значений совпадает, но их смысл нужно документировать. Один заказ может породить несколько уведомлений, поэтому номер заказа не всегда подходит как уникальный message ID.

Где создавать correlation ID

Идентификатор создают как можно ближе к источнику бизнес-события. Если входящий HTTP-запрос уже содержит доверенный trace context, его можно продолжить. В остальных случаях сервис генерирует новое случайное значение и передаёт дальше.

Не используйте номер телефона, email или номер договора как correlation ID. Технический идентификатор должен быть непрозрачным и не раскрывать персональные данные. UUID или другой достаточно уникальный формат проще безопасно показывать поддержке.

Как переносить через систему

Correlation ID включают в сообщение очереди, структурированные логи и внутренний запрос к адаптеру. Если API провайдера поддерживает клиентское поле, туда передают client_message_id, а связь с correlation ID сохраняют в своей базе.

Не каждый провайдер возвращает произвольные метаданные в DLR. Поэтому таблица соответствия создаётся в момент успешного приёма:

correlation_id → client_message_id → provider_message_id.

Когда приходит webhook со статусом SMS, система находит provider message ID и восстанавливает весь контекст.

Структурированные логи

Полезная запись содержит время, сервис, среду, correlation ID, event ID, client message ID, тип операции, результат и код ошибки. Полный текст SMS, OTP, API-ключ и номер телефона туда не нужны. Для номера достаточно маски или внутреннего contact ID.

Все компоненты должны использовать одинаковые названия полей. Если один пишет corrId, другой request_id, а третий прячет значение в тексте, сквозной запрос усложняется. Общая схема логов важнее красивой строки для чтения человеком.

OpenTelemetry связывает логи и трассировки через TraceId и SpanId. Даже если полная трассировка не внедрена, тот же принцип полезен: идентификатор должен передаваться явно и попадать в каждый значимый этап.

Correlation ID и идемпотентность

Эти механизмы отвечают на разные вопросы. Correlation ID показывает: «какие операции относятся к одному пути?». Ключ идемпотентности отвечает: «создавали ли мы уже этот внешний эффект?».

При повторе одного запроса correlation ID часто сохраняют, чтобы видеть все попытки одной цепочки. Idempotency key обязательно сохраняют для той же логической отправки. При новом бизнес-событии создают новые значения, даже если получатель и шаблон совпадают.

Работа поддержки

В интерфейсе поддержки удобно искать по безопасному публичному идентификатору сообщения. Результат должен показывать последовательность без доступа к секретам:

1. Событие создано.
2. Задача помещена в очередь.
3. Воркер начал попытку.
4. Провайдер принял сообщение и выдал ID.
5. Получен промежуточный или финальный DLR.
6. Выполнено бизнес-действие после статуса.

Такой timeline сокращает время диагностики и показывает, на каком участке закончилась цепочка. Общие требования к данным описаны в статье про логи SMS-отправок.

Метрики и трассировки

Correlation ID не нужно помещать в labels метрик: уникальные значения создадут огромную кардинальность. Метрики агрегируют по сервису, сценарию, провайдеру, оператору и коду результата, а конкретный ID используют для перехода из алерта в лог или trace.

В распределённой трассировке полезны spans: создание задачи, ожидание очереди, вызов SMS API, приём DLR и обработка результата. Асинхронный webhook приходит позже исходного запроса, поэтому связь сохраняют через message ID и добавляют как link, если единый непрерывный trace уже завершён.

Ошибки внедрения

• генерировать новый correlation ID на каждом слое;
• использовать один постоянный ID для всех сообщений заказа;
• передавать персональные данные вместо непрозрачного значения;
• логировать ID только при ошибке, теряя успешную часть пути;
• не сохранять связь с provider message ID;
• добавлять уникальный ID в метрики;
• позволять пользователю подменять доверенный служебный заголовок без проверки.

Проверка

Возьмите одно тестовое сообщение и найдите по correlation ID все этапы без поиска по номеру. Затем смоделируйте таймаут, повтор задачи и дублированный webhook. Timeline должен показать несколько попыток, но одну логическую отправку и один итоговый статус.

Проверьте также срок хранения связей. Если DLR может прийти через сутки, таблицу соответствия нельзя удалить через час. С другой стороны, бесконечное хранение подробных технических данных увеличивает стоимость и риски.

Итог

Correlation ID превращает распределённую SMS-интеграцию в понятную цепочку. Он проходит от бизнес-события через очередь и API до статуса доставки, а связи с внутренним и провайдерским message ID позволяют восстановить историю. Это простой механизм, но он работает только при единой схеме полей и дисциплине передачи во всех компонентах.