Application Real-Time Monitoring Service：SDK參考

本頁索引

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

如何使用前端監控SDK配置項

可通過以下兩種方式使用前端監控SDK配置項：

• 向頁面插入BI探針時在config中添加額外參數。

  例如，以下範例程式碼的config中，除了預設的pid參數外，還添加了用於單頁面應用（Single Page Application）情境的enableSPA參數。

  <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://retcode.alicdn.com/retcode/bl.js","__bl");
  </script>                    

• 頁面初始化完成後，在前端JS代碼中調用setConfig方法來修改配置項。

  __bl.setConfig(next)調用參數說明：

  參數	類型	描述	是否必選	預設值
  next	Object	需要修改的配置項以及值	是	無

pid

[回到頂部]

uid

樣本：調用setConfig方法修改SDK配置項。

__bl.setConfig({
    uid: 12345
});        

[回到頂部]

tag

[回到頂部]

page

[回到頂部]

setUsername

本配置項用於設定一個方法，該方法需要傳回型別為String的使用者名稱稱。配置後可以根據使用者名稱稱進行全鏈路追蹤（會話追蹤）、查詢使用者會話軌跡，便於排查問題。

樣本：調用setConfig方法修改SDK配置項。

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

[回到頂部]

enableSPA

[回到頂部]

parseHash

單頁面應用情境中（參見SPA頁面上報），在enableSPA設為true的前提下，頁面觸發hashchange事件時，parseHash參數用於將URL Hash解析為Page欄位。

預設值

其預設值由一個簡單的字串處理方法獲得：

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

此項一般情況下不需要修改。如果需要在上報時使用自訂的頁面名，或者URL的Hash比較複雜，則需要修改此配置項。例如：

// 定義頁面Hash和Page的映射關係。
var PAGE_MAP = {
    '/': '首頁',
    '/contact': '聯絡我們',
    '/list': '資料列表',
    // ...
};
// 頁面load後調用SDK方法。
window.addEventListener('load', function (e) {
    // 調用setConfig方法修改SDK配置項。
    __bl.setConfig({
        parseHash: function (hash) {
            key = hash.replace(/\?.*$/, '');
            return PAGE_MAP[key] || '未知頁面';
        }
    });
});

[回到頂部]

disableHook

[回到頂部]

ignoreUrlCase

[回到頂部]

urlHelper

當頁面URL類似於http://example.com/projects/123456（projects後面的數字是專案ID）時，如果將example.com/projects/123456作為page上報，會導致在資料查看時頁面無法聚成一類。這種情況下，為了使同類頁面聚類，可以使用urlHelper參數過濾掉非關鍵字符，例如此例中的專案ID。

預設值

此配置項的預設值是以下數組，一般情況下不需要修改。

[
    // 將所有Path中的數字變成*。
    {rule: /\/([a-z\-_]+)?\d{2,20}/g, target: '/$1**'},
    // 去掉URL末尾的'/'。
    /\/$/
]                    

此設定項的預設值會過濾掉xxxx/123456後面的數字，例如xxxx/00001和xxxx/00002都會變成xxxx/**。

實值型別

urlHelper的值可以是以下類型：

• String或RegExp（Regex）：將匹配到的字串去掉。

• Object<rule, target>：對象包含兩個Key（rule和target）作為JS字串的replace方法的入參。使用方法參見JS相關教程中的String::replace方法。

• Function：將原字串作為入參執行方法，將執行結果作為Page。

• Array：用於設定多條規則，每條規則都可以是上述類型之一。

[回到頂部]

apiHelper

用於在自動上報API時過濾介面URL中的非關鍵字符，用法及含義同urlHelper。

預設值

預設值是一個對象，一般情況下不需要修改：

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

此設定項的預設值會過濾掉介面URL中類似xxxx/123456後面的數字。

如果需要在API中上報?後面的參數，例如：https://arms.console.aliyun.com/apm?pid=fr6fbgbeot中的pid參數，需要按照以下方法手動上報API資料：

• 使用ignore方法，關閉自動上報。具體操作，請參見ignore。

• 使用api()自行上報API資料。具體操作，請參見api()。

[回到頂部]

parseResponse

該配置項用於解析自動上報API時返回的資料。

預設值

該配置項的預設值為：

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};
}                    

以上代碼會解析返回的資料，嘗試提取出msg和code。對於一般應用來說，此設定項不需要修改。如果預設值無法滿足業務需求，則可以重新設定。

[回到頂部]

ignore

ignore的值是一個對象，對象中包含4個屬性：ignoreUrls、ignoreApis、ignoreErrors和ignoreResErrors。可單獨設定其中的1個或多個屬性。

預設值

該配置項的預設值為：

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

ignoreUrls

ignoreUrls表示忽略某些URL，符合規則的URL下的日誌都不會被上報。值可以是String、RegExp、Function或者以上三種類型組成的數組。樣本：

__bl.setConfig({
                ignore: {
                    ignoreUrls: [
                    'http://host1/',  // 字串
                    /.+?host2.+/,     // Regex
                    function(str) {   // 方法
                        if (str && str.indexOf('host3') >= 0) {
                            return true;   // 不上報
                        }
                        return false;      // 上報
                    }]
                }
            });                    

ignoreApis

ignoreApis表示忽略某些API，符合規則的API將不會被監控。值可以是String、RegExp、Function或者以上三種類型組成的數組。樣本：

__bl.setConfig({
                ignore: {
                    ignoreApis: [
                    'api1','api2','api3', // 字串
                    /^random/,  // Regex
                    function(str) { // 方法
                        if (str && str.indexOf('api3') >= 0) return true;   // 不上報
                        return false;   // 上報
                    }]
                }
            });                    

ignoreErrors

ignoreErrors表示忽略某些JS錯誤，符合規則的JS錯誤不會被上報。值可以是String、RegExp、Function或者以上三種類型組成的數組。樣本：

__bl.setConfig({
                ignore: {
                    ignoreErrors: [
                    'test error', // 字串
                    /^Script error\.?$/, // Regex
                    function(str) { // 方法
                        if (str && str.indexOf('Unknown error') >= 0) return true;   // 不上報
                        return false;   // 上報
                    }]
                }
            });            

ignoreResErrors

ignoreResErrors表示忽略指定的資源錯誤，符合規則的資源錯誤不會被上報。值可以是String、RegExp、Function或者以上三種類型組成的數組。樣本：

__bl.setConfig({
                ignore: {
                    ignoreResErrors: [
                    'http://xx/picture.jpg', // 字串
                    /jpg$/, // Regex
                    function(str) { // 方法
                        if (str && str.indexOf('xx.jpg') >= 0) return true;   // 不上報
                        return false;   // 上報
                    }]
                }
            });

[回到頂部]

disabled

[回到頂部]

sample

sample配置項作用：

• 減小API的資料上報量（降低部分費用），更精確的方案建議使用ignore參數過濾掉某些不需要監控的API資料，更多資訊，請參考ignore。

• 降低採集資料的效能開銷。

sample配置項說明：

• 為了減小上報量和降低負載，該配置項會對效能和成功API日誌進行隨機採樣上報，幕後處理日誌時會根據對應的採樣配置進行還原，因此不會影響JS錯誤率和失敗API率等指標的計算。但是會導致在查詢API詳情或者相關資料明細的時候，無法保證一定可以查看明細。

• 採樣值sample預設為1，值可以是1~100的整數，對應的採樣率為1/sample，例如：1表示100%採樣，10表示10%採樣，100表示1%採樣。

[回到頂部]

pvSample

pvSample配置項作用：

• 減小PV的資料上報量（降低部分費用）。

• 降低採集資料的效能開銷。

pvSample配置項說明：

• 為了減小上報量和降低負載，該配置項會對PV日誌進行隨機採樣上報，幕後處理日誌時會根據對應的採樣配置進行還原，樣本量足夠大的情況下對JS錯誤率等指標的計算影響不大。

• 採樣值pvSample預設為1，值可以是1~100的整數，對應的採樣率為1/pvSample，例如：1表示100%採樣，10表示10%採樣，100表示1%採樣。

[回到頂部]

sendResource

如果sendResource配置為true，則頁面load事件觸發時會上報當前頁面載入的靜態資源資訊。如果發現頁面載入較慢，可以在會話追蹤頁面查看頁面載入的靜態資源瀑布圖，判斷頁面載入較慢的具體原因。

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://retcode.alicdn.com/retcode/bl.js","__bl");
</script>            

[回到頂部]

useFmp

[回到頂部]

enableLinkTrace

[回到頂部]

release

[回到頂部]

environment

[回到頂部]

behavior

[回到頂部]

autoSendPerf

[回到頂部]

c1\c2\c3

除了以上列出的配置項，您可能還需要更多的附加資訊輔助處理業務問題，因此ARMS SDK提供了3個可自訂欄位的配置項，配置後欄位內容會包含在每一條上報的日誌中。

[回到頂部]