# Регистър на събитията в работния поток

Регистърът на събитията в работния поток записва проследяване за всяка трайна граница на работния поток. Всяко събитие от проследяването може да включва входа и изхода на стъпката, публичното състояние преди и след стъпката, контекста на изпълнение, препратки към артефакти, части от потока, времеви данни и подробности за грешките.

## Какво се записва

| Събитие | Кога | Записвани данни |
|---|---|---|
| `step_started` | Преди изпълнението на обработчика на стъпката | ИД на задачата, опашка, опит, име на стъпката, тип на стъпката, вход и състояние преди изпълнението |
| `step_completed` | След успешно изпълнение на обработчика на стъпката | Вход, изход, състояние преди и след изпълнението, контекст, артефакти, части и продължителност |
| `step_failed` | Когато обработчикът на стъпката хвърли изключение | Вход, състояние преди и след изпълнението, ако е налично, контекст, клас на грешката, съобщение за грешката, проследяване и продължителност |
| `step_branch_completed` | Когато един паралелен клон приключи успешно | Вход на клона, изход, състояние преди и след изпълнението, контекст и продължителност |
| `step_item_completed` | Когато един елемент от цикъл for-each приключи успешно | Вход на елемента, изход, състояние преди и след изпълнението, метаданни на елемента, контекст и продължителност |
| `workflow_waiting` | Когато стъпка за изчакване постави изпълнението на пауза | Тип на изчакването, цели на изчакването, режим на изчакване, ключ за резултата, метаданни за съвпадението и състояние по време на изчакване |
| `workflow_resumed` | Когато условието за стъпка на изчакване е изпълнено | Данни за възобновяване, състояние преди и след възобновяването |
| `workflow_replayed` | Когато експортиране бъде създадено отново | Метаданни на изходния работен поток и състояние при повторно изпълнение |

## Извличане на данни от времевата линия

```php
$events = Queuety::workflow_timeline( $workflow_id );

foreach ( $events as $event ) {
    echo $event['step_index'] . ' ' . $event['event'] . ' ' . $event['handler'] . "\n";

    if ( 'step_completed' === $event['event'] ) {
        $input        = $event['input'];
        $output       = $event['output'];
        $state_before = $event['state_before'];
        $state_after  = $event['state_after'];
    }

    if ( 'step_failed' === $event['event'] ) {
        echo 'Error: ' . $event['error']['message'] . "\n";
    }
}
```

Всеки ред на събитие съдържа:

- `id`
- `workflow_id`
- `job_id`
- `parent_event_id`
- `step_index`
- `step_name`
- `step_type`
- `handler`
- `event`
- `queue`
- `attempt`
- `input`
- `output`
- `state_before`
- `state_after`
- `context`
- `artifacts`
- `chunks`
- `error`
- `duration_ms`
- `created_at`

## Нормализиран пакет с проследявания

Използвайте `workflow_trace()`, когато създавате инструмент за отстраняване на грешки UI:

```php
$trace = Queuety::workflow_trace( $workflow_id );
```

Пакетът с проследявания включва:

- `workflow`
- `steps`
- `events`
- `jobs`
- `logs`
- `artifacts`
- `chunks`
- `signals`
- `wait_dependencies`

`steps` групира събитията по индекс на стъпката и включва последното важно събитие за всяка стъпка.

## Търсене на състоянието на стъпка

```php
$state = Queuety::workflow_state_at( $workflow_id, $step_index );
```

Това връща публичното `state_after` от последното приключило или възобновено събитие за тази стъпка, или `null`, ако няма записано състояние.

## Метаданни за проследяване по време на изпълнение

Обработчиците могат да добавят подробности за проследяването на ниво приложение, докато работят:

```php
Queuety::trace_input( [ 'resolved' => $resolved_input ] );
Queuety::trace_context( [ 'ability' => 'content/load-post' ] );
Queuety::trace_output( [ 'post' => $post ] );
```

Обработчиците на стъпки могат също да връщат запазени метаданни за проследяване:

```php
return [
    'result' => 'done',
    '_queuety_trace' => [
        'input' => [ 'resolved' => $resolved_input ],
        'context' => [ 'node_id' => 'loadPost' ],
        'artifacts' => [
            [ 'key' => 'brief', 'kind' => 'markdown' ],
        ],
    ],
];
```

Ключът `_queuety_trace` се съхранява в регистъра на събитията и не се слива със състоянието на работния поток.

## CLI

Прегледайте времевата линия като таблица:

```bash
wp queuety workflow timeline 42
```

Прегледайте състоянието след дадена стъпка:

```bash
wp queuety workflow state-at 42 0
```

## Съхранение

Регистрите на събитията се натрупват с времето. Използвайте `prune()`, за да изтриете старите събития от проследяването:

```php
$deleted = Queuety::workflow_events()->prune( 30 );
```