Як забезпечити спостережуваність вихідних запитів до сторонніх API і швидко знаходити причини збоїв?

Question

Accepted Answer

Коли «не приходять SMS» чи «замовлення не потрапили в CRM», перше питання - що саме відбувалося між вашим застосунком і провайдером. Без записів про вихідні запити відповісти неможливо.
Події HTTP-клієнта - точка для централізованого логування без зміни коду інтеграцій:
use Illuminate\Http\Client\Events\ConnectionFailed;
use Illuminate\Http\Client\Events\ResponseReceived;

Event::listen(function (ResponseReceived $event) {
    Log::channel('integrations')->info('http.out', [
        'host' => parse_url($event->request->url(), PHP_URL_HOST),
        'method' => $event->request->method(),
        'path' => parse_url($event->request->url(), PHP_URL_PATH),
        'status' => $event->response->status(),
        'duration_ms' => round(($event->response->transferStats?->getTransferTime() ?? 0) * 1000),
    ]);
});

Event::listen(fn (ConnectionFailed $event) => Log::channel('integrations')->warning('http.out.failed', [
    'url' => $event->request->url(),
]));

Також є RequestSending перед відправкою і глобальні middleware клієнта (Http::globalRequestMiddleware, globalResponseMiddleware) - наприклад, щоб додати заголовок кореляції до всіх вихідних запитів.
Що варто записувати:

провайдер, ендпойнт (без параметрів з персональними даними), метод, статус, тривалість, номер спроби;
ідентифікатор запиту провайдера з заголовка відповіді (X-Request-Id, CF-Ray) - саме його попросить підтримка провайдера;
ваш ідентифікатор кореляції - щоб зв'язати вихідний запит з HTTP-запитом користувача чи джобою, що його породили (Context::add('trace_id', ...) в Laravel додає його в усі журнали);
для збоїв - фрагмент тіла відповіді з помилкою.

Чого НЕ записувати: токени й ключі (Authorization), паролі, номери карток, повні тіла з персональними даними. Маскування - в одному місці, у слухачі подій.
Метрики й сповіщення важливіші за журнали:

частка помилок і латентність за провайдером (p95);
кількість 429 - наближення до лімітів;
довжина черги інтеграцій і кількість невдалих джоб;
сповіщення, коли частка помилок провайдера перевищує поріг.

Інструменти в Laravel-екосистемі: Pulse (картки повільних вихідних запитів), Telescope (на staging - детально кожен запит), Nightwatch, OpenTelemetry для розподіленого трасування.
Журнал бізнес-операцій інтеграції (таблиця «синхронізації»: що відправлено, коли, результат, зовнішній ID) - окремо від технічних журналів. Його показують підтримці й адміністраторам і використовують для звірки.
Пісочниці провайдерів у staging - щоб збої інтеграцій ловилися до продакшену, а моніторинг працював і там.
Докладніше в документації: HTTP-клієнт: події

Як забезпечити спостережуваність вихідних запитів до сторонніх API і швидко знаходити причини збоїв?

Схожі питання