# Habilitar a desminificação de rastreamentos de pilha de erros em JavaScript Quando o código-fonte JavaScript da sua aplicação Web é minificado, os rastreamentos de pilha de erros podem ser difíceis de ler. Você pode habilitar a desminificação dos rastreamentos de pilha fazendo o upload de seus mapas de origem para o Amazon S3. O CloudWatch RUM recuperará os mapas de origem para mapear os números de linha e coluna no código-fonte minificado e retorná-los ao código-fonte original não minificado. Isso melhorará a legibilidade dos rastreamentos de pilha de erros e ajudará a identificar a localização do erro no código-fonte original. ## Requisitos e sintaxe Os mapas de origem são cruciais para depurar e rastrear problemas em sua aplicação Web em diferentes versões. Certifique-se de que cada versão da aplicação Web tenha um mapa de origem único. Cada versão deve ter seu próprio releaseId exclusivo. Um releaseId precisa ser uma string com 1 a 200 caracteres e só pode conter letras, números, sublinhados, hifens, dois pontos, barras e pontos. Para adicionar o `releaseId` como metadados aos eventos do RUM, configure o cliente Web do CloudWatch RUM. Espera-se que os mapas de origem sejam arquivos JSON simples, seguindo a estrutura definida pela especificação [Source Map V3](https://sourcemaps.info/spec.html). Os campos obrigatórios são: `version`, `file`, `sources`, `names` e `mappings`. Certifique-se de que o tamanho de cada mapa de origem não exceda o limite de 50 MB. Além disso, o serviço RUM recuperará apenas até 50 MB de mapas de origem por rastreamento de pilha. Se necessário, divida o código-fonte em vários pedaços menores. Para obter mais informações, consulte [Code Splitting with WebpackJS](https://webpack.js.org/guides/code-splitting/). **Topics** + [Requisitos e sintaxe](#CloudWatch-RUM-RequirementsJavaScriptStackTraceSourceMaps) + [Configurar a política de recursos do bucket do Amazon S3 para permitir acesso ao serviço RUM](#CloudWatch-RUM-ConfigureS3) + [Fazer upload de mapas de origem](#CloudWatch-RUM-UploadSourceMaps) + [Configurar releaseId no cliente Web do CloudWatch RUM](#CloudWatch-RUM-ConfigureRumID) + [Habilitar o monitor de aplicação do CloudWatch RUM para desminificar os rastreamentos de pilha de JavaScript](#CloudWatch-RUM-unminifyjavascript) + [Visualizar rastreamentos de pilha desminificados no console do RUM](#CloudWatch-RUM-viewunminifiedstacktraces) + [Visualizar rastreamentos de pilha desminificados no CloudWatch Logs](#CloudWatch-RUM-viewunminifiedstacktracesCWL) + [Solucionar problemas de mapas de origem](#CloudWatch-RUM-troubleshootsourcemaps) ## Configurar a política de recursos do bucket do Amazon S3 para permitir acesso ao serviço RUM Certifique-se de que o bucket do Amazon S3 esteja na mesma região Do seu RUM appMonitor. Configure seu bucket do Amazon S3 para permitir o acesso ao serviço RUM a fim de recuperar arquivos de mapas de origem. Inclua as chaves de contexto de condição global `aws:SourceArn` e `aws:SourceAccount` para limitar as permissões do serviço ao recurso. Essa é a maneira mais eficiente de se proteger contra o [problema "confused deputy"](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). O exemplo a seguir mostra como é possível usar as chaves de contexto de condição global `aws:SourceArn` e `aws:SourceAccount` no Amazon S3, a fim de evitar o problema do substituto confuso. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RUM Service S3 Read Permissions", "Effect": "Allow", "Principal": { "Service": "rum.amazonaws.com" }, "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::{{BUCKET_NAME}}", "arn:aws:s3:::{{BUCKET_NAME}}/*" ], "Condition": { "StringEquals": { "aws:SourceAccount": "{{ACCOUNT_ID}}", "aws:SourceArn": "arn:aws:rum:{{REGION}}:{{ACCOUNT_ID}}:appmonitor/{{APP_MONITOR_NAME}}" } } } ] } ``` ------ Se você estiver usando chaves do AWS KMS para criptografar os dados, verifique se a política de recursos da chave está configurada de maneira semelhante para incluir as chaves de contexto de condição global `aws:SourceArn` e `aws:SourceAccount` a fim de dar acesso ao serviço RUM para usar as chaves para recuperar os arquivos do mapa de origem. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RUM Service KMS Read Permissions", "Effect": "Allow", "Principal": { "Service": "rum.amazonaws.com" }, "Action": "kms:Decrypt", "Resource": "arn:aws:kms:{{us-east-1}}:{{123456789012}}:key/{{KEY_ID}}", "Condition": { "StringEquals": { "aws:SourceAccount": "{{123456789012}}", "aws:SourceArn": "arn:aws:rum:{{us-east-1}}:{{123456789012}}/{{APP_MONITOR_NAME}}" } } } ] } ``` ------ ## Fazer upload de mapas de origem Configure seu pacote JavaScript para gerar mapas de origem durante a minificação. Quando você compilar sua aplicação, o pacote criará um diretório (p. ex., dist) contendo os arquivos JavaScript minificados e seus mapas de origem correspondentes. Veja um exemplo a seguir. ``` ./dist |-index.d5a07c87.js |-index.d5a07c87.js.map ``` Carregue os arquivos de mapa de origem em seu bucket no Amazon S3. Os arquivos devem estar localizados em uma pasta com o nome `releaseId`. Por exemplo, se o nome do meu bucket for `my-application-source-maps` e o `releaseId` for 2.0.0, o arquivo do mapa de origem estará localizado no seguinte local: ``` my-application-source-maps |-2.0.0 |-index.d5a07c87.js.map ``` Para automatizar o upload de seus mapas de origem, você pode criar o seguinte script bash e executá-lo como parte do seu processo de compilação. ``` #!/bin/bash # Ensure the script is called with required arguments if [ "$#" -ne 2 ]; then echo "Usage: $0 {{S3_BUCKET_NAME}} {{RELEASE_ID}}" exit 1 fi # Read arguments S3_BUCKET="$1" RELEASE_ID="$2" # Set the path to your build directory BUILD_DIR="./dist" # Upload all .map files recursively if aws s3 cp "$BUILD_DIR" "s3://$S3_BUCKET/$RELEASE_ID/" --recursive --exclude "*" --include "*.map"; then echo "Successfully uploaded all source map files" else echo "Failed to upload source map files" fi ``` ## Configurar releaseId no cliente Web do CloudWatch RUM O CloudWatch RUM usa o `releaseId` configurado para determinar a pasta na qual deve recuperar os arquivos de mapa de origem. Nomeie o `releaseId` da mesma forma que sua pasta de arquivos de mapa de origem. Se você tiver usado o script bash fornecido acima ou um similar, o `releaseId` configurado no script deverá ser o mesmo configurado no seu cliente Web do CloudWatch RUM. É necessário usar a versão 1.21.0 ou posterior do cliente Web do CloudWatch RUM. ``` import { AwsRum, AwsRumConfig } from "{{aws-rum-web}}"; try { const config: AwsRumConfig = { sessionSampleRate: 1, endpoint: "https://dataplane.rum.us-west-2.amazonaws.com", telemetries: ["performance", "errors", "http"], allowCookies: true, releaseId: "{{RELEASE_ID}}", //Add this }; const APPLICATION_ID: string = "{{APP_MONITOR_ID}}"; const APPLICATION_VERSION: string = "1.0.0"; const APPLICATION_REGION: string = "us-west-2"; new AwsRum(APPLICATION_ID, APPLICATION_VERSION, APPLICATION_REGION, config); } catch (error: any) { // Ignore errors thrown during CloudWatch RUM web client initialization } ``` ## Habilitar o monitor de aplicação do CloudWatch RUM para desminificar os rastreamentos de pilha de JavaScript Para desminificar os rastreamentos de pilha de JavaScript, defina o status de SourceMap do monitor de aplicação como `ENABLED`. Informe o URI do Amazon S3 para o bucket ou pasta que contém todos os mapas de origem para seu monitor de aplicação. Ao armazenar mapas de origem diretamente no bucket principal (não em uma subpasta), o URI do Amazon S3 deve ser formatado como `Amazon S3://{{BUCKET_NAME}}`. Nesse caso, os arquivos de mapa de origem deverão estar no seguinte local. ``` {{BUCKET_NAME}} |- {{RELEASE_ID}} |-index.d5a07c87.js.map ``` Quando um diretório secundário for a raiz, o URI do Amazon S3 deverá ser formatado como `Amazon S3://{{BUCKET_NAME}}/{{DIRECTORY}}`. Nesse caso, os arquivos de mapa de origem deverão estar no seguinte local. ``` {{BUCKET_NAME}} |- {{DIRECTORY}} |-{{RELEASE_ID}} |-index.d5a07c87.js.map ``` ## Visualizar rastreamentos de pilha desminificados no console do RUM Após carregar seus mapas de origem para o Amazon S3, habilitar os mapas de origem em seu monitor de aplicação do RUM e implantar sua aplicação Web com o `releaseId` configurado no cliente Web do CloudWatch RUM, selecione **Eventos** no console do RUM. Essa guia exibe os dados brutos do evento RUM. Filtre por tipo de evento de erro JS e visualize o evento de erro JS mais recente. Você verá o rastreamento de pilha desminificado no novo campo `event_details.unminifiedStack` para eventos ingeridos após a ativação do recurso. ## Visualizar rastreamentos de pilha desminificados no CloudWatch Logs Habilite o armazenamento de eventos do RUM no CloudWatch Logs ativando **Armazenamento de dados**. Após habilitá-lo, você poderá pesquisar o novo campo **event\_details.unminifiedStack**. Isso permite que você analise tendências e relacione problemas em várias sessões usando consultas do CloudWatch Logs. ## Solucionar problemas de mapas de origem O CloudWatch RUM fornece métricas prontas para uso para solucionar problemas na configuração do mapa de origem. Essas métricas estão publicadas no namespace da métrica chamado `AWS/RUM`. Todas as métricas a seguir são publicadas com uma dimensão application\_name. O valor dessa dimensão é o nome do monitor de aplicações. As métricas a seguir também são publicadas com uma dimensão `aws:releaseId`. O valor dessa dimensão é o `releaseId` associado ao evento de erro de JavaScript. | MetricName | Unidade | Descrição | | --- | --- | --- | | UnminifyLineFailureCount | Contagem | A contagem de linhas de rastreamento de pilha no evento de erro JS que falharam ao serem desminificadas. Detalhes adicionais sobre a falha serão adicionados à linha específica que falhou no campo event\_details.unminifiedStack. | | UnminifyLineSuccessCount | Contagem | A contagem de linhas de rastreamento de pilha no evento de erro JS que foram desminificadas com sucesso. | | UnminifyEventFailureCount | Contagem | A contagem de eventos de erro de JS que falharam em ter qualquer linha desminificada. Detalhes adicionais sobre a falha serão adicionados ao campo event\_details.unminifiedStack. | | UnminifyEventSuccessCount | Contagem | A contagem de eventos de erro de JS que conseguiram ter pelo menos uma linha de rastreamento de pilha desminificada. | Ao desminificar uma linha no rastreamento da pilha, o CloudWatch RUM poderá falhar por vários motivos, entre eles: + Falha ao recuperar o arquivo de mapa de origem correspondente devido a problemas de permissão. Certifique-se de que a política de recursos do bucket esteja configurada corretamente. + O arquivo de mapa de origem correspondente não existe. Certifique-se de que os arquivos do mapa de origem tenham sido enviados para o bucket ou para a pasta certa com o mesmo nome do releaseId configurado em seu cliente Web do CloudWatch RUM. + O arquivo de mapa de origem correspondente é muito grande. Divida seu código-fonte em partes menores. + Já há 50 MB de arquivos de mapa de origem recuperados para o rastreamento da pilha. Reduza o tamanho do rastreamento da pilha, pois 50 MB é uma limitação no lado do serviço. + O mapa de origem é inválido e não pôde ser indexado. Certifique-se de que o mapa de origem seja um JSON simples, seguindo a estrutura definida pela especificação Source Map V3 e inclua os seguintes campos: version, file, sources, names, mappings. + O mapa de origem não conseguiu mapear o código-fonte minificado de volta para o rastreamento de pilha não minificado. Certifique-se de que o mapa de origem seja o mapa de origem correto para o releaseId fornecido.