PWA Kit 앱 디버깅

버그와 성능 병목 현상은 웹 앱 개발에서 피할 수 없는 문제입니다. PWA Kit를 사용하면 앱을 면밀히 검사하는 다양한 도구와 기술로 이러한 문제의 근본 원인을 파악할 수 있습니다.

이 가이드의 모든 Placeholder를 실제 값으로 바꾸십시오. 자리 표시자는 $PLACEHOLDER와 같은 형식입니다.

이 가이드의 보다 구체적인 조언을 따르기 전에 다음과 같은 일반적인 문제 해결 단계를 먼저 시도해보십시오.

• 로컬 개발 서버를 시작하기 전에 지원되는 버전의 Node를 실행 중인지 다시 확인합니다(시작하기 가이드 참조).
• 개발 서버가 아직 실행 중이며, 다른 프로세스가 포트를 점유하고 있지 않은지 확인합니다.
• 코드를 변경한 후 브라우저를 다시 로드하기 전에 터미널에 HTTP development server listening 메시지가 표시되는지 확인합니다.
• 브라우저 콘솔과 터미널 모두에서 오류를 찾습니다.
• 브라우저의 개발자 도구를 사용하여 네트워크 오류 응답을 찾습니다. (Chrome의 DevTools에서 Network(네트워크) 탭으로 이동합니다.)
• 구문 오류 및 오타를 쉽게 찾을 수 있도록 코드 포맷터와 린터를 실행합니다. 구성 파일은 Retail React App에서 Prettier(코드 포맷터)와 ESLint(린터) 모두에 제공됩니다.
• 컴퓨터의 바이러스 백신 및 방화벽 설정에서 코드 실행을 방해하거나 네트워크 요청을 차단하는 항목이 있는지 확인합니다.
• 성능 문제를 찾고 분석하려면 Chrome의 DevTools에서 프로파일러를 사용합니다. 자세한 내용은 Google의 다음 가이드를 참조하십시오. Analyze Runtime Performance(런타임 성능 분석). 또한 Chrome용 React 개발자 도구 확장을 설치하여 구성 요소 수준에서 유사한 정보를 볼 수 있는 다른 프로파일러 탭을 표시할 수 있습니다.

커머스 앱이 지원하는 URL에 추가하여 서버 측 코드의 문제를 디버깅하는 데 사용할 수 있는 두 가지 특수한 쿼리 매개변수가 있습니다.

__server_only 쿼리 매개변수는 hydration 프로세스를 중지하여 페이지가 서버 측 렌더링 후에 표시되는 것과 동일하게 브라우저에 표시되도록 합니다. 검색 엔진은 이 버전의 페이지를 크롤링하므로, 서버의 렌더링된 페이지 버전을 보면 서버 측 렌더링 문제뿐만 아니라 SEO 문제까지 해결하는 데 도움이 됩니다.

__pretty_print 쿼리 매개변수는 읽기 쉽도록 __PRELOADED_STATE__ 오브젝트에 서식을 추가합니다. 이 오브젝트는 hydration이 시작되기 전에 앱의 상태에 대한 스냅샷을 제공하므로 올바른 값이 포함되어 있는지 확인할 수 있어 디버깅에 도움이 됩니다. 오브젝트의 컨텐츠를 보려면 앱을 로드하고 페이지의 소스를 확인하고 __PRELOADED_STATE__를 검색합니다.

__PRELOADED_STATE__ 오브젝트는 앱이 서버 측에서 실행될 때 처음에 요청했던 페이지의 HTML 소스 내에 있는 <script> 태그에 포함되어 있습니다. __PRELOADED_STATE__ 오브젝트에는 getProps 함수에서 반환되는 직렬화된 값(_app 구성요소 및 페이지 구성요소에 연결된 getProps 버전 포함)이 포함되어 있습니다.

기본적으로 앱 서버는 터미널에 콘솔 메시지를 표시하지만, 다른 경우에는 사용자가 코드 실행을 볼 수 없습니다. 이러한 제한으로 인해 서버 측(또는 로컬 머신)에서 페이지를 렌더링하는 코드를 디버깅하기가 어려울 수 있습니다.

디버깅을 개선하기 위해, 디버거가 연결할 수 있는 노드에서 검사기 프로세스를 실행하는 대체 명령을 사용하여 로컬 개발 서버를 시작할 수 있습니다. (자세한 내용은 Node 설명서를 참조하십시오.)

많이 사용되는 여러 가지 브라우저 및 텍스트 편집기에 포함된 디버거를 노드의 검사기 프로세스에 연결할 수 있습니다. 다음은 Google Chrome 및 Visual Studio Code에 대한 지침입니다.

1. 터미널을 엽니다.
2. 프로젝트 디렉터리로 이동합니다.
3. npm run start:inspect를 사용하여 로컬 개발 서버를 시작합니다.
4. 디버거가 수신 중인지 확인하려면 터미널 출력에서 "Debugger listening(디버거 수신 중)" 메시지를 찾습니다.
5. Chrome을 열고 chrome://inspect라는 URL을 입력합니다.
6. Open Dedicated Devtools For Node(Node의 전용 DevTools 열기)를 클릭합니다.
7. 새 창에서 DevTools가 열립니다.
8. 디버거가 연결되었는지 확인하려면 터미널 출력에서 "Debugger Attached(디버거 연결됨)" 메시지를 찾습니다.
9. 중단점을 설정하고 debugger 문을 추가하는 등의 작업을 수행합니다.
10. Chrome의 로컬 개발 서버에서 페이지를 로드합니다.
11. 디버깅 전용 창을 사용합니다.

이제 서버 측 코드의 실행을 추적할 수 있습니다.

DevTools의 중단점을 이용한 디버깅에 대한 자세한 내용은 Google의 다음 가이드를 참조하십시오. JavaScript 디버깅.

1. Visual Studio Code에서 프로젝트 파일을 엽니다.
2. 메뉴 모음에서 Terminal(터미널) > New Terminal(새 터미널)을 클릭합니다.
3. npm run start:inspect를 사용하여 로컬 개발 서버를 시작합니다.
4. 명령 팔레트를 엽니다. Windows의 바로가기: Ctrl + Shift + P. Mac의 바로가기: Command + Shift + P.
5. 다음 명령을 입력합니다. “Debug: Attach to Node Process.”
6. Node 프로세스의 목록이 표시됩니다. 목록의 첫 번째 항목을 선택합니다.
7. 디버거가 연결되었는지 확인하려면 터미널 출력에서 "Debugger Attached(디버거 연결됨)" 메시지를 찾습니다.
8. 중단점을 설정하고 디버거 문을 추가하는 등의 작업을 수행합니다.
9. 웹 브라우저에서 로컬 개발 서버의 페이지를 로드합니다.
10. Visual Studio Code의 통합 디버거를 디버깅에 사용합니다.

이제 Visual Studio Code에서 서버 측 코드의 실행을 추적할 수 있습니다.

MRT(Managed Runtime)에 배포된 코드를 디버깅하는 방법은 세 가지가 있습니다.

• 소스 맵을 사용하여 오류가 발생한 위치를 정확히 찾아냅니다.
• 비상 로그를 사용하여 저용량 환경에서 실시간으로 문제 또는 오류를 디버깅합니다.
• 프로덕션 환경의 경우 강력한 검색 및 보존 기능을 제공하는 Log Center를 사용합니다.

소스 맵을 사용하여 서버 측 또는 클라이언트 측 오류를 식별합니다. 소스 맵은 오류가 발생한 위치를 정확히 찾아내는 간단한 오류 스택 추적을 제공합니다. 예를 들어 스택 추적은 오류가 발생한 파일 및 줄 번호를 식별하여 더 쉽게 문제를 해결할 수 있도록 해줍니다.

소스 맵을 사용하려면 PWA Kit 버전 3.4.x 이상을 사용하여 사이트를 빌드해야 합니다. 이전 버전이 있는 경우 PWA Kit 3.4.x를 사용하도록 프로젝트를 업그레이드하십시오.

소스 맵을 사용하도록 설정하는 방법은 Runtime Admin을 사용하거나 Managed Runtime API를 사용하는 두 가지가 있습니다.

Runtime Admin 사용

1. Runtime Admin에 로그인합니다.
2. 프로젝트를 클릭합니다.
3. 환경을 클릭합니다.
4. 환경 설정을 클릭합니다.
5. Advanced(고급) 섹션에서 Edit(편집)를 클릭합니다.
6. 소스 맵을 활성화합니다.
7. 고급 섹션 상단에서 업데이트를 클릭합니다.
8. 번들 재배포가 완료될 때까지 기다립니다.

Managed Runtime API 사용

projects_target_partial_updateAPI 엔드포인트를 호출하고 enable_source_maps를 true로 설정합니다. 그러면 사용자 환경에서 --enable-source-maps Managed Runtime 환경 변수가 NODE_OPTIONS로 구성되고 번들이 다시 배포됩니다.

1. 프로젝트를 빌드할 때 로컬 환경 변수 PWA_KIT_SSR_SOURCE_MAP=true를 사용하여 ssr.js.map 파일을 생성합니다.

2. Managed Runtime에 번들을 배포합니다.

소스 맵을 활성화하고 업로드한 후에는 Managed Runtime에서 비상 로그를 사용하여 볼 수 있습니다.

소스 맵을 사용하면 성능 문제가 발생할 수 있습니다. 예를 들어 error.stack에 액세스할 때마다 지연 시간이 발생합니다. 따라서 코드에 console.error(e)를 포함하면 사이트 속도가 느려질 수 있습니다.

• 새 비프로덕션 환경: enable_source_maps가 true로 설정되어 있습니다.
• 새 프로덕션 환경: enable_source_maps가 false로 설정되어 있습니다. 이 동작은 소스 맵 기능을 활성화할 때 발생할 수 있는 잠재적인 성능 영향을 방지하는 데 도움이 됩니다.
• **모든 기존 환경: **enable_source_maps가 false로 설정되어 있습니다.

앱이 Managed Runtime에 배포되면 원격 디버깅이 지원되지 않습니다. 단, Managed Runtime 환경의 로그를 실시간으로 추적하여 서버 측 오류를 진단할 수 있습니다.

명령줄을 통해 로그를 추적하는 두 가지 옵션이 있습니다.

버전 2.4.1 이상에서 생성된 PWA Kit 프로젝트 내에서 작업하는 경우 다음과 같이 할 수 있습니다.

• logs 명령에 대한 도움말 보기: npm run tail-logs -- --help
• 특정 프로젝트 및 환경에 대한 로그 추적: npm run tail-logs -- --environment $ENV_ID

PWA Kit 프로젝트 외부에서 작업하거나 버전 2.4.1 이하에서 생성된 프로젝트가 있는 경우, npx를 사용하여 다음과 같이 할 수 있습니다.

• logs 명령에 대한 도움말 보기: npx @salesforce/pwa-kit-dev tail-logs --help
• 특정 환경 ID 및 프로젝트 ID에 대한 로그 추적: npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

로그를 추적할 때는 다음 제약 조건을 염두에 두십시오.

• 각 로그 추적 세션은 60분 후에 종료됩니다.
• 각 환경에서는 모든 사용자에 걸쳐 한 번에 최대 100개의 활성 로그 추적 세션을 지원할 수 있습니다.
• 로그를 추적하려면 Managed Runtime 프로젝트에 대한 개발자 권한 또는 관리자 권한이 필요합니다.

PWA Kit를 사용하여 사이트를 구축했거나 B2C Commerce 인스턴스가 있는 경우 Log Center를 사용하여 오류를 해결합니다. Log Center:

• MRT(Managed Runtime) 및 B2C Commerce 인스턴스의 로그에 액세스할 수 있는 단일 위치를 제공합니다. MRT 환경에서 발생하는 상황과 B2C Commerce 인스턴스에서 발생하는 상황의 연관성을 분석합니다.
• 많은 수의 기록 로그를 검색하고 필터링할 수 있습니다. 문제를 더 빨리 조사하고 해결하는 데 도움이 되도록 프로덕션 환경에서 발생한 문제에 대한 자세한 정보를 얻을 수 있습니다.

이 가이드에서는 PWA Kit를 사용하여 빌드된 사이트의 디버깅에 중점을 둡니다. B2C Commerce 인스턴스에서 Log Center를 사용하는 방법에 대한 자세한 내용은 중앙 집중식 Log Center를 참조하십시오.

Log Center의 환경에 대한 MRT 로그에 액세스하려면 먼저 다음 조건을 충족해야 합니다.

1. Account Manager에 Log Center 사용자 역할이 있어야 합니다. 이를 확인하려면 Account Manager에서 자신의 역할을 확인하십시오. 이 역할이 없는 경우 Account Manager 관리자에게 액세스 권한을 부여해 달라고 요청하십시오. Salesforce B2C Commerce 사용자의 Account Manager 관리를 참조하십시오.

2. 다음과 같이 환경을 설정합니다.

   a. 환경을 프로덕션 환경으로 표시합니다. 프로덕션 환경과 관련한 세부 정보 및 제한 사항을 참조하십시오.

   b. 환경에 연결할 Commerce Cloud(B2C Commerce) 인스턴스를 선택합니다.

   c. 환경에 연결할 사이트 ID를 하나 이상 추가합니다.

사전 요구 사항을 완료한 후 Log Center에서 MRT 로그를 보려면 다음을 수행합니다.

1. Log Center를 시작합니다.
2. 지역을 선택합니다.
3. **realm**을 선택합니다. realm ID를 모르면 Account Executive(AE) 또는 Customer Success Manager(CSM)에게 문의하십시오.
4. 필터링된 결과 표시를 클릭합니다.
5. 검색 > 현재 검색을 클릭합니다.
6. 서비스 유형에서 mrt를 선택합니다.
7. 호스트에서 MRT 로그를 보려는 프로덕션 환경을 선택합니다. 호스트의 형식은 $PROJECT.$ENVIRONMENT입니다. MRT 프로덕션 환경이 둘 이상 있는 경우 여러 MRT 호스트 이름이 표시될 수 있습니다.
8. MRT 로그를 봅니다.

Log Center의 로그 수준 및 로그 볼륨에 대한 자세한 내용은 관리자를 위한 구성을 참조하십시오.