# ワークフローイベントログ

ワークフローイベントログは、永続化されたワークフローの各境界についてトレースを記録します。各トレースイベントには、ステップの入力、出力、ステップ実行前の公開状態、実行後の公開状態、実行時コンテキスト、アーティファクト参照、ストリーミングチャンク、タイミング、エラーの詳細を含められます。

## 記録される内容

| イベント | 発生時点 | 記録されるデータ |
|---|---|---|
| `step_started` | ステップハンドラーの実行前 | ジョブID、キュー、試行回数、ステップ名、ステップ型、実行前の入力と状態 |
| `step_completed` | ステップハンドラーの成功後 | 入力、出力、実行前の状態、実行後の状態、コンテキスト、アーティファクト、チャンク、所要時間 |
| `step_failed` | ステップハンドラーが例外をスローしたとき | 入力、実行前の状態、取得可能な場合は実行後の状態、コンテキスト、エラークラス、エラーメッセージ、トレース、所要時間 |
| `step_branch_completed` | 並列分岐の1つが成功したとき | 分岐の入力、出力、実行前の状態、実行後の状態、コンテキスト、所要時間 |
| `step_item_completed` | for-eachの項目が1つ成功したとき | 項目の入力、出力、実行前の状態、実行後の状態、項目のメタデータ、コンテキスト、所要時間 |
| `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 );
```