# Registro eventi del flusso di lavoro

Il registro eventi del flusso di lavoro registra una traccia per ogni confine persistente del flusso. Ogni evento di traccia può includere l'input e l'output del passaggio, lo stato pubblico prima e dopo il passaggio, il contesto di runtime, i riferimenti agli artefatti, i segmenti trasmessi in streaming, i tempi e i dettagli degli errori.

## Dati registrati

| Evento | Quando | Dati acquisiti |
|---|---|---|
| `step_started` | Prima dell'esecuzione del gestore di un passaggio | ID del job, coda, tentativo, nome del passaggio, tipo di passaggio, input e stato prima dell'esecuzione |
| `step_completed` | Dopo l'esito positivo del gestore di un passaggio | Input, output, stato prima e dopo, contesto, artefatti, segmenti e durata |
| `step_failed` | Quando il gestore di un passaggio genera un'eccezione | Input, stato prima, stato dopo se disponibile, contesto, classe dell'errore, messaggio di errore, traccia e durata |
| `step_branch_completed` | Quando un ramo parallelo termina correttamente | Input del ramo, output, stato prima e dopo, contesto e durata |
| `step_item_completed` | Quando un elemento di un ciclo for-each termina correttamente | Input dell'elemento, output, stato prima e dopo, metadati dell'elemento, contesto e durata |
| `workflow_waiting` | Quando un passaggio di attesa sospende l'esecuzione | Tipo di attesa, condizioni di attesa, modalità di attesa, chiave del risultato, metadati di corrispondenza e stato durante l'attesa |
| `workflow_resumed` | Quando una condizione di attesa viene soddisfatta | Dati per la ripresa, stato prima e dopo la ripresa |
| `workflow_replayed` | Quando un'esportazione viene ricreata | Metadati del flusso di lavoro di origine e stato della riproduzione |

## Consultare la cronologia

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

Ogni riga dell'evento contiene:

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

## Pacchetto di tracce normalizzato

Usate `workflow_trace()` per creare un debugger UI:

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

Il pacchetto di tracce include:

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

`steps` raggruppa gli eventi per indice del passaggio e include l'ultimo evento rilevante per ciascun passaggio.

## Ricerca dello stato del passaggio

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

Restituisce lo stato pubblico `state_after` dell'ultimo evento completato o ripreso per quel passaggio, oppure `null` se non è stato registrato alcuno stato.

## Metadati della traccia di runtime

I gestori possono aggiungere dettagli di traccia a livello applicativo durante l'esecuzione:

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

I gestori dei passaggi possono anche restituire metadati di traccia riservati:

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

La chiave `_queuety_trace` viene salvata nel registro eventi e non viene unita allo stato del flusso di lavoro.

## CLI

Visualizzate la cronologia in una tabella:

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

Visualizzate lo stato dopo un passaggio:

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

## Conservazione

I registri eventi si accumulano nel tempo. Usate `prune()` per eliminare gli eventi di traccia meno recenti:

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