PWA Kit アプリのデバッグ

バグとパフォーマンスのボトルネックは、Web アプリの開発で避けようのない部分です。PWA Kit では、アプリを詳細に検討するためのツールやテクニックを使用して、これらの問題の根本に迫ることができます。

このガイドのプレースホルダーを実際の値に置き換えてください。プレースホルダーは $PLACEHOLDER の形式になっています。

このガイドに記載されている特定の問題に焦点を絞ったアドバイスに従う前に、以下の一般的なトラブルシューティングの手順を試してみてください:

  • ローカル開発サーバーを起動する前に、サポートされているバージョンの Node を実行していることを再度確認します (入門ガイドを参照)。
  • 開発サーバーが現在実行されていることと、ポートが別のプロセスで使用されていないことを確認します。
  • コードの変更後、ブラウザーを再度読み込む前に、HTTP development server listening というメッセージがターミナルに表示されることを確認します。
  • ブラウザーコンソールとターミナルの両方でエラーを探します。
  • ブラウザーの開発ツールを使用して、ネットワークエラーレスポンスを探します。(Chrome のデベロッパーツールで Network (ネットワーク) タブを開きます。)
  • 構文エラーやミススペルを見つけるために、コードの formatter と linter を実行します。Retail React App では、Prettier (code formatter) と ESLint (linter) の両方に対して構成ファイルが提供されています。
  • コンピューターのアンチウィルスとファイアウォールの設定で、コードの実行を阻止しているものや、ネットワークリクエストをブロックしているものがないかを確認します。
  • パフォーマンスの問題を識別および分析するには、Chrome のデベロッパーツールで Profiler を使用します。詳細については、Google によるガイドの Analyze Runtime Performance (ランタイムパフォーマンス分析) を参照してください。また、Chrome 向けの React Developer Tools 拡張機能をインストールして、コンポーネントレベルで同様の情報を表示できる別の Profiler タブを取得できます。

コマースアプリによって処理される任意の URL に 2 つの特別なクエリパラメーターを追加して、サーバー側コードに関する問題をデバッグできます。

__server_only クエリパラメーターは、ページがサーバー側のレンダリング後とまったく同じようにブラウザーに表示されるように、ハイドレーション プロセスを停止します。サーバー側にレンダリングされるページのバージョンを見ることで、サーバー側のレンダリングの問題だけでなく、SEO に関する問題のトラブルシューティングも行うことができます。これは、検索エンジンはこのバージョンのページをクロールするためです。

__pretty_print クエリパラメーターは __PRELOADED_STATE__ オブジェクトに形式を追加し、読みやすくします。このオブジェクトは、ハイドレーションが始まる前に、アプリの状態にスナップショットを提供します。このため、予想する値が含まれているかを確認することでデバッグの助けとなります。オブジェクトのコンテンツを表示するには、アプリを読み込み、ページのソースを表示し、__PRELOADED_STATE__ を検索します。

__PRELOADED_STATE__ オブジェクトは、アプリがサーバー側で実行を開始する際に最初にリクエストされるページの HTML ソース内の <script> タグに含まれています。__PRELOADED_STATE__ オブジェクトは getProps 関数から返されたシリアル化された値を含みます (_app コンポーネントとページコンポーネントにアタッチされた getProps のバージョンを含む)。

デフォルトでは、アプリサーバーはターミナルにコンソールメッセージを表示しますが、それ以外はコードの実行を観察することはできません。この制限によって、サーバー側で (またはローカルマシンで) ページのレンダリングを行うコードのデバッグが難しくなります。

デバッグを向上させるために、デバッガーをアタッチできる Node でインスペクタープロセスを実行する代替コマンドを使用してローカル開発サーバーを起動できます。(詳細については、Node のドキュメントを参照してください。)

広く使用されている多くのブラウザーやテキストエディターに付属しているデバッガーを、Node のインスペクタープロセスにアタッチできます。以下に、Google Chrome と Visual Studio Code での手順を示します。

  1. ターミナルを開きます。
  2. プロジェクトディレクトリに移動します。
  3. npm run start:inspect を使用してローカル開発サーバーを起動します。
  4. デバッガーがリッスンしていることを確認するために、ターミナルの出力で “Debugger listening” (デバッガーがリッスン中) というメッセージを探します。
  5. Chrome を開き、URL に chrome://inspect と入力します。
  6. Open dedicated DevTools for Node (Node 専用 DevTools を開く) をクリックします。
  7. DevTools が新しいウィンドウに開きます。
  8. デバッガーがアタッチされていることを確認するために、ターミナルの出力で “Debugger attached” (デバッガーがアタッチ済み) というメッセージを探します。
  9. ブレークポイントの設定や、debugger ステートメントの追加などを行います。
  10. Chrome でローカル開発サーバーからページを読み込みます。
  11. デバッグには専用のウィンドウを使用します。

これでサーバー側コードの実行をトレースできます。

DevTools でのブレークポイントを使用したデバッグの詳細については、Google によるガイドの Debug JavaScript (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. Web ブラウザーでローカル開発サーバーからページを読み込みます。
  10. Visual Studio Code に統合されているデバッガーを使用してデバッグを行います。

これで Visual Studio Code でサーバー側コードの実行をトレースできます。

Node プロセスを繰り返しアタッチしなくてもいいようにするには、コマンドパレットを開いて、“Debug: Toggle Auto Attach” と入力します。設定を Always (常時) に切り替えて、Visual Studio Code ターミナルでローカル開発サーバーを再起動します。

Managed Runtime (MRT) にデプロイされたコードをデバッグするには、次の 3 つの方法があります。

  • ソースマップを使用して、エラーが発生した場所を特定します。
  • ログのテールを使用して、少量の環境でリアルタイムの問題やエラーをデバッグします。
  • Production (本番) 環境では、強力な検索と保持機能を提供する Log Center を使用します。

ソースマップを使用して、サーバー側またはクライアント側のエラーを特定します。ソースマップは、エラーが発生した場所を特定する単純なエラースタックトレースを提供します。たとえば、スタックトレースでは、エラーが発生したファイルと行番号が識別され、トラブルシューティングが容易になります。

ソースマップを有効にするとパフォーマンスに影響を与えるため、この機能は非本番環境でのみ使用することをお勧めします。

ソースマップを使用するには、PWA Kit バージョン 3.4.x 以降を使用してサイトを構築する必要があります。以前のバージョンを使用している場合は、PWA Kit 3.4.x を使用するようにプロジェクトをアップグレードします。

ソースマップを有効にするには、Runtime Admin を使用するか、Managed Runtime API を使用するかの 2 つの選択肢があります。

Runtime Admin を使用 する場合

  1. Runtime Admin にログインします。
  2. プロジェクトをクリックします。
  3. 環境をクリックします。
  4. Environment Settings (環境設定) をクリックします。
  5. Advanced (詳細) セクションで Edit (編集) をクリックします。
  6. Source Maps (ソースマップ) を有効にします。
  7. 詳細セクションの上部にある Update (更新) をクリックします。
  8. バンドルの再デプロイが完了するまで待ちます。

Managed Runtime API を使用 する場合

projects_target_partial_update API エンドポイントを呼び出し、enable_source_maps を true に設定します。これにより、環境内の NODE_OPTIONS Managed Runtime 環境変数が --enable-source-maps で構成され、バンドルが再デプロイされます。

  1. プロジェクトを作成するときは、ローカル環境変数 PWA_KIT_SSR_SOURCE_MAP=true を使用して ssr.js.map ファイルを生成します。
  1. Managed Runtime にバンドルをデプロイします。

ソースマップを有効化およびアップロードすると、Managed Runtime のログのテールを使用してソースマップを表示できます。

ソースマップを使用すると、パフォーマンスの問題が発生する可能性があります。たとえば、error.stack にアクセスするたびにレイテンシーが発生します。そのため、コードに console.error(e) を含めると、サイトの速度が低下する可能性があります。

  • 新しい非 Production (本番) 環境: enable_source_maps は true に設定されています。
  • 新しい Production (本番) 環境: enable_source_maps は false に設定されています。この動作は、ソースマップ機能が有効な場合に発生する可能性のあるパフォーマンスへの影響を回避するのに役立ちます。
  • すべての既存の環境: enable_source_maps は false に設定されています。

アプリが Managed Runtime にデプロイされる場合、リモートデバッグはサポートされません。ただし、Managed Runtime 環境のログをリアルタイムでテールして、サーバー側のエラーの診断に役立てることができます。

コマンドラインを用いてログをテールするには、以下の 2 つのオプションがあります。

バージョン 2.4.1 以降で生成された PWA Kit プロジェクト内で作業している場合、次のことができます。

  • ログコマンドのヘルプの表示: npm run tail-logs -- --help
  • 特定のプロジェクトおよび環境のログのテール: npm run tail-logs -- --environment $ENV_ID

上記コマンドでは追加の--が必須です。

PWA Kit プロジェクト外で作業している場合、またはバージョン 2.4.1 より前のバージョンで生成されたプロジェクトで作業する場合は、npxを使用して次のことができます。

  • ログコマンドのヘルプの表示: npx @salesforce/pwa-kit-dev tail-logs --help
  • 特定の環境 ID とプロジェクト ID のログのテール: npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

--environment および --project 引数の代わりに、より短い -e および -p 引数を使用することもできます。

ログをテールする場合は、次の点に注意してください。

  • 各ログテールセッションは 60 分後に終了します。
  • 各環境では、すべてのユーザーに対しアクティブなログテールセッションを一度に 100 セッションまでサポートできます。
  • ログをテールするには、Managed Runtime プロジェクトに対し、デベロッパーまたは管理者としてのユーザー許可を取得している必要があります。

PWA Kit を使用してサイトを構築した場合、または B2C Commerce インスタンスがある場合は、Log Center を使用してエラーのトラブルシューティングを行います。Log Center では:

  • 1 つの場所から Managed Runtime (MRT) のログと B2C Commerce インスタンスのログにアクセスできます。MRT 環境内で発生している内容を B2C Commerce インスタンス内で発生している内容と結び付けます。
  • 多くの履歴ログを検索およびフィルタリングできます。本番環境で発生した情報を取得し、問題をより迅速に調査して解決することができます。
  • Log Center の MRT ログは、Production (本番) 環境でのみ使用できます。前提条件を参照してください。
  • イベントが発生してからログが Log Center に表示されるまでに、最大 15 分間の遅延が生じることがあります。

このガイドでは、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. 環境を Production (本番) 環境としてマークします。Production (本番) 環境に関する詳細と制限事項を参照してください。

    b. 環境に接続する Commerce Cloud (B2C Commerce) インスタンスを選択します。

    c. 環境に関連付ける 1 つ以上のサイト ID を追加します。

前提条件を完了した後、Log Center で MRT ログを表示するには、次の手順を実行します。

  1. Log Center を開始します。
  2. 地域 を選択します。
  3. レルム を選択します。レルム ID がわからない場合は、アカウントエグゼクティブ (AE) または Customer Success Manager (CSM) までお問い合わせください。
  4. Show filtered results (フィルター結果を表示) をクリックします。
  5. Search (検索) > Current Search (現在の検索) の順にクリックします。
  6. 「Service Type」(サービスタイプ) で、mrt を選択します。
  7. 「Host」(ホスト) で、MRT ログを表示する本番環境を選択します。ホストの形式は $PROJECT.$ENVIRONMENT です。MRT 本番環境が複数ある場合は、複数の MRT ホスト名が表示されます。
  8. MRT ログを表示します。

Log Center のログレベルとログボリュームについては、管理者のための構成を参照してください。