Configurações de exemplo do RUM SDK para mini programs - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  // Additional parameters
});

Parâmetros de inicialização

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`pid`	String	Sim	-	ID do mini program.
`endpoint`	String	Sim	-	Endereço para envio dos dados de monitoramento.
`env`	String	Não	`prod`	Ambiente de implantação. Valores válidos: `prod` (produção), `gray` (canary release), `pre` (pré-lançamento), `daily` (diário), `local` (local).
`version`	String	Não	-	Versão do mini program.
`user`	Object	Não	`user.id` gerado pelo SDK	Configurações de identidade do usuário. Consulte parâmetros user.
`collectors`	Object	Não	-	Configurações dos coletores de dados. Consulte parâmetros collectors.
`beforeReport`	Function	Não	noop	Callback invocado antes de cada relatório. Use-o para modificar ou bloquear dados de saída.
`reportConfig`	Object	Não	`{ flushTime: 3000, maxEventCount: 20 }`	Configurações de relatório de dados. Consulte parâmetros reportConfig.
`sessionConfig`	Object	Não	-	Configurações de amostragem e tempo limite de sessão. Consulte parâmetros sessionConfig.
`parseViewName`	Function	Não	-	Analisa o nome da visualização (`view.name`) a partir da URL da página.
`parseResourceName`	Function	Não	-	Extrai o nome do recurso (`resource.name`) da URL do recurso.
`evaluateApi`	Function	Não	-	Parser personalizado para eventos de API. Consulte parâmetros evaluateApi.
`filters`	Object	Não	-	Regras de filtragem de eventos. Consulte parâmetros filters.
`properties`	Object	Não	-	Propriedades personalizadas anexadas a todos os eventos. Consulte parâmetros properties.

Parâmetros `user`

Configure a identidade do usuário para rastreamento de sessão.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`id`	String	Não	Gerado pelo SDK	ID do usuário. O SDK gera este valor e ele não pode ser modificado.
`tags`	String	Não	-	Tags de usuário para categorização.
`name`	String	Não	-	Nome de usuário.

Importante

Não sobrescreva user.id. Alterar esse valor afeta os dados de visitantes únicos (UV). Para integrar seu próprio sistema de contas, defina user.name ou user.tags.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  user: {
    name: getYourUserName(),
    tags: getYourTags(),
  }
});

Parâmetros `reportConfig`

Controle a frequência e o tamanho do lote de envio de dados do SDK.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`flushTime`	Number	Não	`3000`	Intervalo de relatório em milissegundos. Valores válidos: 0 a 10000. Defina como `0` para envio imediato.
`maxEventCount`	Number	Não	`20`	Número máximo de eventos por relatório. Valores válidos: 1 a 100.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  reportConfig: {
    flushTime: 0,          // Report data immediately
    maxEventCount: 50      // Send up to 50 events per batch
  }
});

Parâmetros `sessionConfig`

Gerencie as taxas de amostragem de sessão e tempos limite. Use a amostragem para reduzir o volume de dados em ambientes de alto tráfego.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`sampleRate`	Number	Não	`1`	Taxa de amostragem. Valores válidos: 0 a 1. Por exemplo, `0.5` aplica uma taxa de amostragem de 50%.
`maxDuration`	Number	Não	`86400000`	Duração máxima da sessão em milissegundos. Padrão: 24 horas.
`overtime`	Number	Não	`1800000`	Tempo limite da sessão em milissegundos. A sessão expira após este período de inatividade. Padrão: 30 minutos.

Cache local

O SDK armazena o ID do usuário e os dados de sessão no cache local do mini program:

_arms_uid: ID único do usuário (user.id).
_arms_session: metadados da sessão no formato ${sessionId}-${sampled}-${startTime}-${lastTime}, onde:
- sessionId: ID único da sessão.
- sampled: indica se a amostragem foi acionada.
- startTime: timestamp de início da sessão.
- lastTime: timestamp da última atividade.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  sessionConfig: {
    sampleRate: 0.5,          // 50% sampling rate
    maxDuration: 86400000,    // 24-hour max session
    overtime: 3600000,        // 1-hour inactivity timeout
  },
});

Parâmetros `collectors`

Os coletores reúnem tipos específicos de dados de monitoramento. Cada coletor pode ser ativado (true), desativado (false) ou configurado com um objeto de opções.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`api`	Boolean \	Object	Não	`true`	Rastreia requisições de API.
`jsError`	Boolean \	Object	Não	`true`	Rastreia erros de JavaScript.
`consoleError`	Boolean \	Object	Não	`true`	Rastreia erros provenientes de `console.error`.
`action`	Boolean \	Object	Não	`true`	Rastreia interações do usuário.

Exemplo

Desative o rastreamento de interação do usuário:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  collectors: {
    action: false,
  }
});

Parâmetros `evaluateApi`

A função evaluateApi fornece análise personalizada para eventos de API, incluindo eventos request e httpRequest. Ela aceita três argumentos e retorna um Promise<IApiBaseAttr>.

Assinatura da função:

evaluateApi: async (options, response, error?) => IApiBaseAttr

Argumentos:

Parâmetro	Tipo	Descrição
`options`	Object	Parâmetros da requisição, incluindo `url`, `headers` e `data`. Os campos exatos dependem do método de requisição.
`response`	Object	Corpo da resposta.
`error`	Error	Objeto de erro. Presente apenas quando a requisição falha.

**Valor de retorno (IApiBaseAttr):**

Os campos retornados substituem os padrões do SDK. Campos omitidos mantêm seus valores padrão.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	String	Não	Nome da API, geralmente uma URL convergida. Máximo de 1.000 caracteres. Por exemplo, `/list/123` torna-se `/list/$id`. Este valor tem precedência sobre `parseResourceName`.
`message`	String	Não	Breve descrição da API. Máximo de 1.000 caracteres.
`success`	Number	Não	Resultado da requisição: `1` (sucesso), `0` (falha), `-1` (desconhecido).
`duration`	Number	Não	Duração total da requisição.
`status_code`	Number \	String	Não	Código de status HTTP.
`snapshots`	String	Não	Dados de depuração como `reqHeaders`, `params` e `resHeaders`. Máximo de 5.000 caracteres. Snapshots não são indexados e não podem ser usados como condições de filtro para consultas ou agregação.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  evaluateApi: async (options, response, error) => {
    const respText = JSON.stringify(response);

    // Returned fields overwrite defaults. Omitted fields keep default values.
    return {
      name: 'my-custom-api',
      success: error ? 0 : 1,
      snapshots: JSON.stringify({
        params: 'page=1&size=10',
        response: respText.substring(0, 2000),
        reqHeaders: '',
        resHeaders: ''
      })
    }
  }
});

Parâmetros `filters`

Exclua eventos específicos de recursos e exceções dos relatórios.

Parâmetro	Tipo	Obrigatório	Descrição
`resource`	MatchOption \	MatchOption[]	Não	Exclui eventos de recursos estáticos e de API (como XMLHttpRequest ou fetch).
`exception`	MatchOption \	MatchOption[]	Não	Exclui eventos de exceção.

MatchOption

type MatchOption = string | RegExp | ((value: string) => boolean);

Três modos de correspondência estão disponíveis:

String: corresponde a qualquer URL que comece com o valor especificado. Por exemplo, 'https://api.aliyun.com' corresponde a https://api.aliyun.com/v1/resource.
RegExp: corresponde a URLs usando uma expressão regular.
Function: função personalizada que retorna true para excluir o evento.

Quando MatchOption[] é fornecido, as condições são avaliadas em ordem. Um evento é excluído se qualquer condição corresponder.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  filters: {
    // Exclude exception events
    exception: [
      'Test error',                    // Prefix match
      /^Script error\.?$/,             // Regex match
      (msg) => {
        return msg.includes('example-error');  // Custom function
      },
    ],
    // Exclude resource and API events
    resource: [
      'https://example.com/',          // Prefix match
      /localhost/i,                     // Regex match (case-insensitive)
      (url) => {
        return url.includes('example-resource');
      },
    ],
  },
});

Parâmetros `properties`

Anexe propriedades personalizadas de chave-valor a todos os eventos.

Parâmetro	Tipo	Obrigatório	Descrição
`[key: string]`	String \	Number	Não	Propriedade personalizada. Chave: máximo de 50 caracteres (o excesso é truncado). Valor String: máximo de 2.000 caracteres. Valores que não sejam string ou number são removidos.

Comportamento de mesclagem:

Propriedades globais (definidas em init()) e propriedades de nível de evento (definidas via evaluateApi, sendCustom, sendException ou sendResource) são mescladas no momento do armazenamento.
As propriedades de nível de evento têm precedência sobre as propriedades globais com a mesma chave.
Após a mesclagem, o número total de pares chave-valor não pode exceder 20. Os pares excedentes são classificados por chave e removidos.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  properties: {
    prop_string: 'xx',
    prop_number: 2,
    // Keys or values exceeding the length limit are truncated
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    more_than_2000_value_limit: new Array(2003).join('1'),
    // Invalid values are removed
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

Parâmetros resolvidos automaticamente

O SDK resolve automaticamente as seguintes propriedades a partir de endereços IP e strings UserAgent. Valores configurados manualmente têm precedência sobre os valores resolvidos automaticamente.

Parâmetro	Tipo	Obrigatório	Descrição
`device`	Object	Não	Informações do dispositivo.
`os`	Object	Não	Informações do sistema operacional e do contêiner.
`geo`	Object	Não	Informações de geolocalização.
`isp`	Object	Não	Informações do provedor de internet (ISP).
`net`	Object	Não	Informações de rede.

Para descrições dos campos, consulte Atributos comuns.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  geo: {
    country: '<your-country>',
    city: '<your-city>',
  },
});

APIs do SDK

Use as APIs a seguir para ler e modificar configurações em tempo de execução e para reportar dados personalizados.

getConfig

Recupere a configuração atual do SDK:

const config = ArmsRum.getConfig();

setConfig

Atualize a configuração do SDK após a inicialização:

// Update a single parameter
ArmsRum.setConfig('env', 'pre');

// Update multiple parameters
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
  ...config,
  version: '1.0.0',
  env: 'pre',
});

sendCustom

Reporte um evento personalizado. Tanto type quanto name são obrigatórios.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`type`	String	Sim	-	Tipo do evento.
`name`	String	Sim	-	Nome do evento.
`group`	String	Não	-	Grupo do evento.
`value`	Number	Não	-	Valor numérico associado ao evento.

ArmsRum.sendCustom({
  type: 'CustomEventType1',
  name: 'customEventName2',
  group: 'customEventGroup3',
  value: 111.11
});

sendException

Reporte uma exceção personalizada. Tanto name quanto message são obrigatórios.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`name`	String	Sim	-	Nome da exceção.
`message`	String	Sim	-	Mensagem da exceção.
`file`	String	Não	-	Arquivo onde a exceção ocorreu.
`stack`	String	Não	-	Rastreamento de pilha (stack trace).
`line`	Number	Não	-	Número da linha.
`column`	Number	Não	-	Número da coluna.

ArmsRum.sendException({
  // Required
  name: 'customErrorName',
  message: 'custom error message',
  // Optional
  file: 'custom exception filename',
  stack: 'custom exception error.stack',
  line: 1,
  column: 2
});

sendResource

Reporte um evento de recurso personalizado. Os parâmetros name, type e duration são obrigatórios.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`name`	String	Sim	-	Nome do recurso.
`type`	String	Sim	-	Tipo de recurso, como `script`, `api` ou `image`.
`duration`	String	Sim	-	Tempo de resposta.
`success`	Number	Não	-	Resultado da requisição: `1` (sucesso), `0` (falha), `-1` (desconhecido).
`method`	String	Não	-	Método da requisição.
`status_code`	Number \	String	Não	-	Código de status HTTP.
`message`	String	Não	-	Mensagem descritiva.
`url`	String	Não	-	URL da requisição.
`trace_id`	String	Não	-	ID de rastreamento para tracing distribuído.

ArmsRum.sendResource({
  // Required
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  // Optional
  url: 'https://www.example.com/data/getListByPage',
});

Parâmetros de inicialização

Parâmetros user

Exemplo

Parâmetros reportConfig

Exemplo

Parâmetros sessionConfig

Cache local

Exemplo

Parâmetros collectors

Exemplo

Parâmetros evaluateApi

Exemplo

Parâmetros filters

MatchOption

Exemplo

Parâmetros properties

Exemplo

Parâmetros resolvidos automaticamente

Exemplo

APIs do SDK

getConfig

setConfig

sendCustom

sendException

sendResource

Parâmetros `user`

Parâmetros `reportConfig`

Parâmetros `sessionConfig`

Parâmetros `collectors`

Parâmetros `evaluateApi`

Parâmetros `filters`

Parâmetros `properties`