Application Real-Time Monitoring Service:Análise automática de source map para Web e H5

Pré-requisitos

Certifique-se de que sua aplicação web esteja integrada ao Real User Monitoring (RUM). Para obter instruções, consulte Integrar uma aplicação web ou H5.

Ferramentas de build suportadas

O recurso de análise automática de source map do RUM suporta atualmente as seguintes ferramentas de build:

• Webpack

• Vite

Utilize o plugin de ferramenta de build do RUM

Envio automático de arquivos de source map

Para simplificar seu fluxo de trabalho, configure o plugin de ferramenta de build do RUM para enviar automaticamente os arquivos de source map ao armazenamento OSS do RUM após a injeção dos UUIDs.

Etapa 1: Ativar o switch de envio em lote

Para obter permissões de gravação no OSS do RUM, faça login no ARMS console como um usuário RAM. Para sua aplicação RUM, acesse a página Application Settings e ative o switch de envio em lote para o OSS.

Esse switch está localizado na aba File Management.

Etapa 2: Obter o AccessKey ID e o Secret

Forneça o AccessKey ID e o AccessKey Secret do usuário RAM ao plugin de ferramenta de build do RUM.

Ao criar o AccessKey, selecione Use in local development environment como caso de uso. Para instruções detalhadas, consulte Criar um AccessKey para um usuário RAM.

Após selecionar essa opção, o sistema recomenda evitar codificar as informações do AccessKey diretamente no código e, em vez disso, usar variáveis de ambiente para configurar suas credenciais. Marque a caixa de seleção I confirm that I must create an AccessKey e clique em Continue to Create.

Etapa 3: Configurar o plugin

Na configuração do plugin de ferramenta de build do RUM, insira o ID da aplicação RUM, o AccessKey ID, o AccessKey Secret, a versão e a região da sua aplicação. A versão serve para agrupar os arquivos de source map enviados no ARMS console e tem como padrão 1.0.0. A região padrão é cn-hangzhou.

import { RumWebpackPlugin } from '@arms/rum-webpack-plugin'
const config = {
  plugins: [new RumWebpackPlugin({
    pid: '',  // RUM application ID
    accessKeyId: '',
    accessKeySecret: '',
    version: '',
    region: ''
  })],
  devtool: 'source-map',
};
export default config

import { rumVitePlugin } from '@arms/rum-vite-plugin'
export default defineConfig({
  plugins: [rumVitePlugin({
    pid: '',  // RUM application ID
    accessKeyId: '',
    accessKeySecret: '',
    version: '',
    region: ''
  })],
  build: {
    sourcemap: true,
  },  
});

Envio manual de arquivos de source map

Etapa 1: Compilar o projeto

Utilize o comando de build fornecido pela sua ferramenta de build para compilar o projeto. Em seguida, o plugin de ferramenta de build do RUM injeta um UUID nos arquivos JS e em seus respectivos arquivos de source map.

A presença do campo debugId no arquivo de source map indica que o UUID foi injetado com sucesso.

{
    "version": 3,
    "file": "index.js",
    "mappings": "AAAAA,QAAQC,IAAI",
    "sources": [
        "webpack://examples/./src/index.js"
    ],
    "sourcesContent": [
        "console.log('Hello World!');\n"
    ],
    "names": [
        "console",
        "log"
    ],
    "sourceRoot": "",
    "debugId": "e4f083d6-b8d8-4cae-a0ea-16f2e83a6be1"
}

Após abrir a página em um navegador, confirme a injeção do UUID no arquivo JS verificando a propriedade _armsRumDebugIds no objeto global window.

> window._armsRumDebugIds
< {"Error\n    at file:///Users/yy/Projects/rum-bundler-plugin/packages/examples/dist/webpack5/index.js:1:128": "e4f083d6-b8d8-4cae-a0ea-16f2e83a6be1"}

Etapa 2: Enviar manualmente os arquivos de source map

Caso não utilize o recurso de envio automático, envie os arquivos manualmente pelo ARMS console. Na página Application Settings, dentro da seção File Management, faça o upload dos arquivos de source map que já possuem o UUID injetado. Se o UUID correspondente aparecer na coluna UUID, isso indica que o arquivo foi analisado com sucesso.

Durante o envio, insira uma version (por exemplo, 1.0.0) e clique em Batch Upload.

Etapa 3: Verificar a análise automática

Na página Exception Statistics, acesse a página de detalhes de uma exceção específica. Cada linha do stack trace exibe o UUID injetado pelo plugin de ferramenta de build do RUM. Um hífen (-) indica falha no reporte do UUID.

Se um arquivo de source map com UUID correspondente tiver sido enviado, o RUM analisa automaticamente a primeira linha do stack trace para mostrar a localização do erro no arquivo de origem. Clique em qualquer outra linha para expandir e visualizar o resultado da análise.

Após a análise do SourceMap, o arquivo de origem estará localizado em webpack://demo/index.tsx. O erro encontra-se na linha 14: throw new Error('test error'). O código-fonte analisado é apresentado abaixo.

import React from 'react';
import Page from '@alicloud/console-components-page';
import TestCode from './TestCode';
const TestPage = () => {
  return (
    <Page>
      &lt;Page.Header title="Test" /&gt;
      &lt;Page.Content&gt;
        <IncidentPlanTable />
        <button
          onClick={() => {
            throw new Error('test error');
          }}
        >
          test
        </button>
      &lt;Page.Content&gt;
    </Page>
  );
};

Notas de lançamento do plugin de ferramenta de build do RUM

Perguntas frequentes

O que fazer se os arquivos de source map forem enviados com sucesso, mas a página de detalhes da exceção não exibir o código-fonte?

Isso ocorre quando o arquivo de source map enviado não contém o conteúdo do código-fonte (campo sourcesContent). Para resolver:

1. Verifique a configuração da sua ferramenta de build de front-end para garantir que a inclusão do código-fonte esteja ativada durante a geração dos arquivos de source map.

2. Utilize uma ferramenta de terceiros, como decodeSourceMap, para validar se o arquivo de source map gerado localmente contém o campo sourcesContent.

3. Confirme se o arquivo de source map armazenado no OSS está formatado corretamente e acessível.

O ARMS RUM suporta buckets OSS personalizados para envio de arquivos de source map?

Não. O ARMS RUM não oferece suporte a buckets OSS personalizados. O serviço provisiona buckets OSS dedicados para cada região . Basta ativar o switch OSS batch upload na aba File Management da página Application Settings para utilizar diretamente o bucket provisionado. Não é possível especificar um bucket diferente.

O que fazer se arquivos de source map enviados via ossutil ou outras ferramentas não aparecerem no ARMS console?

O envio de arquivos usando caminhos baseados em pastas ou estruturas de diretórios não padronizadas pode impedir a exibição correta da lista de arquivos no ARMS console. Recomendamos o uso do plugin de ferramenta de build do RUM para Webpack ou Vite, pois ele gerencia o envio de source maps automaticamente. Caso precise enviar arquivos manualmente, siga as etapas descritas na seção Envio manual de arquivos de source map deste tópico: na página Application Settings, dentro da seção File Management, utilize o recurso Batch Upload e informe o número correto da versão.

Como configurar o endpoint se minha aplicação estiver implantada em uma região diferente da região do serviço ARMS RUM?

O armazenamento de source map do ARMS RUM está disponível apenas nas seguintes regiões: China (Hangzhou), Singapura (Sudeste da Ásia 1) e Vale do Silício (Oeste dos EUA 1). Se sua aplicação estiver em outra região, configure o endpoint na sua aplicação cliente ou na configuração do plugin para apontar para uma dessas três regiões suportadas, permitindo a conexão com o bucket OSS provisionado. Não é possível usar um endpoint de região local para o envio de source maps.