Habilitación de la desminificación de seguimientos de pila de errores de JavaScript

Cuando el código fuente JavaScript de la aplicación web está minificado, los seguimientos de pila de los errores pueden resultar difíciles de leer. Para habilitar la desminificación de los seguimientos de pila, puede cargar sus mapas de origen en Amazon S3. CloudWatch RUM recuperará los mapas de origen para vincular los números de línea y columna del código fuente minificado con el código fuente original no minificado. Esto mejorará la legibilidad de los seguimientos de pila de los errores y ayudará a identificar la ubicación del error en el código fuente original.

Requisitos y sintaxis

Los mapas de origen son fundamentales para depurar y hacer un seguimiento de los problemas de la aplicación web en las distintas versiones. Asegúrese de que cada versión de la aplicación web tenga un mapa de origen único. Cada versión debería tener su propio releaseId único. El releaseId debe ser una cadena de entre 1 y 200 caracteres y solo puede contener letras, números, guiones bajos, guiones, dos puntos, barras y puntos. Para añadir el releaseId como metadato a los eventos de RUM, configure el cliente web de CloudWatch RUM.

Se espera que los mapas de origen sean archivos JSON simples que sigan la estructura definida por la especificación Source Map V3. Los campos obligatorios son version, file, sources, names y mappings.

Asegúrese de que el tamaño de cada mapa de origen no supere el límite de 50 MB. Además, el servicio RUM solo recuperará hasta 50 MB de mapas de origen por seguimiento de pila. Si es necesario, divida el código fuente en varios fragmentos más pequeños. Para obtener más información, consulte División de código con WebpackJS.

Configuración de la política de recursos de su bucket de Amazon S3 para permitir el acceso al servicio RUM

Asegúrese de que su bucket de Amazon S3 se encuentre en la misma región que su appMonitor de RUM. Configure su bucket de Amazon S3 para permitir el acceso al servicio RUM para recuperar los archivos de mapas de origen. Incluya las claves de contexto de condición globales aws:SourceArn y aws:SourceAccount para limitar los permisos del servicio al recurso. Esta es la forma más eficaz de protegerse contra el problema del suplente confuso.

En el ejemplo siguiente se muestra cómo se pueden utilizar las claves de contexto de condición globales aws:SourceArn y aws:SourceAccount en Amazon S3 para evitar el problema del suplente 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"
                }
            }
        }
    ]
}

Si utiliza claves de AWS KMS para cifrar los datos, asegúrese de que la política de recursos de la clave esté configurada de manera similar para incluir las claves de contexto de condición globales aws:SourceArn y aws:SourceAccount con el fin de dar acceso al servicio RUM para usar las claves y recuperar los archivos de los mapas de origen.

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

Carga de mapas de origen

Configure su paquete de JavaScript para generar mapas de origen durante la minificación. Cuando cree su aplicación, el paquete creará un directorio (por ejemplo, dist) que contiene los archivos JavaScript minificados y sus mapas de origen correspondientes. Consulte a continuación un ejemplo.

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

Cargue los archivos de los mapas de origen en el bucket de Amazon S3. Los archivos deben estar ubicados en una carpeta con el releaseId como nombre. Por ejemplo, si el nombre de mi bucket es my-application-source-maps y el releaseId es 2.0.0, significa que el archivo del mapa de origen se encuentra en la siguiente ubicación:

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

Para automatizar la carga de los mapas de origen, puede crear el siguiente script Bash y ejecutarlo como parte de su proceso de creación.

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

Configuración del releaseId en el cliente web de CloudWatch RUM

CloudWatch RUM utiliza el releaseId configurado para determinar la carpeta de la que recuperar los archivos de los mapas de origen. Asigne al releaseId el mismo nombre que a la carpeta de archivos de mapas de origen. Si usó el script Bash proporcionado anteriormente o uno similar, el releaseId configurado en el script debe ser el mismo que el configurado en su cliente web de CloudWatch RUM. Debe utilizar la versión 1.21.0 o posterior del cliente web de 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
}

Habilitación del monitor de aplicaciones CloudWatch RUM para desminificar los seguimientos de pila de JavaScript

Para desminificar los seguimientos de pila de JavaScript, establezca el estado SourceMap del monitor de aplicaciones en ENABLED. Proporcione el URI de Amazon S3 del bucket o la carpeta que contiene todos los mapas de origen para el monitor de su aplicación.

Si se almacenan los mapas de origen directamente en el bucket principal (no en una subcarpeta), el URI de Amazon S3 debe tener el formato Amazon S3://BUCKET_NAME. En este caso, los archivos de los mapas de origen deben estar en la siguiente ubicación.

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

Cuando la raíz es un directorio secundario, el formato del URI de Amazon S3 debe ser Amazon S3://BUCKET_NAME/DIRECTORY. En este caso, los archivos de los mapas de origen deben estar en la siguiente ubicación.

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

Visualización de seguimientos de pila desminificados en la consola de RUM

Después de cargar los mapas de origen en Amazon S3, habilitar los mapas de origen en el monitor de aplicaciones RUM e implementar la aplicación web con el releaseId configurado en el cliente web de CloudWatch RUM, seleccione Eventos en la consola de RUM. En esta pestaña se muestran los datos sin procesar de los eventos de RUM. Filtre los datos por el tipo de evento de error de JS y vea el último evento de error de JS. Verá el seguimiento de pila sin minificar en el nuevo campo event_details.unminifiedStack correspondiente a los eventos ingeridos después de habilitar la característica.

Visualización de los seguimientos de pila sin minificar en CloudWatch Logs

Para habilitar el almacenamiento de eventos de RUM en CloudWatch Logs, active el Almacenamiento de datos. Una vez habilitado, puede buscar en el nuevo campo event_details.unminifiedStack. Esto le permite analizar las tendencias y relacionar los problemas de varias sesiones con las consultas de CloudWatch Logs.

Solución de problemas con los mapas de origen

CloudWatch RUM proporciona métricas listas para usar para solucionar los problemas de configuración de los mapas de origen. Estas métricas se publican en el espacio de nombres de la métrica llamado AWS/RUM. Las métricas siguientes se publican con una dimensión de application_name. El valor de esta dimensión es el nombre del supervisor de aplicaciones. Las métricas también se publican con una dimensión de aws:releaseId. El valor de esta dimensión es el releaseId asociado al evento de error de JavaScript.

Es posible que CloudWatch RUM no pueda desminificar alguna línea del seguimiento de pila por diferentes motivos, entre los que se incluyen los siguientes: