Abilitazione della riduzione delle tracce dello stack di JavaScript errori

Quando il codice JavaScript sorgente dell'applicazione Web viene minimizzato, le tracce dello stack di errori possono essere difficili da leggere. Puoi abilitare l'unminificazione delle tracce dello stack caricando le tue mappe di origine su Amazon S3. CloudWatch RUM recupererà le mappe di origine per mappare i numeri di riga e colonna del codice sorgente minimizzato al codice sorgente originale non minimizzato. Ciò migliorerà la leggibilità delle tracce dello stack di 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 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, sourcesnames, e. mappings

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

Configura la policy delle risorse del bucket Amazon S3 per consentire l'accesso al servizio RUM

Assicurati che il tuo 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 del contesto aws:SourceArn e della condizione aws:SourceAccount globale per limitare le autorizzazioni del servizio alla risorsa. Questo è il modo più efficace per proteggersi dal problema di deputy confused.

L'esempio seguente mostra come utilizzare le chiavi di contesto aws:SourceArn e aws:SourceAccount global condition in Amazon S3 per evitare il confuso problema del vice.

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

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

Carica le mappe di origine

Configura il tuo JavaScript pacchetto per generare mappe di origine durante la minificazione. Quando create l'applicazione, il bundle creerà una directory (ad esempio, dist) contenente JavaScript i file minimizzati e le relative mappe di origine. 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 devono trovarsi in una cartella con releaseId il nome. Ad esempio, se il nome del mio bucket è my-application-source-maps ed 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 client web RUM CloudWatch

CloudWatch RUM utilizza il file configurato releaseId per determinare la cartella in cui recuperare i file della mappa di origine. Assegna lo releaseId stesso nome alla cartella dei file della mappa di origine. Se hai usato lo script bash fornito sopra o uno simile, lo script releaseId configurato nello script dovrebbe essere lo stesso di quello 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 minimizzare le tracce dello stack JavaScript

Per ridurre al minimo le tracce JavaScript dello stack, imposta lo stato del monitor dell'app 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 principale, 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 dello stack non minimizzate 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 aver distribuito l'applicazione Web con releaseId il client Web configurato nel 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 lo stack trace non minimizzato nel nuovo event_details.unminifiedStack campo per gli eventi inseriti dopo l'attivazione della funzionalità.

Visualizzazione delle tracce dello stack non minimizzate nei log CloudWatch

Abilita l'archiviazione degli eventi RUM nei CloudWatch registri 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 tra più sessioni utilizzando le query di Logs. CloudWatch

Risoluzione dei problemi relativi alle mappe sorgente

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

MetricName	Unità	Descrizione
UnminifyLineFailureCount	Conteggio	Il conteggio delle righe di traccia dello stack nell'evento di errore JS che non è stato minimizzato. Ulteriori dettagli sull'errore verranno aggiunti alla riga specifica che ha avuto esito negativo nel campo event_details.unminifiedStack.
UnminifyLineSuccessCount	Conteggio	Il numero di righe di traccia dello stack nell'evento di errore JS che sono state unminificate con successo.
UnminifyEventFailureCount	Conteggio	Il conteggio degli eventi di errore JS per i quali non è stata unminificata alcuna riga. Ulteriori dettagli sull'errore verranno aggiunti nel campo event_details.unminifiedStack.
UnminifyEventSuccessCount	Conteggio	Il numero di eventi di errore JS che sono riusciti a rendere unminificata almeno una riga di traccia dello 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 sorgente corrispondente a causa di problemi di autorizzazione. Assicurati che la politica delle risorse del bucket sia configurata correttamente.

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

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

• 50 MB di file di mappe sorgente già recuperati per lo stack trace. Riduci la lunghezza dello stack trace 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, fonti, nomi, mappature.

• La mappa di origine non è riuscita a mappare il codice sorgente minimizzato allo stack trace non minimizzato. Assicurati che la mappa dei sorgenti sia quella corretta per il ReleaseID specificato.