debugging-with-ably-cli

Ably CLI を使ったデバッグ

Ably CLI（@ably/cli。npm install -g @ably/cli でインストール）を使うと、ターミナルから Ably の操作を監視、テスト、シミュレーションできます。console.log やブラウザーの DevTools よりもすばやく確認できます。

コマンドの確認： コマンドグループを確認するには ably --help、サブコマンド、フラグ、使用例を確認するには ably <command> --help を実行してください。CLI は自己説明型です。このスキルでは、何ができるか、いつ使うかを説明します。

---

1. 診断の判断ツリー

Messages not arriving
├── Is anyone on the channel?        → list channels with a prefix filter
├── Was anything published?          → check channel history (2 min only without persistence)
├── Can I see messages live?         → subscribe to the channel
├── Test round-trip                  → subscribe in background, publish from main terminal
└── Check channel lifecycle          → subscribe to channel lifecycle logs, or inspect the channel in the dashboard

Presence not working
├── Who is actually present?         → subscribe to presence on the channel
├── Simulate a client joining        → enter presence with custom client-id and data
├── Check presence member count      → get channel occupancy
│   (stale members? ungraceful disconnects take ~15s to be removed)
└── Watch all presence events        → subscribe to logs filtered by channel.presence, or inspect the channel in the dashboard

Connection problems
├── Can I connect at all?            → test connection (try ws and xhr separately)
├── Is Ably up?                      → check service status
├── Watch connection lifecycle       → subscribe to connection lifecycle logs
└── Connection count vs plan limit   → check app stats in live mode

Auth errors
├── Is the API key valid?            → test connection with the specific key
├── What capabilities does key have? → list auth keys
├── Using tokens (JWT or Ably)?      → issue a test token via CLI to verify the key can create valid tokens
│   (CLI token issuance tests the key, not your app's authUrl/authCallback)
├── Token expired (40142)?           → check TTL and renewal config (authUrl/authCallback)
└── Look up the error code           → ask the support agent or fetch help.ably.io/error/{code}

Channel state / lifecycle issues
├── Watch channel events             → subscribe to channel lifecycle logs
├── Watch all app meta events        → subscribe to all logs
├── Check channel occupancy          → get or subscribe to occupancy
└── Check channel rules/config       → list channel rules (persistence, TLS, push, etc.)

Push notifications not working
├── Watch push delivery logs         → subscribe to push logs (meta channel)
├── Check push log history           → get push log history
├── Is push enabled on namespace?    → list channel rules, check push-enabled
└── Check integration rules          → list integrations, check source type and channel filter

Integration rules not firing
├── List all integrations            → list integrations to see rules, source types, status
├── Check source type matches        → source can be channel.message, channel.presence,
│                                      channel.lifecycle, or presence.message
├── Check channel filter             → filter pattern must match the channel name
├── Is the rule enabled?             → check integration status (enabled/disabled)
└── Check for delivery errors        → check log history — the log metachannel captures
                                       errors sending on integrations

Queue issues
├── Are queues configured?           → list queues
├── Is the integration routing to it?→ list integrations, check AMQP rule target
└── Check message flow               → subscribe to the source channel to verify messages exist

Chat room issues (@ably/chat)
├── Are messages flowing?            → subscribe to room messages
│   (if CLI sees messages but app doesn't → room.attach() likely missing)
├── Check room presence              → subscribe to room presence
├── Check occupancy                  → get room occupancy
├── Check underlying channel events  → inspect the room's channels in the dashboard, or subscribe to channel lifecycle logs and look for the room's channel names
└── Send a test message              → send a message to the room from CLI

Spaces issues (@ably/spaces)
├── Who is in the space?             → subscribe to space members
├── Watch cursors                    → subscribe to space cursors
├── Watch locations                  → subscribe to space locations
└── Check locks                      → get all locks in the space

---

2. デバッグに役立つ重要な事実

• チャネル名では大文字と小文字が区別されます。 パブリッシャーとサブスクライバーで名前が一致しないことは、よくあるバグです。アクティブなチャネルを一覧表示して、実際に存在するチャネルを確認してください。
• 履歴のデフォルトは2分です。 永続化が有効でない場合、履歴は Ably の接続復旧期間のみを対象とします。チャネルルールで persisted: true が設定されているか確認してください。有効になっていない場合は、ユーザーにそのことを伝え、チャネルルールまたはダッシュボードから有効にするよう提案してください。
• プレゼンスには clientId と capability の両方が必要です。 clientId は接続時に設定する必要があり、プレゼンスへの参加時に設定するものではありません。プレゼンスへの参加には presence capability が必要で、プレゼンスイベントのサブスクライブには subscribe capability が必要です。クライアントは、自身が参加せずに誰がプレゼンスにいるかを確認できます。適切な capability がないと、プレゼンス操作は 40160 で失敗します。
• チャネル名に対する capability のスコープ。 publish:["chat:*"] を持つキーは、chat: で始まるチャネル（例：chat:room-1）への publish を許可しますが、chat という名前のチャネルへの publish は許可しません。コロン区切りとワイルドカードパターンが重要であり、これは 40160 エラーのよくある原因です。
• トークンの有効期限（40142）。 トークンには TTL があります。クライアントに更新用の authUrl または authCallback が設定されていない場合、トークンは期限切れになります。接続は失敗し、その他の API リクエストも拒否されます。アプリとは独立して認証フローが機能するか確認するには、CLI からトークンを発行してテストしてください。
• プレゼンスからの削除には遅延があります。 正常に切断されなかった場合、Ably によって削除されるまで約15秒かかります。
• 占有数から重複サブスクリプションがわかります。 サブスクライバー数が予想より大幅に多い場合は、サブスクリプションが重複していないか確認してください（React StrictMode、useEffect のクリーンアップ漏れ、複数の Ably クライアントインスタンスなど）。
• トークンとキーの capability。 キーと、そのキーから発行されたトークンでは、capability が異なる場合があります。トークンの権限は、キーの権限とトークンで指定された個別の権限の共通部分です。40160 エラーをデバッグするには、キーの capability と、サーバー上のトークン作成コードの両方を確認してください。
• メタチャネルのログには [meta]* capability が必要です。 すべての ably logs コマンドは、ログ用メタチャネル（[meta]log、[meta]channel.lifecycle など）をサブスクライブします。* にスコープされたキーはメタチャネルに一致しません。キーの capability リソースリストには [meta]* または [*]* が必要です。アプリのルート API キーには、デフォルトで [*]* が設定されています。ably logs コマンドが 40160 で失敗する場合は、キーの capability スコープを確認してください。単一チャネルを詳しく調査するには（チャネルごとの統計情報、リージョン別の内訳、接続されたインテグレーションなど）、ably channels inspect <channel> を使ってダッシュボードのチャネルインスペクターを開いてください。これは、現在 CLI では利用できない、特権付きの検査用メタチャネル（[meta]inspect:*）を使用します。
• トランスポートのフォールバック。 WebSocket がブロックされている場合、SDK は XHR ストリーミングにフォールバックします。どちらが機能するか確認するため、両方のトランスポートを個別にテストしてください。
• デフォルト以外の環境。 アプリがサンドボックスまたはカスタム環境を使用している場合は、ably accounts login --endpoint <host> でログインし、適切なクラスターを指定してください。
• エラーコードよりエラーメッセージのテキストを重視してください。 Ably のエラーコードは広いカテゴリを表します（例：40000 は多くの種類を含みます）。具体的な原因を特定するため、必ずエラーメッセージのテキストを確認してください。すべてのコードに help.ably.io/error/{code} のヘルプページがあります。または ably support ask "error {code}" を使用してください。

---

3. CLI 認証

CLI の使用には認証情報が必要です。方法は 2 つあります。

プロジェクトの認証情報を使用する（手軽で、ログイン不要）： 環境変数として ABLY_API_KEY を設定します。プロジェクトの環境設定ファイルからキーを見つけてエクスポートします（例：export ABLY_API_KEY=...）。または、トークン（アプリの認証サーバーから取得したものなど）がある場合は、代わりに ABLY_TOKEN を使用します。本番アプリ用のキーの場合は、使用する前にそのことをユーザーに伝えてください。

CLI にログインする（詳しいデバッグやアカウントレベルのコマンドを使用する場合）： ably login を実行すると、OAuth 認証のためにブラウザーが開きます。ログインしたら、ably apps list と ably apps switch を使用して適切なアプリを選択し、ably auth keys list で利用可能なキーとその機能を確認します。

認証情報が利用できない場合は、Ably の環境変数（例：ABLY_API_KEY）が設定されていることをユーザーに確認してもらうか、ably login を実行して認証するよう依頼してください。

---

4. CLI でできること

監視（読み取り専用）

チャネル、プレゼンス、占有状況、ログ、統計情報をリアルタイムでサブスクライブし、Ably が認識している情報をそのまま確認できます。

• チャネルメッセージ：1 つ以上のチャネルをサブスクライブします。ワイルドカードと巻き戻し（アタッチ時に最近のメッセージを再生）に対応しています。
• プレゼンス：参加・退出するユーザーと、そのクライアント ID およびデータペイロードを監視します。
• 占有状況：チャネル上のパブリッシャー、サブスクライバー、プレゼンスメンバーのスナップショットまたはライブストリームを確認します。
• ログ（メタチャネル）：チャネルのライフサイクル、接続のライフサイクル、プレゼンスイベント、プッシュ通知の配信ログを確認します。種類（channel.lifecycle、channel.occupancy、channel.presence、connection.lifecycle、push.publish）でフィルタリングし、巻き戻して最近のイベントを捕捉できます。
• プッシュ通知ログ：専用のプッシュログストリームと履歴を確認し、配信の試行や失敗、デバイスの対象指定を把握します。
• 履歴：チャネル上の過去のメッセージを確認します（永続化なしの場合は 2 分間です。Key Debugging Facts を参照してください）。
• 統計情報：アプリまたはアカウントの統計情報を、ライブポーリングモードで確認します。接続数がプランの上限内かどうかを確認できます。
• チャネル一覧：現在アクティブなチャネルを、プレフィックスで絞り込んで表示します。
• 接続テスト：複数のトランスポート（WebSocket、XHR）で接続を確認し、ネットワークやプロキシの問題を切り分けます。

シミュレーション

参加者として動作し、会話の片方をシミュレートして、もう片方をテストします（サーバーのデバッグ時はクライアント、クライアントのデバッグ時はサーバーをシミュレートします）。

• パブリッシュ：イベント名、JSON、またはプレーンテキストを含むメッセージを送信します。設定可能な回数と間隔で繰り返しパブリッシュして、トラフィックをシミュレートできます。
• 一括パブリッシュ：1 回のリクエストで複数のチャネルにパブリッシュします。
• プレゼンスへの参加：カスタムのクライアント ID とデータ（例：{"role": "server"}）を指定してチャネルに参加します。
• チャット：メッセージ、プレゼンス、入力中の表示、リアクションを含むルーム全体をシミュレートします。
• Spaces：メンバー、カーソル、位置情報、ロックを扱います。
• ベンチマーク：レートとメッセージサイズを設定して、パブリッシャー／サブスクライバーのスループットとレイテンシをテストします。

管理

アプリの設定を照会・変更して、設定関連の問題を診断します。

• チャネルルール（名前空間）：永続化、プッシュ、TLS のみ、バッチ処理、コンフレーション、チャネルレジストリの設定を確認・設定します。
• API キー：機能の一覧表示、作成、失効、アクティブキーの切り替えを行います。
• トークン発行：JWT（またはアプリが Ably トークンを使用している場合は Ably トークン）を発行し、認証フローを個別にテストします。トークンの失効もできます。
• アプリ：一覧表示、作成、切り替え、設定を行います。
• インテグレーション：Webhook、Lambda、Kafka、AMQP などのインテグレーションルールを一覧表示して調べます。ソースタイプ（channel.message、channel.presence、channel.lifecycle、presence.message）、チャネルフィルター、有効／無効の状態を確認します。
• キュー：Ably メッセージキューの一覧表示、作成、削除を行います。

ヘルプを利用する

• AI サポートエージェント（Inkeep 提供）：ably support ask "your question" — Ably のドキュメントと FAQ を検索します。追加の質問には --continue を使用します。
• サービスのステータス：ably status でプラットフォームの稼働状況を確認します。

---

5. 長時間実行されるコマンド

多くのコマンド（subscribe、presence enter、stats --live、occupancy subscribe）は長時間実行され、Ctrl+C を押すか --duration N の時間が経過するまで出力をストリーミングします。これらはバックグラウンドタスクとして実行し、ワークフローを妨げないようにしてください。subscribe をバックグラウンドで開始し、問題を再現してから出力を確認します。

---

6. 接続とチャネルの状態リファレンス

接続状態

状態	意味	診断
connecting	接続を試行中	起動時は正常です。ここで止まる場合は、ネットワークと認証を確認してください
connected	WebSocket がアクティブ	正常です
disconnected	一時的な切断。SDK が再試行します	一時的な切断は正常です。繰り返し発生する場合はネットワークの問題です → 接続ライフサイクルのログを確認してください
suspended	2 分以上オフラインで、再試行の頻度が低下しています	接続テストで接続状態を確認してください
failed	永続的な失敗。SDK は再試行しません	ほぼ常に認証が原因です。対象の API キーでテストしてください
closed	コードによって明示的に閉じられました	.close() の呼び出しを検索してください

チャネル状態

状態	意味	診断
initialized	チャネルオブジェクトが作成されましたが、まだアタッチされていません	最初の subscribe または publish の前は正常です
attaching	サーバーにアタッチをリクエスト中	ここで止まる場合は、接続状態と認証機能を確認してください
attached	アクティブで、メッセージが流れています	正常です
detaching	デタッチをリクエスト中	クリーンアップ中は正常です
detached	アタッチされておらず、メッセージも流れていません	detach() が意図的に呼び出されたか確認してください
suspended	アタッチに失敗しましたが、再試行されます	通常は接続の一時停止に続いて発生します。まず接続状態を確認してください
failed	チャネルで永続的な障害が発生しています	多くの場合、機能が拒否された（40160）か、チャネル名が無効です

---

7. 環境固有の注意点

環境	症状	根本原因	診断
Next.js SSR	レンダリング中に接続が失敗する	サーバーサイドレンダリングでは WebSocket を利用できません	typeof window または useEffect でガードします
Serverless（Lambda、Edge）	接続が古い、またはフリーズする	呼び出しの間に接続がフリーズします	サーバーサイドでは Ably.Rest を使用してください
React StrictMode	メッセージが重複する、プレゼンスがちらつく	二重レンダリングによってサブスクリプションが重複します	occupancy を確認してください。予想より大幅に高い場合は重複しています
CSP ヘッダー	WebSocket がブロックされる	Ably ドメインが connect-src に含まれていません	接続をテストしてください。ws は失敗し、xhr は動作する場合は CSP が原因です
企業プロキシ	WebSocket が通知なしに失敗する	プロキシがアップグレードをブロックしています	接続をテストしてください。ws は失敗し、xhr は動作する場合はプロキシが原因です
モバイルのバックグラウンド	復帰後にメッセージを受信できない	OS が WebSocket を終了します	チャネル履歴で、切断中に送信されたメッセージを確認してください