# イベント履歴

イベント履歴は、EMQXデプロイメントからの最近のクライアント接続、認証、およびサブスクリプションイベントを記録するトラブルシューティングツールです。接続失敗、予期しない切断、認証失敗、効果のないサブスクリプションの調査に利用できます。正確で多次元の検索には、EMQX Tablesを使用してください。

イベント履歴は、EMQX v6.1.3以降を実行しているDedicatedおよびDedicated Flexデプロイメントで利用可能です。ServerlessやBYOCデプロイメントではサポートされていません。

## イベント履歴を使うタイミング

イベント履歴は、クライアントのライフサイクル中に発生するイベントの相関関係を把握するのに役立ちます。例えば、以下のような用途があります。

- クライアントが接続に失敗した理由を調査するために、**Client Connack** および **Authentication Completed** イベントを確認する。
- 予期しない切断の原因を調査するために、**Client Disconnected** イベントの理由を確認する。
- クライアントが使用したトピックとQoSを検証するために、**Session Subscribed** および **Session Unsubscribed** イベントを確認する。
- イベントのタイムスタンプを比較して、クライアントの接続、認証、サブスクリプション操作の順序を再構築する。

イベント履歴はデータ統合TPSを消費します。頻繁にクライアントが接続または再接続するデプロイメントは、より多くのイベントを生成し、より多くのTPSを消費します。イベント履歴を有効にする前に、デプロイメントに十分なデータ統合TPS容量があることを確認してください。

## イベント履歴の有効化

イベント履歴を有効にする前に、以下を確認してください。

- デプロイメントが稼働中であること。
- デプロイメントがDedicatedまたはDedicated Flexであること。
- デプロイメントがEMQX v6.1.3以降を実行していること。
- デプロイメントに十分なデータ統合TPS容量があること。

イベント履歴を有効にする手順は以下の通りです。

1. EMQX Cloudコンソールでデプロイメントを開きます。
2. 左側のナビゲーションメニューで **Diagnostics** -> **Event History** をクリックします。
3. **Enable Now** をクリックします。
4. 確認ダイアログで **Confirm** をクリックします。

ページに **Enabled** ステータスが表示され、EMQXはサポートされているクライアントライフサイクルイベントの記録を開始します。追加のイベント設定は不要です。イベント履歴が有効化された後に発生したイベントのみが記録され、有効化前のイベントは遡って記録されません。

## イベントの検索と確認

イベントの上限はデフォルトで100件です。クライアントや特定の種類のアクティビティに絞り込む場合はフィルターを利用してください。各クエリはデプロイメント内のすべてのEMQXノードのローカルイベントログを読み取り、最新の一致するイベントを集約します。

### イベントのフィルター

以下のフィルターと結果上限が利用可能です。

| フィルター | 一致方法 | 上限 |
| --- | --- | --- |
| **Client ID** | 含む（大文字小文字区別） | 256文字 |
| **Username** | 含む（大文字小文字区別） | 256文字 |
| **IP Address** | 完全一致 | 256文字 |
| **Topic** | 含む（MQTTトピックフィルターの意味論は適用しない） | 256文字 |
| **Event Type** | 完全一致 | リストからサポートされているイベントタイプを選択 |
| イベント上限 | 返される最大イベント数 | `100`（デフォルト）、`500`、`1,000`、`5,000`、`10,000` |

イベントを検索する手順：

1. 1つ以上のフィルターを入力または選択します。すべてのフィルターを空欄にすると、すべてのサポートされているタイプの最近のイベントを検索します。
2. 返す最大イベント数を選択します。
3. 検索アイコンをクリックします。
4. 返されたイベントを確認します。イベント横の展開アイコンをクリックすると詳細を確認できます。

すべてのフィルター値をクリアするにはクリアアイコンをクリックします。現在のフィルターで最新のスナップショットを取得するには更新アイコンをクリックします。

![Filter and query events](./_assets/event-history-query.png)

### 結果の解釈

イベント一覧には以下の情報が表示されます。

- **Time**: イベント発生時刻（秒単位の精度）とUTCオフセット。
- **Event Type**: コンソール上のイベント名（例：**Client Connected**、**Authentication Completed**、**Session Subscribed**）。
- **Client ID**: クライアント識別子。
- **IP Address**: 利用可能な場合はクライアントのIPアドレスとポート。ポートがない場合はIPアドレスのみ表示。
- **Reason**: 利用可能な場合の結果や理由。例えば認証イベントでは `success`、切断イベントでは `internal_error` のような理由が表示されます。

展開された詳細はイベントタイプによって異なります。**Username**、**Topic**、**QoS**、**Connected At**、**Protocol Name**、**Protocol Version**などが含まれます。空のフィールドやメインリストに既に表示されているフィールドは省略されます。

![Inspect event details](./_assets/event-history-event-details.png)

クエリ結果はローカルページネーションを使用し、1ページあたり10件のイベントを表示します。ページを切り替えてもEMQXへの再クエリは行われません。新しい検索開始、フィルターのクリア、結果の更新を行うと新たなクエリが送信され、1ページ目に戻ります。

## サポートされているイベントタイプ

**Event Type** リストには以下のクライアントライフサイクルイベントが含まれます。

| コンソールイベントタイプ | 内部イベントタイプ | 説明 |
| --- | --- | --- |
| **Client Connected** | `client.connected` | クライアントがEMQXに正常に接続した。 |
| **Client Disconnected** | `client.disconnected` | クライアントがEMQXから切断した。予期しない切断のトラブルシューティング時は **Reason** を確認する。 |
| **Client Connack** | `client.connack` | EMQXがクライアントにCONNACKパケットを送信した。 |
| **Authentication Completed** | `client.check_authn_complete` | クライアントの認証試行が完了した。結果は **Reason** で確認する。 |
| **Session Subscribed** | `session.subscribed` | クライアントがトピックをサブスクライブした。イベントを展開してトピックとQoSを確認できる。 |
| **Session Unsubscribed** | `session.unsubscribed` | クライアントがトピックのサブスクライブを解除した。イベントを展開してトピックとQoSを確認できる。 |

イベント履歴は `$events/message/delivery_dropped` のようなメッセージイベントは記録しません。

## イベント履歴の無効化

イベント履歴を無効にするには：

1. **Event History** ページを開きます。
2. 右上の **Disable** をクリックします。
3. 操作を確認します。

イベント履歴が無効化されると、EMQXは新しいイベントの記録を停止します。記録済みのイベントはすぐには削除されず、ディスクログのローテーションやEMQXノードの置き換えまでクエリ結果に表示される可能性があります。イベント履歴はいつでも再度有効化できます。

## 利用上の注意と制限

- **イベントは速やかにクエリしてください**：イベント履歴はローカルディスクログを使用しており、固定の保持期間を保証しません。利用可能な期間はイベント量、ディスク空き容量、ログローテーションに依存します。
- **各クエリはスナップショットとして扱う**：イベント履歴はサーバー側ページネーションや時間範囲クエリをサポートしません。別々のクエリ結果は独立したスナップショットであり、連続性は保証されません。
- **絞り込みフィルターを活用する**：イベント履歴は最近のクライアント活動のトラブルシューティング向けです。正確で多次元の検索にはEMQX Tablesを使用してください。
- **過剰なクエリを避ける**：各デプロイメントは60秒間に最大30回のイベント履歴クエリをサポートします。失敗したリクエストもこの制限にカウントされます。制限を超えたリクエストは `429 Too Many Requests` を返します。
- **結果上限を守る**：クエリは最大10,000件のイベントを返します。