# keenauth events tail によるイベントの追跡

`keenauth events tail` は、環境のイベント API を読み取り、顧客のイベント（例: `user.created`）が発生するたびに出力します。ここで扱うイベントは Webhook の配信と同じもので、エンベロープも `id` も同一です。連携先が受け取る内容を確認したり、操作によって想定どおりのイベントが発生したかを確かめたりするために使用します。停止するには Ctrl-C を押します。その場合、コマンドは終了コード 0 で終了します。

このコマンドには `events:read` 権限が必要です。API キーと `keenauth login` のセッションのどちらでも動作します。

## 使い方

```sh
keenauth events tail --types user.created,user.updated
```

| フラグ | 説明 |
|---|---|
| `--types` | 指定したイベントタイプのみを表示します。カンマ区切りまたは繰り返し指定できます。 |
| `--org` | この組織 (`org_…`) のイベントのみを表示します。 |
| `--payload` | `thin`（既定）または `full`。`full` ではリソースが含まれ、`users:read` 権限も必要です。 |
| `--after` | 開始位置。`latest`（既定）では、現時点以降に発生したイベントのみを表示します。以前の実行で表示されたカーソルを指定すると、そこから続きを表示します。 |
| `--interval` | 新しいイベントがない場合の確認間隔。`1s` から `60s` の範囲で指定します。既定値: `5s`。 |
| `--output`, `-o` | `table`、`json`、`yaml` のいずれか。フラグを省略すると、ターミナルでは表形式、それ以外では JSON で出力されます。 |

無効なフィルター、カーソル、または間隔を指定すると、リクエストを送信する前に、終了コード 2 でコマンドが停止します。

## 出力

- `table`: イベントごとに 1 行で、時刻、タイプ、シーケンス番号、イベント ID を表示します。
- `json`: 各イベントをサーバーから届いた形式のまま、1 行に 1 つの JSON オブジェクトとして出力します（改行区切りの JSON）。標準出力がターミナルでない場合の既定値です。
- `yaml`: イベントごとに 1 つの YAML ドキュメントを出力します。各ドキュメントは `---` で始まります。

イベントは環境のイベント順序 (`seq`) で出力されます。コマンドを停止すると、再開に使うカーソルを標準エラー出力に表示します。

```text
to continue from here: --after <cursor>
```

後で `keenauth events tail --after <cursor>` を実行すると、その間に取り逃したイベントを表示できます。イベントは 30 日間保持されます。

## 追跡の仕組み

コマンドは、カーソル以降のイベントを要求し、それらを出力して、レスポンスが返すカーソルへ移動します。レスポンスで待機中のイベントがあることが示されている場合は、すぐに再度要求します。そうでない場合は `--interval` の時間待機してから、再度要求します。

## 終了コード

| コード | 意味 |
|---|---|
| `0` | Ctrl-C で停止しました。 |
| `1` | サーバーエラーまたはネットワークエラーが発生しました（例: 別の環境のカーソルを指定した場合）。 |
| `2` | 使い方のエラー: フィルター、カーソル、間隔、または出力形式が無効です。リクエストは送信されていません。 |
| `3` | 認証情報がないか、サーバーが `401` または `403` を返しました。 |
| `4` | 契約プランに、この機能が含まれていません（`plan_feature_unavailable` を伴う `403`）。 |