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. 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.

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".

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.

{
    "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.

{
    "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:REGION:ACCOUNT_ID:key/KEY_ID",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "ACCOUNT_ID",
                    "aws:SourceArn": "arn:aws:rum:REGION:ACCOUNT_ID/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.

Ao desminificar uma linha no rastreamento da pilha, o CloudWatch RUM poderá falhar por vários motivos, entre eles: