# 워크플로 이벤트 로그

워크플로 이벤트 로그는 모든 영구 워크플로 경계의 추적 기록을 저장합니다. 각 추적 이벤트에는 단계 입력과 출력, 단계 실행 전후의 공개 상태, 런타임 컨텍스트, 아티팩트 참조, 스트리밍 청크, 실행 시간 및 오류 세부 정보가 포함될 수 있습니다.

## 기록되는 내용

| 이벤트 | 발생 시점 | 기록 데이터 |
|---|---|---|
| `step_started` | 단계 핸들러 실행 전 | 작업 ID, 큐, 시도 횟수, 단계 이름, 단계 유형, 입력 및 실행 전 상태 |
| `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`

## 정규화된 추적 번들

디버거 UI를 만들 때 `workflow_trace()`을 사용하세요.

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