# Registro de eventos del flujo de trabajo

El registro de eventos del flujo de trabajo guarda una traza de cada límite duradero del flujo de trabajo. Cada evento de traza puede incluir la entrada y la salida del paso, el estado público antes y después del paso, el contexto de ejecución, referencias a artefactos, fragmentos transmitidos, tiempos y detalles de errores.

## Qué se registra

| Evento | Cuándo | Datos registrados |
|---|---|---|
| `step_started` | Antes de que se ejecute un controlador de paso | ID del trabajo, cola, intento, nombre del paso, tipo de paso, entrada y estado antes de la ejecución |
| `step_completed` | Después de que un controlador de paso finalice correctamente | Entrada, salida, estado anterior, estado posterior, contexto, artefactos, fragmentos y duración |
| `step_failed` | Cuando un controlador de paso lanza una excepción | Entrada, estado anterior, estado posterior si está disponible, contexto, clase de error, mensaje de error, traza y duración |
| `step_branch_completed` | Cuando una rama paralela finaliza correctamente | Entrada de la rama, salida, estado anterior, estado posterior, contexto y duración |
| `step_item_completed` | Cuando un elemento de un bucle «for each» finaliza correctamente | Entrada del elemento, salida, estado anterior, estado posterior, metadatos del elemento, contexto y duración |
| `workflow_waiting` | Cuando un paso de espera aparca la ejecución | Tipo de espera, objetivos de espera, modo de espera, clave del resultado, metadatos de coincidencia y estado durante la espera |
| `workflow_resumed` | Cuando se cumple una condición de espera | Datos de reanudación, estado antes de reanudar y estado después de reanudar |
| `workflow_replayed` | Cuando se vuelve a crear una exportación | Metadatos del flujo de trabajo de origen y estado de reproducción |

## Consultar la cronología

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

Cada fila del 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`

## Paquete de trazas normalizado

Use `workflow_trace()` al crear una UI de depuración:

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

El paquete de trazas incluye:

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

`steps` agrupa los eventos por índice de paso e incluye el último evento importante de cada paso.

## Búsqueda del estado del paso

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

Esto devuelve el `state_after` público del último evento completado o reanudado de ese paso, o `null` si no se registró ningún estado.

## Metadatos de la traza de ejecución

Los controladores pueden añadir detalles de la traza a nivel de aplicación mientras se ejecutan:

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

Los controladores de pasos también pueden devolver metadatos de traza reservados:

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

La clave `_queuety_trace` se almacena en el registro de eventos y no se combina con el estado del flujo de trabajo.

## CLI

Vea la cronología como una tabla:

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

Vea el estado después de un paso:

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

## Retención

Los registros de eventos se acumulan con el tiempo. Use `prune()` para eliminar eventos de traza antiguos:

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