# Registro de eventos do fluxo de trabalho

O registro de eventos do fluxo de trabalho guarda um rastreamento para cada limite durável do fluxo. Cada evento de rastreamento pode incluir a entrada e a saída da etapa, o estado público antes e depois da etapa, o contexto de execução, referências a artefatos, blocos transmitidos, tempos e detalhes de erros.

## O que é registrado

| Evento | Quando | Dados capturados |
|---|---|---|
| `step_started` | Antes da execução do manipulador da etapa | ID do trabalho, fila, tentativa, nome e tipo da etapa, entrada e estado antes da execução |
| `step_completed` | Depois que o manipulador da etapa é executado com sucesso | Entrada, saída, estado antes, estado depois, contexto, artefatos, blocos e duração |
| `step_failed` | Quando o manipulador da etapa lança uma exceção | Entrada, estado antes, estado depois quando disponível, contexto, classe do erro, mensagem de erro, rastreamento e duração |
| `step_branch_completed` | Quando uma ramificação paralela é concluída com sucesso | Entrada da ramificação, saída, estado antes, estado depois, contexto e duração |
| `step_item_completed` | Quando um item de um loop for-each é concluído com sucesso | Entrada do item, saída, estado antes, estado depois, metadados do item, contexto e duração |
| `workflow_waiting` | Quando uma etapa de espera suspende a execução | Tipo de espera, destinos da espera, modo de espera, chave do resultado, metadados de correspondência e estado durante a espera |
| `workflow_resumed` | Quando uma etapa de espera é atendida | Dados de retomada, estado antes da retomada e estado depois da retomada |
| `workflow_replayed` | Quando uma exportação é recriada | Metadados do fluxo de trabalho de origem e estado da reprodução |

## Consultar a linha do tempo

```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 linha de evento contém:

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

## Pacote de rastreamento normalizado

Use `workflow_trace()` ao criar um depurador UI:

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

O pacote de rastreamento inclui:

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

`steps` agrupa eventos por índice de etapa e inclui o evento importante mais recente de cada etapa.

## Consulta do estado da etapa

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

Isso retorna o estado público `state_after` do evento concluído ou retomado mais recente dessa etapa, ou `null` quando nenhum estado foi registrado.

## Metadados de rastreamento em tempo de execução

Os manipuladores podem adicionar detalhes de rastreamento no nível da aplicação enquanto são executados:

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

Os manipuladores de etapas também podem retornar metadados de rastreamento reservados:

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

A chave `_queuety_trace` é armazenada no registro de eventos e não é mesclada ao estado do fluxo de trabalho.

## CLI

Veja a linha do tempo em uma tabela:

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

Veja o estado após uma etapa:

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

## Retenção

Os registros de eventos se acumulam com o tempo. Use `prune()` para excluir eventos de rastreamento antigos:

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