# Journal des événements des flux de travail

Le journal des événements des flux de travail consigne une trace à chaque étape durable. Chaque événement de trace peut inclure les données d’entrée et de sortie de l’étape, l’état public avant et après l’étape, le contexte d’exécution, les références aux artefacts, les blocs diffusés, les durées et les détails des erreurs.

## Données enregistrées

| Événement | Quand | Données capturées |
|---|---|---|
| `step_started` | Avant l’exécution d’un gestionnaire d’étape | Identifiant de tâche, file d’attente, tentative, nom et type de l’étape, données d’entrée et état avant l’exécution |
| `step_completed` | Après la réussite d’un gestionnaire d’étape | Données d’entrée, sortie, état avant, état après, contexte, artefacts, blocs et durée |
| `step_failed` | Lorsqu’un gestionnaire d’étape lève une exception | Données d’entrée, état avant, état après si disponible, contexte, classe et message de l’erreur, trace et durée |
| `step_branch_completed` | Lorsqu’une branche parallèle réussit | Données d’entrée de la branche, sortie, état avant, état après, contexte et durée |
| `step_item_completed` | Lorsqu’un élément de boucle réussit | Données d’entrée de l’élément, sortie, état avant, état après, métadonnées de l’élément, contexte et durée |
| `workflow_waiting` | Lorsqu’une étape d’attente met l’exécution en pause | Type d’attente, cibles, mode, clé de résultat, métadonnées de correspondance et état pendant l’attente |
| `workflow_resumed` | Lorsqu’une condition d’attente est satisfaite | Données de reprise, état avant la reprise et état après la reprise |
| `workflow_replayed` | Lorsqu’une exportation est recréée | Métadonnées du flux source et état de relecture |

## Interroger la chronologie

```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";
    }
}
```

Chaque ligne d’événement contient :

- `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`

## Ensemble de traces normalisé

Utilisez `workflow_trace()` pour créer une interface de débogage UI :

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

L’ensemble de traces comprend :

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

`steps` regroupe les événements par indice d’étape et inclut le dernier événement important pour chaque étape.

## Recherche de l’état d’une étape

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

Cela renvoie l’état public `state_after` de l’événement le plus récent terminé ou repris pour cette étape, ou `null` si aucun état n’a été enregistré.

## Métadonnées de trace d’exécution

Les gestionnaires peuvent ajouter des détails de trace propres à l’application pendant leur exécution :

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

Les gestionnaires d’étape peuvent aussi renvoyer des métadonnées de trace réservées :

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

La clé `_queuety_trace` est enregistrée dans le journal des événements et n’est pas fusionnée dans l’état du flux de travail.

## CLI

Afficher la chronologie sous forme de tableau :

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

Afficher l’état après une étape :

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

## Conservation

Les journaux d’événements s’accumulent au fil du temps. Utilisez `prune()` pour supprimer les anciennes traces :

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