miniapp SDK configuration reference - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Configuração do SDK

Parâmetro	Tipo	Descrição	Obrigatório	Valor padrão
pid	String	ID do mini programa.	Sim	-
endpoint	String	Endereço para envio dos dados de monitoramento.	Sim	-
env	-	Ambiente da aplicação: prod: ambiente de produção Gray: ambiente de grayscale pre: ambiente de pré-lançamento daily: ambiente diário local: ambiente local	Não	prod
version	String	Versão do mini programa.	Não	-
user	Object	Configuração do usuário. O SDK gera o user.id por padrão.	Não	-
collectors	Object	Configuração de cada Collector.	Não	-
beforeReport	Function	Função executada antes do envio de dados para modificar ou bloquear o reporte.	Não	-
reportConfig	Object	Configuração de reporte. Para mais informações, consulte reportConfig configuration.	Não	{ flushTime: 3000, maxEventCount: 20 }
sessionConfig	Object	Taxa de amostragem e tempo limite da sessão. Para mais informações, consulte sessionConfig parameters.	Não	-
longTaskConfig	Object	Número máximo de reportes de travamentos e limiar de tempo para identificar um travamento. Para mais informações, consulte longTaskConfig configuration.	Não	{ maxEventCount: 5, renderThreshold: 50 }
parseViewName	Function	Analisa o nome da visualização (view.name). Recebe a URL da página como parâmetro de entrada.	Não	-
parseResourceName	Function	Analisa o nome do recurso (resource.name). Recebe a URL do recurso como parâmetro de entrada.	Não	-
evaluateApi	Function	Analisa eventos de API. Para mais informações, consulte evaluateApi parameters.	Não	-
filters	Object	Filtragem de eventos. Para mais informações, consulte filters parameters.	Não	-
properties	Object	Propriedades personalizadas aplicáveis a todos os eventos. Para mais informações, consulte properties parameters.	Não	-
remoteConfig	object	Configuração dinâmica. Para mais informações, consulte Dynamic configuration.	Não	-

Configuração de usuário

Parâmetro	Tipo	Descrição	Obrigatório	Valor padrão
id	String	ID do usuário gerado pelo SDK. Não é modificável.	Não	ID padrão gerado pelo SDK
tags	String	Tags associadas ao usuário.	Não	-
name	String	Nome do usuário.	Não	-

Nota

Para usar seu próprio sistema de contas, altere o nome de usuário (user.name) ou as tags (user.tags) em vez do ID do usuário (user.id). Sobrescrever o user.id afeta os dados de visitantes únicos (UV).

Exemplo

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

Parâmetros de reportConfig

Parâmetro

Tipo

Descrição

Obrigatório

Valor padrão

flushTime

Number

Intervalo de envio de dados.

Valores válidos: 0 a 10000.

Unidade: milissegundos (ms).

Não

3000

maxEventCount

Number

Número máximo de entradas de dados enviadas por vez.

Valores válidos: 1 a 100.

Não

20

Exemplo

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  reportConfig: {
    flushTime: 0, // Specify that data is immediately reported.
    maxEventCount: 50 // Specify the maximum number of data entries reported at a time.
  }
});

Configuração sessionConfig

Parâmetro

Tipo

Descrição

Obrigatório

Valor padrão

sampleRate

Number

Taxa de amostragem. Valores válidos: 0 a 1.

O valor 0,5 define uma taxa de amostragem de 50%.

Não

1

maxDuration

Number

Duração máxima da sessão. Unidade: milissegundos. Valor padrão: 86400000 (24 horas).

Não

86400000

overtime

Number

Tempo limite da sessão. Unidade: milissegundos. Valor padrão: 1800000 (meia hora).

Não

1800000

O cache local do mini programa armazena o ID do usuário e as informações da sessão:

_arms_uid: ID único do usuário (user.id).
_arms_session: informações semânticas da sessão.
- 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 da sessão.

`${sessionId}-${sampled}-${startTime}-${lastTime}`

Exemplo

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  sessionConfig: {
    sampleRate: 0.5, // Specify a 50% sampling rate. 
    maxDuration: 86400000,
    overtime: 3600000,
  },
});

Configuração longTaskConfig

Parâmetro

Tipo

Descrição

Obrigatório

Valor padrão

maxEventCount

Number

Número máximo de reportes de travamentos permitidos por visualização de página (PV).

Valores válidos: [1, 5].

Não

5

renderThreshold

Number

Limiar de tempo para identificar um travamento de setData. Valor mínimo: 50. Unidade: milissegundos.

Não

50

Exemplo

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  longTaskConfig: {
    maxEventCount: 4, // Report stuttering data up to 4 times within a single PV.
    renderThreshold: 100, // A setData operation that takes more than 100 milliseconds is considered a stutter.
  },
});

Parâmetros de collectors

O SDK utiliza collectors, como api e static Resource, para coletar dados de monitoramento de página.

Parâmetro	Tipo	Descrição	Obrigatório	Valor padrão
api	Boolean	Object	Rastreia requisições de API.	Não	true
jsError	Boolean	Object	Rastreia erros de JavaScript.	Não	true
consoleError	Boolean	Object	Rastreia erros lançados por console.error.	Não	true
action	Boolean	Object	Rastreia o comportamento do usuário.	Não	true
longTask	Boolean	Object	Monitora travamentos de página.	Não	true

Exemplo

Desative o listener do comportamento de clique do usuário.

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

Parâmetros de evaluateApi

A função evaluateApi permite analisar eventos de API personalizados, incluindo eventos request e httpRequest.

Parâmetro	Tipo	Descrição
options	Object	Parâmetros da requisição, incluindo url, headers e data. Variam conforme o método de requisição.
response	Object	Corpo da resposta da requisição.
error	Error	Erro ocorrido. Parâmetro opcional, disponível apenas quando a requisição falha.

Esta função aceita chamadas assíncronas e retorna Promise<IApiBaseAttr>. A tabela a seguir descreve IApiBaseAttr.

Parâmetro	Tipo	Descrição	Obrigatório
name	String	Nome da API. Geralmente é uma URL convergida com até 1.000 caracteres. Por exemplo, se a URL for `/list/123`, o parâmetro name convergido será exibido como `/list/$id`. Importante Este parâmetro tem precedência sobre o retorno da função parseResourceName.	Não
message	String	Informações da API. String breve descritiva com no máximo 1.000 caracteres.	Não
success	Number	Indica se a requisição foi bem-sucedida: 1: Sucesso. 0: Falha -1: Desconhecido	Não
duration	Number	Tempo total de resposta da API.	Não
status_code	Number \| String	Código de status.	Não
snapshots	String	Snapshot da API Nota Um snapshot armazena informações sobre reqHeaders, params e resHeaders. É possível personalizar os campos que compõem um snapshot. Snapshots servem principalmente para solucionar exceções. Como não possuem índice, não podem ser usados como condição de filtro para consulta ou agregação. Devem ser strings com até 5.000 caracteres.	Não

Exemplo

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

    // The returned fields will overwrite the default content. If the fields are not returned, the default content is used.
    return {
      name: 'my-custom-api',
      success: error ? 0 : 1,
      snapshots: JSON.stringify({
        params: 'page=1&size=10', // The input parameter.
        response: respText.substring(0, 2000), // The returned value.
        reqHeaders: '', // The request header.
        resHeaders: '' // The response header.
      })
    }
  }
});

Parâmetros de filters

Os parâmetros de filters excluem eventos de recursos e exceções desnecessários.

Parâmetro

Tipo

Descrição

Obrigatório

resource

MatchOption

MatchOption[]

Filtra eventos de recursos coletados, incluindo recursos estáticos e APIs (XMLHttpRequest/fetch).

Não

exception

MatchOption

MatchOption[]

Filtra eventos anômalos coletados.

Não

MatchOption

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

string: corresponde a qualquer URL que comece com o valor especificado. Por exemplo, https://api.alibabacloud.com corresponde a https://api.alibabacloud.com/v1/resource.
RegExp: testa uma URL em relação a uma expressão regular especificada.
function: usa uma função para determinar se uma URL corresponde. Se retornar true, a URL corresponde.

Se a entrada for MatchOption[], as condições acima são avaliadas em ordem. O evento será excluído se qualquer condição for atendida.

Exemplo

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  filters: {
    // Exclude exception events
    exception: [
      'Test error', // Filter error messages starting with 'Test error'.
      /^Script error\.?$/, // Specify a regular expression.
      (msg) => {
        return msg.includes('example-error');
      },
    ],
    // Exclude resource or API events
    resource: [
      'https://example.com/', // Filter resources starting with 'https://example.com/'.
      /localhost/i,
      (url) => {
        return url.includes('example-resource');
      },
    ],
  },
});

Parâmetros de properties

Configure propriedades fornecidas pelo RUM para todos os eventos.

Parâmetro	Tipo	Descrição	Obrigatório
[key: string]	String \| Number	A chave deve ser uma string válida em JSON com no máximo 50 caracteres. O excedente será truncado. Se o valor for uma string, o limite é de 2.000 caracteres. Se o valor não for string nem número, o par chave-valor será removido.	Não

Use evaluateApi, sendCustom, sendException e sendResource para adicionar propriedades a um evento específico.

O sistema mescla propriedades globais e de evento durante o armazenamento. As propriedades de evento têm prioridade sobre as globais e sobrescrevem chaves duplicadas. O limite após a mesclagem é de 20 pares chave-valor. Caso exceda, os pares serão ordenados por chave e os excedentes removidos.

Exemplo

Propriedades configuradas globalmente são anexadas a todos os eventos reportados.

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  properties: {
    prop_string: 'xx',
    prop_number: 2,
    // If the length of the key or value exceeds the limit, the excess part is truncated.
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    more_than_2000_value_limit: new Array(2003).join('1'),
    // The following invalid key-value pairs will be removed.
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

Configuração dinâmica

O RUM suporta entrega dinâmica de configurações de coleta e reporte de dados. O SDK carrega essas configurações ao iniciar a aplicação e sobrescreve item por item as configurações estáticas definidas na inicialização. Esse recurso envolve duas partes: o console e o SDK.

Configuração no console

Primeiro, defina as configurações no console. Acesse Application Settings > SDK Configuration. Após concluir e testar, clique em Confirm and Update Dynamic Configuration. Essa ação envia a configuração para um endpoint remoto do OSS para armazenamento.

Configuração do SDK

Para habilitar a entrega de configuração dinâmica, adicione o campo remoteConfig à inicialização do SDK. Durante a inicialização, o SDK usa esse campo para recuperar a configuração remota do OSS e atualiza recursos como probes e reporte.

import ArmsRum from '@arms/rum-miniapp';

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  remoteConfig: {
    // The region where the web application is located, for example, ap-southeast-1 for Singapore.
    region: "cn-hangzhou"
  }
});

Após recuperar a configuração remota, o SDK atualiza imediatamente os recursos e armazena a configuração no cache local. Assim, o SDK prioriza a configuração em cache local na próxima inicialização.

A versão do SDK deve ser 0.0.37 ou posterior.

Outras configurações

O SDK do RUM permite configurar propriedades comuns resolvidas com base em endereços IP e UserAgent. Parâmetros configurados manualmente têm prioridade sobre os resolvidos automaticamente.

Parâmetro

Tipo

Descrição

Obrigatório

device

Object

Informações do dispositivo.

Não

os

Object

Informações do sistema e do contêiner.

Não

geo

Object

Áreas administrativas

Não

isp

Object

Informações do ISP.

Não

net

Object

Informações de rede.

Não

Para mais informações sobre itens de configuração relacionados aos parâmetros acima, consulte Common attributes.

Exemplo

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

API do SDK

O SDK fornece APIs para modificar e reportar dados personalizados, além de alterar dinamicamente as configurações do SDK.

getConfig

Obtenha as configurações atuais do SDK.

setConfig

Modifique a configuração do SDK.

// Set a specific key
ArmsRum.setConfig('env', 'pre');

// Overwrite the following settings
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
  ...config,
  version: '1.0.0',
  env: 'pre',
});

sendCustom

Para reportar dados personalizados, especifique os parâmetros type e name. A tabela a seguir descreve os parâmetros de reporte. Defina a semântica de negócios conforme necessário.

Parâmetro	Tipo	Descrição	Obrigatório
type	String	Tipo do evento.	Sim
name	String	Nome do evento.	Sim
group	String	Grupo do evento.	Não
value	Number	Valor numérico associado.	Não
properties	object	Propriedades personalizadas.	Não

ArmsRum.sendCustom({
  // Required
  type: 'CustomEvnetType1',
  name: 'customEventName2',
  // Optional
  group: 'customEventGroup3',
  value: 111.11,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendException

Para reportar exceções personalizadas, especifique os parâmetros name e message.

Parâmetro	Tipo	Descrição	Obrigatório
name	String	Nome da exceção.	Sim
message	String	Informações da exceção.	Sim
file	String	Arquivo onde a exceção ocorreu.	Não
stack	String	Stack trace da exceção.	Não
line	Number	Linha onde a exceção ocorreu.	Não
column	Number	Coluna onde a exceção ocorreu.	Não
properties	object	Propriedades personalizadas.	Não

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

sendResource

Para reportar dados de recursos personalizados, especifique os parâmetros name, type e duration.

Parâmetro	Tipo	Descrição	Obrigatório
name	String	Nome do recurso.	Sim
type	String	Tipo de recurso (ex.: script, api, image ou other).	Sim
duration	String	Tempo consumido pela requisição.	Sim
success	Number	Indica se a requisição foi bem-sucedida: 1: Sucesso 0: Falha -1: Desconhecido	Não
method	String	Método de requisição.	Não
status_code	Number \| String	Código de status da requisição.	Não
message	String	Mensagem da requisição.	Não
url	String	Endereço da requisição.	Não
trace_id	String	ID de rastreamento.	Não
properties	object	Propriedades personalizadas.	Não

ArmsRum.sendResource({

  // The following are required.
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  // The following are optional.
  url: 'https://www.aliyun.com/data/getListByPage',
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});