Abilitare l'unificazione delle tracce dello stack di errori JavaScript

Quando il codice JavaScript sorgente dell'applicazione web viene minimizzato, le tracce dello stack di errori possono essere difficili da leggere. Puoi abilitare l'unificazione delle tracce dello stack caricando le mappe di origine su Amazon S3. CloudWatch RUM recupererà le mappe sorgente per mappare i numeri di riga e colonna del codice sorgente minimizzato al codice sorgente non minimizzato originale. Ciò migliorerà la leggibilità delle tracce di stack degli errori e aiuterà a identificare la posizione dell'errore nel codice sorgente originale.

Requisiti e sintassi

Le mappe di origine sono fondamentali per il debug e il monitoraggio dei problemi nelle applicazioni web nelle diverse versioni. Assicurati che ogni versione dell'applicazione web abbia una mappa di origine unica. Ogni versione deve avere il proprio ReleaseID univoco. Un ReleaseID deve essere una stringa di lunghezza compresa tra 1 e 200 caratteri e può contenere solo lettere, numeri, caratteri di sottolineatura, trattini, due punti, barre oblique e punti. Per aggiungere i metadati releaseId as agli eventi RUM, configura il client web RUM. CloudWatch

Le mappe di origine dovrebbero essere semplici file JSON che seguono la struttura definita dalla specifica Source Map V3. I campi obbligatori sono: version, file, sources, names e mappings.

Assicurati che la dimensione di ogni mappa di origine non superi il limite di 50 MB. Inoltre, il servizio RUM recupererà solo fino a 50 MB di mappe di origine per ciascuna traccia di stack. Se necessario, suddividi il codice sorgente in più blocchi più piccoli. Per ulteriori informazioni, consulta Suddivisione del codice con WebpackJS.

Configurazione della policy delle risorse del bucket Amazon S3 per consentire l'accesso al servizio RUM

Assicurati che il bucket Amazon S3 si trovi nella stessa regione del tuo RUM AppMonitor. Configura il tuo bucket Amazon S3 per consentire l'accesso al servizio RUM per il recupero dei file delle mappe di origine. Includi le chiavi di contesto delle condizioni globali aws:SourceArn e aws:SourceAccount per limitare le autorizzazioni del servizio alla risorsa. Questo è il modo più efficace per proteggersi dal problema di deputy confused.

L'esempio seguente mostra il modo in cui puoi utilizzare le chiavi di contesto delle condizioni globali aws:SourceArn e aws:SourceAccount in Amazon S3 per prevenire il problema del confused deputy.

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 utilizzate AWS KMS le chiavi per crittografare i dati, assicuratevi che la politica delle risorse della chiave sia configurata in modo simile per includere le aws:SourceArn chiavi di contesto della condizione aws:SourceAccount globale per consentire al servizio RUM di utilizzare le chiavi per recuperare i file di mappa di origine.

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"
                }
            }
        }
    ]
}

Caricamento delle mappe di origine

Configura il tuo JavaScript pacchetto per generare mappe di origine durante la minimizzazione. Quando crei l'applicazione, il pacchetto creerà una directory (ad esempio, dist) contenente JavaScript i file minimizzati e le mappe di origine corrispondenti. Un esempio è fornito di seguito.

./dist
    |-index.d5a07c87.js
    |-index.d5a07c87.js.map

Carica i file delle mappe di origine nel tuo bucket Amazon S3. I file dovrebbero trovarsi in una cartella con il releaseId come nome. Ad esempio, se il nome del mio bucket è my-application-source-maps e il releaseId è 2.0.0, il file della mappa di origine si trova nella seguente posizione:

my-application-source-maps
    |-2.0.0
        |-index.d5a07c87.js.map

Per automatizzare il caricamento delle mappe di origine, puoi creare il seguente script bash ed eseguirlo come parte del processo di compilazione.

#!/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

Configura ReleaseID nel tuo CloudWatch client web RUM

CloudWatch RUM utilizza il file configurato releaseId per determinare la cartella in cui recuperare i file delle mappe di origine. Assegna al releaseId lo stesso nome della cartella dei file della mappa di origine. Se hai usato lo script bash fornito sopra o uno simile, quello releaseId configurato nello script dovrebbe essere lo stesso configurato nel tuo client web CloudWatch RUM. È necessario utilizzare la versione 1.21.0 o successiva del client web 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
}

Abilitazione del monitor dell'app CloudWatch RUM per annullare la minimizzazione delle tracce dello stack JavaScript

Per annullare la minimizzazione delle tracce JavaScript dello stack, imposta lo stato dell'app monitor su. SourceMap ENABLED Fornisci l'URI di Amazon S3 al bucket o alla cartella contenente tutte le mappe di origine per il monitor dell'app.

Quando si archiviano le mappe di origine direttamente nel bucket principale (non in una sottocartella), l'URI di Amazon S3 deve essere formattato come Amazon S3://BUCKET_NAME. In questo caso, i file delle mappe di origine devono trovarsi nella seguente posizione.

BUCKET_NAME
    |- RELEASE_ID
        |-index.d5a07c87.js.map

Quando una directory secondaria è la directory root, l'URI di Amazon S3 deve essere formattato come Amazon S3://BUCKET_NAME/DIRECTORY. In questo caso, i file delle mappe di origine devono trovarsi nella seguente posizione.

BUCKET_NAME
    |- DIRECTORY
        |-RELEASE_ID
            |-index.d5a07c87.js.map

Visualizzazione delle tracce di stack deminificate nella console RUM

Dopo aver caricato le mappe di origine su Amazon S3, aver abilitato le mappe di origine sul monitor dell'app RUM e distribuito l'applicazione web con il client web releaseId configurato nel client web CloudWatch RUM, seleziona Eventi nella console RUM. Questa scheda mostra i dati grezzi degli eventi RUM. Filtra in base al tipo di evento di errore JS e visualizza l'ultimo evento di errore JS. Vedrai la traccia di stack deminificata nel nuovo campo event_details.unminifiedStack per gli eventi inseriti dopo l'attivazione della funzionalità.

Visualizzazione di tracce di stack non minimizzate nei log CloudWatch

Abilita l'archiviazione degli eventi RUM nei CloudWatch log attivando l'archiviazione dei dati. Una volta abilitato, puoi cercare nel nuovo campo event_details.unminifiedStack. Ciò consente di analizzare le tendenze e mettere in relazione i problemi in più sessioni utilizzando le query CloudWatch Logs.

Risoluzione dei problemi con le mappe di origine

CloudWatch RUM fornisce metriche predefinite per risolvere i problemi di configurazione della mappa di origine. Tali parametri sono pubblicati nel parametro spazio dei nomi denominato AWS/RUM. Le metriche seguenti sono pubblicate con una dimensione application_name. Il valore di questa dimensione è il nome del monitor dell'app. Le metriche sono anche pubblicate con una dimensione aws:releaseId. Il valore di questa dimensione è quello releaseId associato all'evento di errore. JavaScript

MetricName	Unità	Description
UnminifyLineFailureCount	Conteggio	Il conteggio delle righe della traccia di stack nell'evento di errore JS che non è stato deminificato. Ulteriori dettagli sull'errore verranno aggiunti alla riga specifica che ha avuto esito negativo nel campo event_details.unminifiedStack.
UnminifyLineSuccessCount	Conteggio	Il conteggio delle righe della traccia di stack nell'evento di errore JS che sono state deminificate correttamente.
UnminifyEventFailureCount	Conteggio	Il conteggio degli eventi di errore JS per i quali non è stata deminificata alcuna riga. Ulteriori dettagli sull'errore verranno aggiunti nel campo event_details.unminifiedStack.
UnminifyEventSuccessCount	Conteggio	Il conteggio degli eventi di errore JS che sono riusciti a rendere deminificata almeno una riga della traccia di stack.

CloudWatch RUM potrebbe non riuscire a deminimizzare una riga nello stack trace per vari motivi, tra cui, a titolo esemplificativo ma non esaustivo:

• Impossibile recuperare il file della mappa di origine corrispondente a causa di problemi di autorizzazione. Assicurati che la policy delle risorse del bucket sia configurata correttamente.

• Il file della mappa di origine corrispondente non esiste. Assicurati che i file delle mappe di origine siano stati caricati nel bucket o nella cartella corretti con lo stesso nome del releaseID configurato nel tuo client web RUM. CloudWatch

• Il file della mappa di origine corrispondente è troppo grande. Suddividi il codice sorgente in blocchi più piccoli.

• Sono già stati recuperati 50 MB di file di mappa sorgente per la traccia dello stack. Riduci la lunghezza della traccia di stack poiché 50 MB è una limitazione sul lato del servizio.

• La mappa di origine non è valida e non può essere indicizzata. Assicurati che la mappa di origine sia un semplice JSON che segue la struttura definita dalla specifica Source Map V3 e includa i seguenti campi: versione, file, origini, nomi, mappature.

• La mappa di origine non è riuscita a mappare il codice sorgente minificato alla traccia di stack deminificata. Assicurati che la mappa di origine sia quella corretta per il ReleaseID specificato.