Skip to content

디버깅 가이드

Potato 주석 프로젝트를 디버깅합니다 — 상세 로깅을 활성화하고, 디버그 플래그를 사용하며, 일반적인 오류 메시지를 해석하고, 데이터 로딩 및 스키마 검증 문제를 해결합니다.

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)

참고: 명령줄 플래그는 구성 파일 값보다 우선합니다. 예를 들어 -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. 애플리케이션: 세션 저장소와 쿠키를 확인합니다

콘솔 로깅 다시 활성화

--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 requires --debug flag"

--debug-phase 옵션은 --debug도 함께 지정된 경우에만 작동합니다:

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

단계를 찾을 수 없음

지정된 단계가 구성에 존재하지 않는 경우 다음을 확인하세요:

  • 단계 이름의 철자가 올바른지
  • 단계가 YAML 구성에 정의되어 있는지
  • 사용자 정의 페이지의 경우 구성에 있는 정확한 페이지 이름을 사용하세요

추가 자료

구현 세부 정보는 원본 문서를 참조하세요.