Skip to content

デバッグガイド

アノテーションプロジェクトのデバッグフラグ、ログオプション、トラブルシューティングのヒント。

デバッグガイド

Potatoは、アノテーションプロジェクトのデバッグとテストに役立つコマンドラインフラグと設定オプションを提供しています。これらは開発中やトラブルシューティング時に有用です。

サーバー設定

YAML設定ファイルでサーバー設定を直接構成できます：

yaml
server:
  port: 8000        # Port to run on (default: 8000)
  host: "0.0.0.0"   # Host to bind to (default: 0.0.0.0)
  debug: false      # Enable Flask debug mode (default: false)

注意： CLIフラグは設定ファイルの値よりも優先されます。例えば、-p 9000はserver.port: 8000を上書きします。

デバッグフラグ

--debug

簡略化された認証でPotatoをデバッグモードで起動します。

bash
potato start config.yaml --debug

効果：

  • 通常のログイン要件をバイパス
  • 詳細なログを有効化
  • 設定変更を素早くテストするのに有用

--debug-log

システムの異なる部分のデバッグログ出力を制御します。

bash
potato start config.yaml --debug --debug-log=all

オプション：

値説明
allUI（フロントエンド）とサーバー（バックエンド）の両方のログを有効化
uiフロントエンドのJavaScriptコンソールログのみを有効化
serverバックエンドのPythonログのみを有効化
noneすべてのデバッグログを無効化

例：

bash
# Debug frontend issues (JavaScript errors, UI state)
potato start config.yaml --debug --debug-log=ui
 
# Debug backend issues (API calls, data processing)
potato start config.yaml --debug --debug-log=server
 
# Full debugging (both frontend and backend)
potato start config.yaml --debug --debug-log=all
 
# Quiet mode - minimal output
potato start config.yaml --debug --debug-log=none

--debug-phase

前のフェーズを経由せずに特定のフェーズまたはページに直接スキップします。アノテーションワークフローの特定の部分をテストするのに有用です。

bash
potato start config.yaml --debug --debug-phase=annotation

必須： --debugフラグも設定する必要があります。

有効なフェーズ名：

  • login - ログインページ
  • consent - 同意フォーム
  • prestudy - 事前調査
  • instructions - 指示ページ
  • training - トレーニングフェーズ
  • annotation - メインアノテーションフェーズ
  • poststudy - 事後調査
  • done - 完了ページ

例：

bash
# Jump directly to annotation (most common use case)
potato start config.yaml --debug --debug-phase=annotation
 
# Test post-study survey
potato start config.yaml --debug --debug-phase=poststudy
 
# Test a specific named page
potato start config.yaml --debug --debug-phase=my_custom_survey

仕組み：

  • debug_userという名前のユーザーを自動的に作成してログイン
  • 指定されたフェーズより前のすべてのフェーズをスキップ
  • ユーザーの状態はすべての前のフェーズを完了したかのように設定される

デバッグフラグの組み合わせ

フラグはさまざまなデバッグシナリオのために組み合わせることができます：

bash
# Quick annotation testing with minimal noise
potato start config.yaml --debug --debug-phase=annotation --debug-log=none
 
# Full debugging of annotation phase
potato start config.yaml --debug --debug-phase=annotation --debug-log=all
 
# Debug only backend while testing post-study
potato start config.yaml --debug --debug-phase=poststudy --debug-log=server

その他の便利なフラグ

--verbose / -v

一般的な操作ログの詳細出力を有効にします。

bash
potato start config.yaml -v

--veryVerbose

内部状態の詳細情報を含む非常に詳細な出力を有効にします。

bash
potato start config.yaml --veryVerbose

--port / -p

特定のポートで実行します（複数のインスタンスを実行する場合に有用）。

bash
potato start config.yaml -p 8080

ブラウザ開発者ツール

コマンドラインフラグに加えて、ブラウザ開発者ツールをデバッグに使用できます：

  1. コンソール：JavaScriptのログとエラーを表示（F12またはCmd+Option+I）
  2. ネットワーク：フロントエンドとバックエンド間のAPI呼び出しを監視
  3. 要素：DOMとCSSスタイリングを検査
  4. アプリケーション：セッションストレージとCookieを確認

コンソールログの再有効化

--debug-log=serverまたは--debug-log=noneでUIログが無効になった場合、ブラウザコンソールで再有効化できます：

javascript
enableUIDebug();

一般的なデバッグシナリオ

新しいアノテーションスキーマのテスト

bash
# Skip to annotation with full logging
potato start config.yaml --debug --debug-phase=annotation --debug-log=all

API問題のデバッグ

bash
# Server-only logging to focus on backend
potato start config.yaml --debug --debug-log=server

その後、ブラウザのネットワークタブでリクエスト/レスポンスデータを検査します。

ユーザーフローのテスト

bash
# Start from the beginning with UI logging
potato start config.yaml --debug --debug-log=ui

パフォーマンステスト

bash
# Minimal logging overhead
potato start config.yaml --debug --debug-phase=annotation --debug-log=none

トラブルシューティング

「debug-phaseには--debugフラグが必要です」

--debug-phaseオプションは--debugも指定されている場合にのみ動作します：

bash
# Wrong
potato start config.yaml --debug-phase=annotation
 
# Correct
potato start config.yaml --debug --debug-phase=annotation

フェーズが見つからない

指定されたフェーズが設定に存在しない場合、以下を確認してください：

  • フェーズ名のスペルが正しい
  • フェーズがYAML設定で定義されている
  • カスタムページの場合、設定の正確なページ名を使用している

関連情報

実装の詳細については、ソースドキュメントを参照してください。