トラブルシューティング
オペレーターとワークフロー実行時の一般的な問題の診断と解決
概要
本ガイドは、Supervity のオペレーター、ワークフロー、連携、スケジュール、承認で作業する際の 一般的な問題の診断と解決 を支援します。
Supervity は障害が次の特性を持つよう設計されています。
- 可視
- 回復可能
- 監査可能
ほとんどの問題は ワークフローを再構築せずに 解決できます。
実行の問題
実行が即座に失敗する
症状
- 開始直後に実行が失敗する
- ログにエラーが表示される
- ステップが完了しない
確認事項
- ステップ設定が有効である
- 必須入力が存在する
- 連携が接続されている
- 権限とスコープが正しい
修正
- 設定を修正する
- 必要に応じて連携を再接続する
- 権限を確認する
- 実行を再試行する（再構築不要）
実行がハングまたはタイムアウトする
症状
- 長時間実行が続く
- ステップが完了しない
- 最終的にタイムアウトする
対処
- 実行が停止しているステップを特定する
- 外部サービスの健全性を確認する
- データサイズを削減するか入力をバッチ化する
- 適切な場合はタイムアウトを延長する
- 可能な限り並列実行を使用する
連携の問題
連携を接続できない
症状
- OAuth ウィンドウが失敗する
- 承認エラーが表示される
確認事項
- ブラウザのポップアップが有効である
- シークレットまたはプライベートモードを試す
- 外部システムで管理者アクセスがあることを確認する
- 承認を再試行する
連携が頻繁に切断される
症状
- 「Reconnect required」メッセージが頻繁に表示される
- トークン有効期限切れエラー
一般的な原因
- パスワード変更
- 外部でのトークン取り消し
- サービスアカウント制限
修正
- 連携を再接続する
- サポートされている場合はサービスアカウントを優先する
- 該当する場合は API キーをローテーションする
連携アクションが失敗する
症状
- 連携は接続されている
- 実行中に特定のアクションが失敗する
確認事項
- アクションレベルの権限
- リソースの存在（file、record、object）
- API レート制限
- 実行頻度
修正
- 権限を調整する
- 頻度を下げるかリクエストをバッチ化する
- 再試行またはバックオフを追加する
人間レビューの問題
レビュー通知が届かない
症状
- レビュー待ちの実行
- レビュアーに通知されない
確認事項
- レビュアーのメールまたはロール割り当て
- 通知設定
- スパムまたは迷惑メールフォルダ
- レビューリクエストの再送信
レビューフォームを送信できない
症状
- 送信ボタンが無効
- 送信時にエラー
修正
- すべての必須フィールドが入力されていることを確認する
- ページを更新するか再認証する
- 別のブラウザを試す
- 新しいレビューリンクをリクエストする
レビュー待ちで実行が停止
症状
- ワークフローが無期限に一時停止
修正
- タイムアウトとエスカレーション設定を確認する
- バックアップレビュアーにエスカレーションする
- 管理者が手動で承認、却下、またはキャンセルできる
- 今後の実行向けにレビュー設定を調整する
→ 人間によるレビューと承認 を参照
スケジューリングの問題
スケジュール実行が行われなかった
症状
- スケジュールは有効
- 実行が発生しなかった
チェックリスト
- スケジュールは有効か？
- 開始時刻は過去か？
- 正しいタイムゾーンが選択されているか？
- ワークフローは手動で実行できるか？
- プラットフォーム障害はあったか？
スケジュール実行が誤った時刻に行われた
症状
- 実行が数時間ずれている
- 期待した実行がスキップされた
修正
- タイムゾーン設定を確認する
- cron 式を確認する
- サマータイムの変更を考慮する
- グローバル一貫性のために UTC を使用する
データと変数の問題
変数が {{variable}} と表示される
症状
- テンプレートがレンダリングされない
- 空または未解決の値
確認事項
- 変数名（大文字小文字を区別）
- 生成ステップが正常に完了した
- 変数スコープ（loop と global）
- オプション値のデフォルト
データフォーマットまたはパースエラー
症状
- 型不一致エラー
- パース失敗
修正
- 明示的な変換ステップを追加する
- 早期に入力を検証する
- null または空の値を処理する
- 意図的にデータ型を変換する
API と開発者の問題
API 呼び出しが失敗する
チェックリスト
- トークンが有効である
- 正しい環境（prod と staging）
- 必要な権限が付与されている
- 正しい content type
- レート制限を超過していない
→ API リファレンス を参照
ストリーミングまたはチャットが停止しているように見える
症状
- SSE ストリームから応答がない
- 実行が凍結しているように見える
修正
- 接続を開いたままにする
- ファイアウォールまたはプロキシ設定を確認する
- Idempotency-Key を使用する
- 必要に応じて新しいスレッドで再試行する
サポートへの連絡
以下の場合はサポートに連絡してください。
- 問題が一貫して再現可能
- ログが失敗を説明しない
- 実行がブロックされ時間的制約がある
- プラットフォームの問題を疑う
含める情報
- ワークフロー名と ID
- Run ID
- タイムスタンプ
- エラーメッセージ
- 既に試した手順
📧 support@supervity.com
💬 アプリ内チャット
👥 コミュニティフォーラム
予防的ベストプラクティス
本番稼働前
- 現実的なデータでテストする
- 重要アクションに承認を追加する
- 限定的な権限から開始する
- 初期実行を密に監視する
継続的
- 定期的にログを確認する
- 定期的に連携を監査する
- 未使用ワークフローを削除する
- 長時間実行オペレーターを最適化する
クイック診断チェックリスト
エスカレーション前に以下を確認してください。
- オペレーター計画が意図と一致している
- 必須入力が提供されている
- 連携が接続されている
- 権限が十分である
- 保留中の人間レビューがない
- 実行ログを確認した
関連リソース
ほとんどの問題は通常の運用の一部です。
Supervity は 障害がサイレントに失敗するのではなく、安全に一時停止する よう設計されています。
ja/guides/troubleshooting.md