Depurar aplicativos do PWA Kit

Bugs e gargalos de desempenho são uma parte inevitável do desenvolvimento de aplicativos da web. Com o PWA Kit, é possível chegar à raiz desses problemas com uma variedade de ferramentas e técnicas que fazem uma análise detalhada de seu app.

Substitua os espaços reservados neste guia por valores reais. Os espaços reservados são formatados da seguinte maneira: $PLACEHOLDER.

Antes de seguir a orientação mais precisa deste guia, tente estas etapas gerais de solução de problemas antes:

• Verifique se você está executando uma versão compatível do Node (consulte o guia Como começar) antes de iniciar seu servidor de desenvolvimento local.
• Confirme que seu servidor de desenvolvimento ainda está em execução e que a porta não foi controlada por outro processo.
• Depois de uma mudança de código, confirme que a mensagem HTTP development server listening aparece no terminal antes de recarregar o navegador.
• Procure erros tanto no console do navegador quanto no terminal.
• Procure respostas a erros de rede usando as ferramentas de desenvolvedor do seu navegador. (No Chrome, em Ferramentas do desenvolvedor, vá para a guia Network.)
• Para ajudar a identificar erros de sintaxe e de ortografia, execute um formatador de código e um linter. Os arquivos de configuração são fornecidos tanto para o Prettier (formatador de código) quanto para o ESLint (linter) no Retail React App.
• Verifique as configurações do antivírus e do firewall de seu computador em busca de algo que esteja impedindo que o código seja executado ou que esteja bloqueando as solicitações de rede.
• Para identificar e analisar problemas de análise e desempenho, use o Profiler do DevTools do Chrome. Para obter mais informações, consulte este guia do Google: Analyze Runtime Performance (Analisar o desempenho do tempo de execução). Você também pode instalar a extensão React Developer Tools para Chrome para obter outra guia Profiler, onde você pode ver informações similares no nível do componente.

Há dois parâmetros de consulta especiais que podem ser adicionados a qualquer URL usado por seu app de comércio eletrônico para ajudar a depurar problemas com códigos no lado do servidor.

O parâmetro de consulta __server_only interrompe o processo de hidratação para que a página apareça em seu navegador exatamente como apareceria depois da renderização do lado do servidor. Ver a versão renderizada da página no lado do servidor ajuda a solucionar problemas não somente com a renderização no lado do servidor, como também com o SEO, já que os mecanismos de busca rastreiam essa versão da página.

O parâmetro de consulta __pretty_print adiciona formatação ao objeto__PRELOADED_STATE__, para facilitar sua leitura. Esse objeto proporciona um snapshot do estado de seu app antes do início da hidratação, então seria útil depurar para ver se contém os valores esperados. Para ver o conteúdo do objeto, carregue seu app, consulte a origem da página e procure __PRELOADED_STATE__.

O objeto __PRELOADED_STATE__ está incluído em um tag <script> na fonte HTML da página que foi inicialmente solicitada quando seu app começou a executar no lado do servidor. O objeto __PRELOADED_STATE__ contém valores em série retornados pela função getProps (incluindo as versões getProps que estão anexadas ao componente _app e ao componente da página).

Por padrão, o servidor de apps exibe mensagens do console no terminal, mas não permite que você veja o código de execução. Esta limitação pode dificultar a depuração do código que renderiza páginas no lado do servidor (ou em sua máquina local).

Para uma melhor depuração, você pode iniciar seu servidor de desenvolvimento local com um comando alternativo que executa um processo de inspeção em Node que pode ser anexado a um depurador. (Para obter mais detalhes, consulte a documentação sobre o Node.)

Você pode anexar o depurador incluído em vários navegadores populares e editores de texto ao processo de inspeção do Node. Aqui estão as instruções para o Google Chrome e o Visual Studio Code.

1. Abra um terminal.
2. Vá para o diretório de seu projeto.
3. Inicie o servidor de desenvolvimento local usando npm run start:inspect.
4. Para confirmar que o depurador está na escuta, procure a mensagem “Debugger Listening” (Depurador na escuta) na saída do terminal.
5. Abra o Chrome e insira o URL chrome://inspect.
6. Clique em Open dedicated DevTools for Node (Abrir DevTools para Node dedicados).
7. O DevTools se abre em uma nova janela.
8. Para confirmar que o depurador está anexado, procure a mensagem “Debugger Attached” (Depurador anexado) na saída do terminal.
9. Defina pontos de interrupção, adicione declarações do debugger e assim por diante.
10. Carregue uma página do servidor de desenvolvimento local no Chrome.
11. Use a janela dedicada para depuração.

Agora você pode rastrear a execução do seu código no lado do servidor!

Para saber mais sobre como depurar usando pontos de interrupção no DevTools, veja este guia do Google: Debug JavaScript.

1. Abra os arquivos do seu projeto no Visual Studio Code.
2. Na barra de menu, clique em Terminal > New Terminal (Novo terminal).
3. Inicie o servidor de desenvolvimento local usando npm run start:inspect.
4. Abra a Command Palette. Atalho para Windows: Ctrl + Shift + P. Atalho para Mac: Command + Shift + P.
5. Digite o seguinte comando: “Debug: Attach to Node Process” (Depuração: anexar ao processo do Node).
6. Aparecerá uma lista dos processos do Node. Escolha o primeiro da lista.
7. Para confirmar que o depurador está anexado, procure a mensagem “Debugger Attached” na saída do terminal.
8. Defina pontos de interrupção, adicione declarações do depurador e assim por diante.
9. Carregue uma página do servidor de desenvolvimento local no navegador da web.
10. Use o depurador integrado do Visual Studio Code para depuração.

Agora você pode rastrear a execução do seu código no lado do servidor no Visual Studio Code!

Há três maneiras de depurar o código implantado no Managed Runtime (MRT):

• Use mapas de origem para identificar onde ocorreram erros.
• Tail logs (monitoramento de logs em tempo real) para depurar problemas ou erros em tempo real em um ambiente de baixo volume.
• Para um ambiente de produção, use Log Center, que oferece recursos avançados de pesquisa e retenção.

Use mapas de origem para identificar erros no lado do servidor ou no lado do cliente. Os mapas de origem fornecem um rastreamento simples da pilha de erros que identifica onde ocorreu um erro. Por exemplo, o rastreamento de pilha identifica o arquivo e o número da linha em que o erro ocorreu para facilitar a solução de problemas.

Para usar mapas de origem, você deve criar seu site usando PWA Kit versão 3.4.x ou posterior. Se você tiver uma versão anterior, atualize seu projeto para usar o PWA Kit 3.4.x.

Você tem duas opções para habilitar mapas de origem: usar o Runtime Admin ou usar a Managed Runtime API.

Usar o Runtime Admin

1. Faça logon no Runtime Admin.
2. Clique em seu projeto.
3. Clique em um ambiente.
4. Clique em Environment Settings (Configurações do ambiente).
5. Na seção Advanced (Avançado), clique em Edit (Editar).
6. Habilite Source Maps (mapas de origem).
7. Na parte superior da seção Advanced (Avançado), clique em Update (Atualizar).
8. Espere terminar a reimplantação do pacote.

Usar a Managed Runtime API

Chame o endpoint da projects_target_partial_update API e defina enable_source_maps como true. Isso configura a variável de ambiente NODE_OPTIONS do Managed Runtime em seu ambiente com --enable-source-maps e reimplanta o pacote.

1. Ao criar seu projeto, gere o arquivo ssr.js.map usando esta variável de ambiente local: PWA_KIT_SSR_SOURCE_MAP=true.

2. Implante seu pacote no Managed Runtime.

Depois de habilitar e fazer o upload de mapas de origem, você pode visualizá-los usando o monitoramento de logs em tempo real (Tail Logs) no Managed Runtime.

O uso de mapas de origem pode causar problemas de desempenho. Por exemplo, há latência sempre que error.stack é acessado. Portanto, quando você inclui console.error(e) em seu código, isso pode tornar seu site mais lento.

• Novos ambientes de não produção: enable_source_maps está definido como true.
• Novos ambientes de produção: enable_source_maps está definido como false. Esse comportamento ajuda a evitar possíveis impactos no desempenho que podem surgir quando o recurso de mapas de origem está habilitado.
• Todos os ambientes pré-existentes: enable_source_maps está definido como false.

Quando seu aplicativo é implantado no Managed Runtime, a depuração remota não é aceita. No entanto, você pode fazer o monitoramento de logs em tempo real (tail logs) de qualquer ambiente do Managed Runtime para ajudar a diagnosticar erros do lado do servidor.

Você tem duas opções para fazer o monitoramento de logs em tempo real por meio da linha de comando.

Se você está trabalhando em um projeto do PWA Kit gerado com a versão 2.4.1 ou mais recente, é possível:

• Obter ajuda para o comando de logs: npm run tail-logs -- --help
• Monitoramento de logs em tempo real de um ambiente e projeto específico: npm run tail-logs -- --environment $ENV_ID

Se você está trabalhando em um projeto que não seja do PWA Kit ou em um projeto gerado com uma versão mais antiga do que a 2.4.1, é possível usar npx para:

• Obter ajuda para o comando de logs: npx @salesforce/pwa-kit-dev tail-logs --help
• Monitoramento de logs em tempo real de IDs de projeto e de ambiente específicos: npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

Ao acompanhar logs, lembre-se das seguintes limitações:

• Cada sessão de acompanhamento de log termina após 60 minutos.
• Cada ambiente é compatível com até 100 sessões ativas de acompanhamento de log por vez, abrangendo todos os usuários.
• Para fazer o monitoramento de logs em tempo real, você precisa receber permissões de usuário administrador ou desenvolvedor para o projeto do Managed Runtime.

Use Log Center para solucionar erros se você criou um site usando o PWA Kit ou se tiver uma instância do B2C Commerce. Log Center:

• Fornece um único local para acessar logs do Managed Runtime (MRT) e sua instância do B2C Commerce. Conecte o que está acontecendo em seu ambiente MRT com o que está acontecendo em sua instância do B2C Commerce.
• Permite pesquisar e filtrar muitos logs históricos. Você pode obter mais informações sobre o que aconteceu na produção, para ajudar a investigar e resolver problemas mais rapidamente.

Este guia se concentra na depuração de sites criados usando o PWA Kit. Para obter informações sobre como usar o Log Center com sua instância do B2C Commerce, consulte Log Center centralizado.

Para acessar os logs MRT de um ambiente no Log Center, você deve primeiro:

1. Ter a função de Usuário de Log Center no Account Manager. Para verificar, verifique sua função no Account Manager. Se você não tiver a função, peça ao administrador do Account Manager para lhe dar acesso. Consulte Gerenciar o Account Manager para usuários do Salesforce B2C Commerce.

2. Configure o ambiente da seguinte maneira:

   a. Marque o ambiente como um ambiente de produção. Veja detalhes e limitações relacionados aos ambientes de produção.

   b. Selecione uma instância do Commerce Cloud (B2C Commerce) para se conectar ao ambiente.

   c. Adicione um ou mais IDs de site para associar ao ambiente.

Após concluir os pré-requisitos, visualize os logs do MRT no Log Center:

1. Inicie o Log Center.
2. Selecione uma Region (Região).
3. Selecione um Realm. Se você não conhece o ID do seu realm, solicite-o a seu Executivo de contas ou ao Customer Success Manager (CSM).
4. Clique em Show filtered results (Mostrar resultados filtrados).
5. Clique em Search > Current Search (Pesquisar > Pesquisa atual).
6. Em Service Type (Tipo de Serviço), selecione mrt.
7. Em Host, selecione o ambiente de produção cujos logs MRT você deseja ver. O formato do host é $PROJECT.$ENVIRONMENT. Se você tiver mais de um ambiente de produção MRT, poderá ver vários nomes de host MRT.
8. Visualize os logs do MRT.

Para obter informações sobre níveis de log e volumes de log no Log Center, consulte Configuração para administradores.