superplane-monitor

SuperPlane モニター

ワークフローの実行を調査、デバッグ、管理します。

クイックリファレンス

タスク	コマンド
アプリの実行一覧を表示	superplane runs list --app-id <id>
実行の詳細を表示（ノードの実行）	superplane runs describe <run-id> --app-id <id>
ノードの実行一覧を表示	superplane executions list --app-id <id> --node-id <nid>
実行をキャンセル	superplane executions cancel --app-id <id> --execution-id <eid>
キュー内の項目を表示	superplane queue list --app-id <id> --node-id <nid>
キュー内の項目を削除	superplane queue delete --app-id <id> --node-id <nid> --item-id <iid>

CLI がインストールされていることを確認する

デバッグを始める前に、ネットワーク接続なしで CLI バイナリを利用できることを確認します。

command -v superplane

パスが表示されない場合は、ここで作業を中止し、https://docs.superplane.com/installation/cli から CLI をインストールするようユーザーに伝えてください。デバッグでは、実行、ノードの実行、キューを調査するために CLI が必要です。

次に、現在のセッションを確認します。

superplane whoami

認証、DNS、タイムアウト、接続の問題により whoami が失敗する場合、CLI はインストールされていますが、セッションはまだ利用できません。CLI を使ってデバッグを始める前に、必要に応じて接続、コンテキストの修正、ネットワークアクセスの許可を行うようユーザーに伝えてください。

デバッグでキャンバスの編集が必要な場合は、変更をステージしてコミットするか、--message を指定して直接適用します。

superplane apps staging update --file canvas.yaml
superplane apps staging commit --message "Fix canvas"
# or:
superplane apps canvas update -f canvas.yaml --message "Fix canvas"

デバッグのワークフロー

1. アプリを見つける

superplane apps list

2. 最近の実行を一覧表示する

superplane runs list --app-id <app_id>

各実行は、キャンバス全体を通じてトリガーが発火したものです。

3. 実行を調査する

superplane runs describe <run_id> --app-id <app_id>

次のようなノードの実行を確認します。

• Failed（失敗） — エラーが発生したノード
• Pending/Running（保留中／実行中） — 停滞している可能性があります
• Skipped（スキップ） — 分岐（If/Filter）によって迂回されています

4. ノードの履歴とペイロードを調査する

superplane executions list --app-id <app_id> --node-id <node_id> -o yaml

失敗が繰り返し発生しているか確認します。式のエラーの場合は、実際のペイロード構造を調査します。

• rootEvent.data.data — トリガーの実際のイベントペイロード（2 つの .data は、Webhook ペイロードを包むイベントエンベロープです）
• input — 上流ノードからノードが受け取ったデータ（こちらも { data, timestamp, type } エンベロープを持ちます）
• resultMessage — 式のどのフィールドが nil だったかを含む、正確なエラー

ドキュメントから推測するのではなく、これらの実際のペイロードを使って式のパスを修正してください。

分岐やチャネルに関する問題では、実行 YAML の outputs を調査します（トップレベルの result だけでは不十分です）。

• ノードの result: RESULT_PASSED が表示されていても、failure チャネルにルーティングされる場合があります。これらは独立しています（ランタイムの健全性と意味上のルーティング）。バグと判断する前に、実行結果と出力チャネルを参照してください。
• outputs の出力チャネル名が、エッジの接続（success、failed、default など）と一致することを確認します。
• 下流の動作が runs describe の表示と一致しない場合、ルーティングの実態はノードの outputs ブロックを基準に判断してください。

5. 修正して再実行する

キャンバスを更新した後、UI から、またはテンプレートを設定した start（Manual Run）トリガーを使って、新しい実行を開始します。

superplane apps staging update --file canvas.yaml
superplane apps staging commit --message "Fix canvas"
# or:
superplane apps canvas update -f canvas.yaml --message "Fix canvas"

よくある失敗パターン

認証エラー

ノードが権限エラーで直ちに失敗します。次を確認します。

superplane integrations list
superplane secrets list

インテグレーションが接続されており、シークレットが有効であることを確認します。

式のエラー

ノードが存在しないフィールドを参照して失敗します。次を確認します。

• $['Node Name'] のノード名が完全に一致している（大文字と小文字を区別）
• 上流ノードが実際に想定したフィールドを出力している
• ルートペイロードに想定したデータが含まれている

キューの停滞

実行が進まず、キューにたまっていきます。

superplane queue list --app-id <id> --node-id <nid>

原因：ノードが一時停止している、Approval が人間の入力を待っている、Time Gate が保留している、外部サービスが応答していない。

停滞している項目を削除します。

superplane queue delete --app-id <id> --node-id <nid> --item-id <iid>

Merge が実行されない

Merge はすべての入力エッジを待機します。いずれかの分岐が停滞、フィルターで除外、または失敗していると、Merge は停止します。すべての上流分岐を確認してください。

他のスキルを使う場面

必要な作業	使用するスキル
キャンバスの作成または変更	superplane-app-builder
CLI コマンドと認証	superplane-cli

ドキュメント

URLを取得できるエージェント向けに、SuperPlaneのドキュメント全文をLLM向けの形式で提供しています。

• コンパクトなインデックス：https://docs.superplane.com/llms.txt
• 全コンテンツ：https://docs.superplane.com/llms-full.txt