README

pipeline-flow-core - Laravel-пакет для трассировки backend-сценариев по trace_id.

Он помогает видеть один сценарий целиком: какие шаги уже прошли, какой шаг завершился ошибкой и в каком статусе сейчас находится run (running, ok, fail).

Это полезно, когда одно действие пользователя проходит через несколько backend-шагов. Например: вход в комнату, выдача токена, проверка runtime, вызов внутреннего API, отправка broadcast-события.

Пакет можно использовать двумя способами:

• только на backend, когда trace_id создаётся внутри приложения;
• в связке с frontend, когда клиент передаёт один и тот же trace_id в связанные запросы, а backend собирает их в один сценарий.

Когда пакет полезен

• Нужно быстро понять, где ломается многошаговый backend-flow.
• Нужно связать несколько backend-запросов в один пользовательский сценарий.
• Нужно видеть последние запуски сценариев через dashboard.

Быстрый старт

1. Установить пакет

composer require squop/pipeline-flow-core

Провайдер пакета подключается через Laravel auto-discovery.

2. Опубликовать конфиг

php artisan vendor:publish --tag=pipeline-flow-config

Будет создан файл config/pipeline-flow.php.

3. Выбрать драйвер хранения

Если нужен database driver, дополнительно опубликуйте миграции и выполните их:

php artisan vendor:publish --tag=pipeline-flow-migrations
php artisan migrate

Для redis этот шаг не нужен.

Драйверы хранения

Redis

redis подходит для быстрого старта, локального дебага и временного хранения trace-данных.

Плюсы:

• не нужна отдельная таблица;
• проще всего включить и начать смотреть сценарии;
• хорошо подходит для разработки и короткоживущих debug-run'ов.

Ограничения:

• полноценной пагинации по всему набору данных здесь нет;
• это скорее debug-режим, чем основное хранилище истории.

Database

database подходит, когда нужно хранить run'ы более предсказуемо и смотреть историю стабильнее, чем в debug-режиме Redis.

Плюсы:

• данные лежат в SQL-таблице;
• recent list использует нормальную пагинацию по неистёкшим записям;

Особенности:

• нужно опубликовать миграции и выполнить migrate;
• для очистки старых записей используется команда:

php artisan pipeline-flow:prune

Итог:

• redis - для быстрого локального дебага;
• database - если нужен более полноценный просмотр истории.

Использование

Сценарий 1. Трассировка только на backend

Если сценарий живёт полностью на backend, приложение может само создать trace_id, записывать шаги и вернуть этот идентификатор в ответ.

use Squop\PipelineFlow\ScenarioTraceService;

$trace_id = app(ScenarioTraceService::class)->issue();

После этого шаги сценария можно писать через PipelineManager.

use Squop\PipelineFlow\PipelineManager;

app(PipelineManager::class)->recordStepOk(
    pipeline_id: 'join_room',
    trace_id: $trace_id,
    step_name: 'room_join',
    duration_ms: 42,
    run_meta: [
        'user_id' => 10,
        'room_id' => 15,
    ],
    step_meta: [
        'source' => 'api',
    ],
);

Если на одном из шагов произошла ошибка:

app(PipelineManager::class)->recordStepFail(
    pipeline_id: 'join_room',
    trace_id: $trace_id,
    step_name: 'livekit_token_issue',
    duration_ms: 150,
    error: 'livekit_service_not_configured',
    run_meta: [
        'user_id' => 10,
    ],
);

Чтобы frontend или вызывающий клиент получил этот же trace_id, его можно вернуть в JSON-ответе:

use Squop\PipelineFlow\ScenarioTraceService;

$response = response()->json([
    'message' => 'ok',
]);

return app(ScenarioTraceService::class)->applyToJsonResponse($response, $trace_id);

Пакет добавит:

• header X-Scenario-Trace-Id;
• поле scenario_trace_id в JSON.

Сценарий 2. Frontend передаёт свой trace_id

Если frontend отправляет один и тот же trace_id в связанные запросы, backend сможет собрать их в один сценарий и показать более полную картину пользовательского flow.

На backend можно принять trace_id из запроса:

use Squop\PipelineFlow\ScenarioTraceService;

$trace_id = app(ScenarioTraceService::class)->resolveFromRequest($request);

Дальше этот trace_id используется так же, как и локально созданный:

• записываются шаги через recordStepOk() и recordStepFail();
• при необходимости тот же trace_id возвращается в ответе;
• в dashboard или API потом видно весь связанный сценарий.

Практический смысл простой: frontend и backend начинают смотреть на один и тот же trace, а не на набор несвязанных запросов.

Минимальный конфиг

<?php

return [
    'enabled' => true,
    'service_name' => 'backend',
    'driver' => 'redis',
    'trace_header_name' => 'X-Scenario-Trace-Id',
    'routes' => [
        'enabled' => true,
        'middleware' => ['web'],
        'authorize' => App\Support\PipelineRouteAuthorizer::class,
    ],
    'ui' => [
        'enabled' => true,
        'middleware' => ['web'],
    ],
    'pipelines' => [
        'join_room' => [
            'active_timeout_seconds' => 30,
            'success_step' => 'livekit_token_issue',
        ],
    ],
];

Ключевые параметры:

• enabled - включает пакет;
• service_name - имя сервиса, которое будет записываться в шагах;
• driver - redis или database;
• trace_header_name - header, через который передаётся trace_id;
• routes.enabled - включает встроенные read-only routes;
• ui.enabled - включает встроенный dashboard;
• pipelines.*.success_step - шаг, после которого run считается успешным;
• pipelines.*.active_timeout_seconds - сколько run может оставаться в running без новых шагов.

Dashboard

У пакета есть встроенный HTML dashboard для просмотра последних run'ов и деталей по ним.

Он включается через ui.enabled. Обычно этого достаточно, чтобы быстро смотреть trace'ы без отдельной админки.

HTTP API

У пакета есть встроенные read-only routes для просмотра recent run'ов и конкретного run по trace_id.

Они включаются через routes.enabled. Обычно это полезно для внутренних debug-инструментов или если вы хотите читать trace'ы не только через dashboard.

Важно

• Пакет не добавляет трассировку автоматически: шаги сценария вы записываете сами в коде приложения.
• Если нужен в первую очередь быстрый debug, обычно достаточно redis.
• Если нужна более стабильная история и нормальная пагинация, лучше использовать database.
• У пакета есть точки расширения, но для первого внедрения это обычно не нужно.