PHPackages                             squop/pipeline-flow-core - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. squop/pipeline-flow-core

ActiveLibrary[Utility & Helpers](/categories/utility)

squop/pipeline-flow-core
========================

Laravel package for lightweight pipeline flow tracing

1.1.0(2mo ago)04proprietaryPHP ^8.2

Since May 6Compare

[ Source](https://github.com/Daniil-Solovyev/pipeline-flow-core)[ Packagist](https://packagist.org/packages/squop/pipeline-flow-core)[ RSS](/packages/squop-pipeline-flow-core/feed)WikiDiscussions Synced 3w ago

READMEChangelogDependencies (8)Versions (3)Used By (0)

Pipeline Flow Core
==================

[](#pipeline-flow-core)

`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. Установить пакет

[](#1-установить-пакет)

```
composer require squop/pipeline-flow-core
```

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

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

[](#2-опубликовать-конфиг)

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

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

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

[](#3-выбрать-драйвер-хранения)

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

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

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

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

[](#драйверы-хранения)

### Redis

[](#redis)

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

Плюсы:

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

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

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

### Database

[](#database)

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

Плюсы:

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

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

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

```
php artisan pipeline-flow:prune
```

Итог:

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

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

[](#использование)

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

[](#сценарий-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`

[](#сценарий-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, а не на набор несвязанных запросов.

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

[](#минимальный-конфиг)

```