Application Real-Time Monitoring Service:Referência do SDK

Métodos neste tópico

pid | uid | tag | page | setUsername | enableSPA | parseHash | disableHook | ignoreUrlCase | urlHelper | apiHelper | parseResponse | ignore | disabled | sample | pvSample | sendResource | useFmp | enableLinkTrace | release | environment | behavior | c1\c2\c3 | autoSendPerf

Usar itens de configuração do SDK

Use os itens de configuração do SDK por meio de um dos seguintes métodos:

• Ao instalar um agente do Browser Monitoring em uma página, adicione parâmetros ao config conforme suas necessidades.

  Por exemplo, no código de amostra a seguir, além do parâmetro padrão pid, o parâmetro enableSPA para aplicações de página única (SPAs) foi adicionado ao config:

  <script>
  !(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxxxxx",enableSPA:true};
  with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
  })(window,document,"https://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
  </script>                    

• Após a inicialização da página, chame o método setConfig no código JavaScript para modificar os itens de configuração.

  O método __bl.setConfig(next) aceita o seguinte parâmetro:

  Parâmetro	Tipo	Descrição	Obrigatório	Valor padrão
  next	Object	O item de configuração e seu valor que você deseja modificar.	Sim	Nenhum

pid

[[Back to Top]](#sc_index)

uid

O código a seguir exemplifica como chamar o método setConfig para modificar o item de configuração do SDK:

__bl.setConfig({
    uid: 12345
});        

[[Back to Top]](#sc_index)

tag

[[Back to Top]](#sc_index)

page

[[Back to Top]](#sc_index)

setUsername

Este item de configuração cria uma função responsável por obter o nome de usuário como uma string. Após obter o nome de usuário, é possível implementar rastreamento de sessão ponta a ponta e consultar sessões com base nesse nome para solucionar problemas.

O código a seguir exemplifica como chamar o método setConfig para modificar o item de configuração do SDK:

__bl.setConfig({
    setUsername: function () {
        return "username_xxx";
    }
});            

[[Back to Top]](#sc_index)

enableSPA

[[Back to Top]](#sc_index)

parseHash

Em cenários de aplicação de página única (SPA) (consulte SPA page data reporting), se enableSPA estiver definido como true, o parâmetro parseHash analisa o hash da URL e o converte no campo Page quando ocorre um evento hashchange.

Default value

O valor padrão é obtido através do seguinte método de processamento de string:

function (hash) {
    var page = hash ? hash.replace(/^#/, '').replace(/\?.*$/, '') : '';
    return page || '[index]';
}           

Geralmente, não é necessário modificar este parâmetro. No entanto, caso deseje usar um nome de página personalizado para reportar dados específicos ou se o hash da URL for complexo, modifique este item de configuração. Exemplo:

// Define the mapping between URL hashes and page names.
var PAGE_MAP = {
    '/': 'homepage',
    '/contact': 'contact us',
    '/list': 'data list',
    // ...
};
// Call the SDK method after the page is loaded.
window.addEventListener('load', function (e) {
    // Call the setConfig method to modify the SDK configuration item.
    __bl.setConfig({
        parseHash: function (hash) {
            key = hash.replace(/\?.*$/, '');
            return PAGE_MAP[key] || 'unknown page';
        }
    });
});

[[Back to Top]](#sc_index)

disableHook

[[Back to Top]](#sc_index)

ignoreUrlCase

[[Back to Top]](#sc_index)

urlHelper

Quando a URL de uma página é semelhante a http://example.com/projects/123456 (onde o número após projects é o ID do projeto), reportar example.com/projects/123456 como página impede o agrupamento correto dos dados. Nesse caso, para garantir que páginas semelhantes sejam agrupadas, use o parâmetro urlHelper para filtrar caracteres não críticos, como o ID do projeto neste exemplo.

Default value

O valor padrão deste item de configuração é o array mostrado no código de amostra a seguir. Na maioria dos casos, não é necessário modificar esse valor:

[
    // Replace all digits in the path with asterisks (*).
    {rule: /\/([a-z\-_]+)?\d{2,20}/g, target: '/$1**'},
    // Remove a trailing slash (/) from the URL.
    /\/$/
]                    

Por padrão, esta configuração substitui identificadores numéricos que seguem um segmento de caminho. Por exemplo, tanto xxxx/00001 quanto xxxx/00002 tornam-se xxxx/**, assim como aconteceria com uma URL original como xxxx/123456.

Value types

O valor do parâmetro urlHelper pode ser dos seguintes tipos:

• String ou RegExp (expressão regular): Remove a parte correspondente da string da URL.

• Object<rule, target>: Um objeto com as chaves rule e target. Estes são passados como argumentos para o método JavaScript String.prototype.replace(). Para detalhes, consulte a documentação do String.prototype.replace().

• Function: Uma função que recebe a string original da URL como argumento. Seu valor de retorno é usado como o valor final da página.

• Array: Um array contendo múltiplas regras, onde cada regra pode ser qualquer um dos tipos descritos acima.

[[Back to Top]](#sc_index)

apiHelper

Este parâmetro remove caracteres não essenciais nas URLs ao reportar automaticamente dados específicos de operações de API. O uso e a função deste parâmetro são idênticos aos descritos em urlHelper.

Default value

O valor padrão deste parâmetro é um objeto e não precisa ser modificado:

{rule: /(\w+)\/\d{2,}/g, target: '$1'}                    

Esta configuração padrão filtra números finais nos caminhos de URL da API, como em xxxx/123456.

Se precisar reportar parâmetros da query string (a parte da URL da API após o ?), como o parâmetro pid em https://arms.console.alibabacloud.com/apm?pid=fr6fbgbeot, use o reporte manual:

• Chame o método ignore para desativar o reporte automático de dados. Para mais informações, consulte ignore.

• Chame o método api() para reportar manualmente os dados específicos da página sobre operações de API. Para mais informações, consulte api().

[[Back to Top]](#sc_index)

parseResponse

Este item de configuração analisa os dados retornados quando o sistema reporta automaticamente dados específicos de operações de API.

Default value

O código de amostra a seguir mostra as configurações padrão:

function (res) {
    if (!res || typeof res !== 'object') return {};
    var code = res.code;
    var msg = res.msg || res.message || res.subMsg || res.errorMsg || res.ret || res.errorResponse || '';
    if (typeof msg === 'object') {
        code = code || msg.code;
        msg = msg.msg || msg.message || msg.info || msg.ret || JSON.stringify(msg);
    }
    return {msg: msg, code: code, success: true};
}                    

A função padrão analisa a resposta para extrair as propriedades msg e code. Embora essa função atenda à maioria das aplicações, substitua-a caso não satisfaça seus requisitos de negócio.

[[Back to Top]](#sc_index)

ignore

O valor do parâmetro ignore é um objeto que contém quatro propriedades: ignoreUrls, ignoreApis, ignoreErrors e ignoreResErrors. Defina uma ou mais propriedades do valor do parâmetro.

Default value

O código de amostra a seguir mostra as configurações padrão:

ignore: {
        ignoreUrls: [],
        ignoreApis: [],
        ignoreErrors: [],
        ignoreResErrors: []
    },                    

ignoreUrls

A propriedade ignoreUrls especifica quais URLs ignorar. Logs provenientes de URLs que correspondem a um padrão definido não são reportados. O valor pode ser uma string, regular expression, function ou um array contendo esses tipos. Exemplo:

__bl.setConfig({
                ignore: {
                    ignoreUrls: [
                    'http://host1/',  // string
                    /.+?host2.+/,     // regular expression
                    function(str) {   // function
                        if (str && str.indexOf('host3') >= 0) {
                            return true;   // Do not report
                        }
                        return false;      // Report
                    }]
                }
            });                    

ignoreApis

A propriedade ignoreApis especifica quais APIs ignorar. Chamadas para APIs que correspondem a um padrão definido não são monitoradas. O valor pode ser uma string, regular expression, function ou um array contendo esses tipos. Exemplo:

__bl.setConfig({
                ignore: {
                    ignoreApis: [
                    'api1','api2','api3', // string
                    /^random/,  // regular expression
                    function(str) { // function
                        if (str && str.indexOf('api3') >= 0) return true;   // Do not report
                        return false;   // Report
                    }]
                }
            });                    

ignoreErrors

A propriedade ignoreErrors especifica quais erros JS ignorar. Erros JS que correspondem a um padrão definido não são reportados. O valor pode ser uma string, regular expression, function ou um array contendo esses tipos. Exemplo:

__bl.setConfig({
                ignore: {
                    ignoreErrors: [
                    'test error', // string
                    /^Script error\.?$/, // regular expression
                    function(str) { // function
                        if (str && str.indexOf('Unknown error') >= 0) return true;   // Do not report
                        return false;   // Report
                    }]
                }
            });            

ignoreResErrors

A propriedade ignoreResErrors especifica quais erros de recurso ignorar. Erros de recurso que correspondem a um padrão definido não são reportados. O valor pode ser uma string, regular expression, function ou um array contendo esses tipos. Exemplo:

__bl.setConfig({
                ignore: {
                    ignoreResErrors: [
                    'http://xx/picture.jpg', // string
                    /jpg$/, // regular expression
                    function(str) { // function
                        if (str && str.indexOf('xx.jpg') >= 0) return true;   // Do not report
                        return false;   // Report
                    }]
                }
            });

[[Back to Top]](#sc_index)

disabled

[[Back to Top]](#sc_index)

sample

Benefícios:

• Reduz custos ao reportar apenas dados de API amostrados. Recomendamos identificar os dados que não exigem monitoramento configurando o parâmetro ignore. Para mais informações, consulte ignore.

• Diminui a sobrecarga de desempenho na coleta de dados.

Descrição:

• Configure este item para selecionar e reportar aleatoriamente logs de desempenho e logs de operações de API bem-sucedidas. Isso reduz o volume de dados reportados e a carga de trabalho. Quando o ARMS processa os logs reportados em segundo plano, ele restaura os dados com base nas configurações de amostragem. Dessa forma, métricas como taxa de erro JS ou taxa de falha de API permanecem precisas e não sofrem impacto da amostragem. No entanto, ao definir este parâmetro, talvez não seja possível obter dados detalhados, como os detalhes da API.

• O valor padrão de sample é 1. Valores válidos são inteiros de 1 a 100. A taxa de amostragem é 1/sample. Por exemplo, 1 significa 100% de amostragem, 10 significa 10% de amostragem e 100 significa 1% de amostragem.

[[Back to Top]](#sc_index)

pvSample

Benefícios:

• Reduz custos ao reportar apenas dados de PV amostrados.

• Diminui a sobrecarga de desempenho na coleta de dados.

Descrição:

• Configure este item para selecionar e reportar aleatoriamente logs de PV. Isso reduz o volume de dados reportados e a carga de trabalho. Quando o ARMS processa os logs reportados em segundo plano, ele restaura os dados com base nas configurações de amostragem. Assim, métricas como a taxa de erro JS permanecem precisas e não sofrem impacto da amostragem.

• O valor padrão de pvSample é 1. A taxa de amostragem é 1/pvSample. Por exemplo, um valor de 1 significa 100% de amostragem, 10 significa 10% de amostragem e 100 significa 1% de amostragem.

[[Back to Top]](#sc_index)

sendResource

Se o parâmetro sendResource estiver definido como true, os recursos estáticos da página serão reportados quando o evento load da página for acionado. Se uma página carregar lentamente, visualize seu gráfico de cascata de recursos estáticos na página Session Traces para identificar a causa.

O código a seguir exemplifica como definir o parâmetro sendResource:

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxxxxx",sendResource:true};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
</script>            

[[Back to Top]](#sc_index)

useFmp

[[Back to Top]](#sc_index)

enableLinkTrace

[[Back to Top]](#sc_index)

release

[[Back to Top]](#sc_index)

environment

[[Back to Top]](#sc_index)

behavior

[[Back to Top]](#sc_index)

autoSendPerf

[[Back to Top]](#sc_index)

c1\c2\c3

Além dos itens de configuração anteriores, o SDK do ARMS fornece três itens personalizados para que você configure campos conforme seus requisitos de negócio. Após configurar esses campos, seus valores serão incluídos em todos os logs reportados.

[[Back to Top]](#sc_index)