Como instalar o agente do ARMS Browser Monitoring usando npm - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Quando sua aplicação web precisa de visibilidade em tempo real sobre o desempenho da página, erros de JavaScript, taxas de sucesso de API e comportamento do usuário, o Application Real-Time Monitoring Service (ARMS) Browser Monitoring coleta e reporta esses dados por meio de um SDK leve. Instale o SDK via npm para integrá-lo ao código frontend durante a compilação e eliminar qualquer impacto no tempo de carregamento da página em runtime.

Com o npm, o SDK é integrado à aplicação durante o processo de build, sem afetar o desempenho de carregamento da página. No entanto, erros e carregamentos de recursos anteriores à conclusão da inicialização não são capturados. Para rastrear todos os eventos desde o início do carregamento da página, utilize a configuração baseada em CDN.

Pré-requisitos

Antes de começar, verifique se você tem:

Uma conta Alibaba Cloud com o ARMS ativado
Um site do Browser Monitoring criado no console do ARMS, que fornece o pid (ID do projeto) e a imgUrl (endpoint de reporte)
Node.js e um gerenciador de pacotes (npm, yarn ou pnpm) instalados

Etapa 1: Instalar o SDK

Instale o pacote @arms/js-sdk:

# npm
npm install @arms/js-sdk --save

# yarn
yarn add @arms/js-sdk

# pnpm
pnpm add @arms/js-sdk

Etapa 2: Inicializar o SDK

Importe o SDK no ponto de entrada da aplicação e chame BrowserLogger.singleton() para criar uma instância singleton. Substitua os placeholders pelos valores reais.

Sintaxe CommonJS:

const BrowserLogger = require('@arms/js-sdk');

const __bl = BrowserLogger.singleton({
  pid: '<your-pid>',              // Project ID from the ARMS console
  appType: 'web',
  imgUrl: '<your-imgUrl>',        // Reporting endpoint from the ARMS console
  // enableSPA: true,             // Uncomment for single-page applications
  // enableLinkTrace: true,       // Uncomment for front-to-back tracing
});

Sintaxe de módulo ES:

import BrowserLogger from '@arms/js-sdk';

const __bl = BrowserLogger.singleton({
  pid: '<your-pid>',              // Project ID from the ARMS console
  appType: 'web',
  imgUrl: '<your-imgUrl>',        // Reporting endpoint from the ARMS console
});

Substitua os seguintes placeholders pelos valores reais:

Placeholder	Descrição	Onde encontrar
`<your-pid>`	ID único do projeto	Gerado automaticamente pelo ARMS ao criar um site
`<your-imgUrl>`	URL do endpoint de reporte de dados	Fornecida ao criar um site do Browser Monitoring. Exemplo: `https://arms-retcode.aliyuncs.com/r.png?`

Nota

Nota: BrowserLogger.singleton() é um método estático que retorna um objeto singleton. Os parâmetros config e prePipe têm efeito apenas na primeira chamada. Chamadas subsequentes retornam a instância existente.

Definir um ID de usuário personalizado

Por padrão, o SDK gera um ID de usuário (UID) para rastrear visitantes únicos (UVs). Esse UID gerado automaticamente serve para buscar o usuário, é atualizado a cada seis meses e não contém atributos de negócio.

Para usar seu próprio identificador, adicione o parâmetro uid:

const __bl = BrowserLogger.singleton({
  pid: '<your-pid>',
  appType: 'web',
  uid: '<your-custom-uid>',       // Custom user identifier
  imgUrl: '<your-imgUrl>',
});

Etapa 3: Verificar a configuração

Após implantar a aplicação com o SDK inicializado:

Abra a aplicação em um navegador e interaja com a página.
Faça login no console do ARMS e acesse Browser Monitoring.
Selecione a aplicação e verifique se os dados de visualização de página (PV) e as métricas de desempenho aparecem na página de visão geral.

Caso nenhum dado apareça, verifique se há erros no console do navegador e confirme se os valores de pid e imgUrl estão corretos.

Referência de configuração

Os parâmetros de configuração são os mesmos da importação via CDN. A tabela abaixo lista os parâmetros comuns do SDK. Para a lista completa, consulte a referência do SDK.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`pid`	String	Sim	Nenhum	ID único do projeto. Gerado automaticamente pelo ARMS ao criar um site.
`uid`	String	Não	Gerado automaticamente	Identificador de usuário para rastrear visitantes únicos. Use este valor para buscar o usuário. Se omitido, o SDK gera um e o rotaciona a cada seis meses.
`tag`	String	Não	Nenhum	Tag personalizada anexada a cada entrada de log.
`release`	String	Não	`undefined`	Versão da aplicação. Defina este valor para comparar métricas entre diferentes releases.
`environment`	String	Não	`prod`	Ambiente de implantação. Valores válidos: `prod` (produção), `gray` (liberação gradual), `pre` (staging), `daily` (build diária), `local` (desenvolvimento local).
`sample`	Integer	Não	`1`	Taxa de amostragem para logs de desempenho e logs de API bem-sucedidos. Inteiro de 1 a 100. Os logs são amostrados na proporção de `1/sample`. Para mais detalhes, consulte Métricas estatísticas.
`behavior`	Boolean	Não	`true`	Registra o comportamento do usuário anterior aos erros para facilitar a solução de problemas.
`enableSPA`	Boolean	Não	`false`	Escuta eventos `hashchange` e reporta novamente dados de PV. Ative esta opção para aplicações de página única (SPAs).
`enableLinkTrace`	Boolean	Não	`false`	Habilita o rastreamento de ponta a ponta para correlacionar requisições do frontend com traces do backend. Para mais detalhes, consulte Usar rastreamento de ponta a ponta para diagnosticar erros de API.

Reportar dados pré-inicialização

Se alguma lógica for executada antes da chamada de BrowserLogger.singleton(), passe um array prePipe como segundo argumento para enfileirar esses dados para reporte. A estrutura do pipe segue o mesmo formato da configuração baseada em CDN.

const BrowserLogger = require('@arms/js-sdk');

// Queue data to report before the SDK initializes
const pipe = [
  // Report the current page as an API call
  // Equivalent to: __bl.api(api, success, time, code, msg)
  ['api', '/index.html', true, performance.now, 'SUCCESS'],

  // Enable SPA mode after initialization
  ['setConfig', { enableSPA: true }],
];

const __bl = BrowserLogger.singleton({ pid: '<your-pid>' }, pipe);

Para mais detalhes, consulte Dados de pré-reporte.

Referência da API

BrowserLogger.singleton(config, prePipe)

Método estático que retorna uma instância singleton de BrowserLogger. Disponível apenas quando você importa o SDK via npm.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`config`	Object	Sim	Nenhum	Objeto de configuração do site. Consulte a Referência de configuração e a referência do SDK.
`prePipe`	Array	Não	Nenhum	Array de dados pré-enfileirados para reporte na inicialização.

Chame este método no ponto de entrada da aplicação para inicializar o SDK ou de qualquer módulo para recuperar a instância existente:

// Retrieve the existing singleton instance from any module
const __bl = BrowserLogger.singleton();

Métodos de reporte

Use a instância __bl para reportar dados personalizados. Para a lista completa de APIs, consulte a referência da API Frontend.