Application Real-Time Monitoring Service:Referensi konfigurasi SDK RUM untuk web dan HTML5

Inisialisasi CDN

Saat memuat SDK melalui Alibaba Cloud Content Delivery Network (CDN), akses SDK dari namespace global RumSDK.default:

const ArmsRum = window.RumSDK.default;

// Inisialisasi SDK setelah SDK dimuat.
// Lewati langkah ini jika Anda telah menetapkan window.__rum sebelum tag skrip SDK.
ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
});

// Perbarui konfigurasi saat runtime
ArmsRum.setConfig('env', 'pre');

Inisialisasi npm

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

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

Contoh

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

Contoh

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  reportConfig: {
    flushTime: 0,       // Laporkan langsung
    maxEventCount: 50,  // Maksimal 50 event per batch
  },
});

Detail penyimpanan

Parameter storage menentukan tempat SDK menyimpan data berikut:

• _arms_uid — ID pengguna unik (user.id)

• _arms_session — metadata sesi dalam format ${sessionId}-${sampled}-${startTime}-${lastTime}:

  • sessionId — identifier sesi unik

  • sampled — apakah sesi ini dipilih melalui sampling

  • startTime — timestamp mulai sesi

  • lastTime — timestamp aktivitas terakhir

Contoh

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  sessionConfig: {
    sampleRate: 0.5,          // Sampling 50% sesi
    maxDuration: 86400000,    // Maksimal 24 jam
    overtime: 3600000,        // Timeout ketidakaktifan 1 jam
    storage: 'cookie',        // Gunakan cookie alih-alih localStorage
  },
});

Contoh

Nonaktifkan pelacakan interaksi pengguna:

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

Argumen input

Tipe kembalian (IApiBaseAttr)

Bidang yang dikembalikan menggantikan nilai default SDK. Bidang yang dihilangkan tetap menggunakan nilai default-nya.

Contoh

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  evaluateApi: async (options, response, error) => {
    let respText = '';
    if (response && response.text) {
      respText = await response.text();
    }

    return {
      name: 'my-custom-api',
      success: error ? 0 : 1,
      snapshots: JSON.stringify({
        params: 'page=1&size=10',
        response: respText.substring(0, 2000),
        reqHeaders: '',
        resHeaders: '',
      }),
      properties: {
        prop_msg: 'custom msg',
        prop_num: 1,
      },
    };
  },
});

Tipe MatchOption

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

• String — mencocokkan URL atau pesan apa pun yang diawali dengan nilai yang ditentukan. Misalnya, 'https://api.aliyun.com' cocok dengan 'https://api.aliyun.com/v1/resource'.

• RegExp — mencocokkan URL atau pesan terhadap ekspresi reguler.

• Function — menerima URL atau pesan sebagai input. Kembalikan true untuk mengecualikan event tersebut.

Saat Anda memberikan array nilai MatchOption, kondisi dievaluasi berurutan. Suatu event dikecualikan jika salah satu kondisi cocok.

Contoh

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  filters: {
    exception: [
      'Test error',                           // Pesan yang diawali dengan 'Test error'
      /^Script error\.?$/,                    // Pesan yang cocok dengan regex ini
      (msg) => msg.includes('example-error'), // Fungsi pencocokan kustom
    ],
    resource: [
      'https://example.com/',   // URL yang diawali dengan 'https://example.com/'
      /localhost/i,             // URL yang mengandung 'localhost'
      (url) => url.includes('example-resource'),
    ],
  },
});

DetectionRule

Event pemicu

Metode deteksi

Tipe CustomTesterResult:

type CustomTesterResult = {
  hasContent: boolean;               // true = konten ada; false = terdeteksi layar putih
  message?: string;                  // Pesan error
  snapshot?: Record<string, any>;    // Data diagnostik
}

ConfigOptions

Opsi khusus untuk metode deteksi SCREENSHOT dan SAMPLE.

Opsi SCREENSHOT:

Opsi SAMPLE:

Opsi bersama:

Kedua metode SCREENSHOT dan SAMPLE mendukung opsi debug (Boolean, default: false). Saat diaktifkan, detail deteksi dicetak ke konsol developer tools browser.

Contoh

Deteksi berbasis tangkapan layar:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SCREENSHOT',
      configOptions: {
        colorRange: ['rgb(255, 255, 255)', 'rgb(0, 0, 0)'],
        threshold: 0.9,
        pixels: 10,
        horizontalOffset: 210,
        verticalOffset: 50,
      },
    }],
  },
});

Deteksi berbasis sampling:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SAMPLE',
      configOptions: {
        sampleMethod: 2,
        checkPoints: 10,
        threshold: 0.9,
        whiteBoxElements: ['.el-skeleton'],
      },
    }],
  },
});

Fungsi deteksi kustom:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: async (element) => {
        return {
          hasContent: false,
          message: 'Custom error message',
          snapshot: {
            checkPoints: 100,
            rate: 0.99,
            checkdata: '......',
          },
        };
      },
    }],
  },
});

Perilaku penggabungan

• Properti global (diatur di init()) dan properti tingkat event (diatur melalui evaluateApi, sendCustom, sendException, atau sendResource) digabung saat penyimpanan.

• Properti tingkat event memiliki prioritas lebih tinggi. Jika kunci yang sama ada di kedua tempat, nilai tingkat event yang digunakan.

• Setelah penggabungan, maksimal 20 pasangan kunci-nilai disimpan. Pasangan berlebih diurutkan berdasarkan kunci dan dihapus.

Contoh

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  properties: {
    prop_string: 'xx',
    prop_number: 2,
    // Kunci lebih dari 50 karakter dipotong
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    // Nilai string lebih dari 2.000 karakter dipotong
    more_than_2000_value_limit: new Array(2003).join('1'),
    // Tipe tidak valid -- pasangan ini dihapus
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

Langkah 1: Konfigurasikan di konsol ARMS

1. Buka Application List dan buka aplikasi Anda.

2. Buka Application Settings > SDK config.

3. Tetapkan nilai konfigurasi yang diinginkan.

4. Klik Confirm Update Dynamic Configuration untuk mendorong pengaturan ke server Object Storage Service (OSS) jarak jauh.

Langkah 2: Aktifkan di SDK

Tambahkan bidang remoteConfig ke kode inisialisasi Anda dengan region tempat aplikasi Anda di-hosting.

CDN:

window.__rum = {
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  remoteConfig: {
    region: "cn-hangzhou"  // Contoh: "ap-southeast-1" untuk Singapura
  }
};

<script async src="https://xxid-sdk.rum.aliyuncs.com/v2/browser-sdk.js"></script>

npm:

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

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  remoteConfig: {
    region: "cn-hangzhou"  // Contoh: "ap-southeast-1" untuk Singapura
  }
});

Perilaku caching

Setelah mengambil konfigurasi jarak jauh, SDK menyimpan pengaturan tersebut secara lokal. Pada inisialisasi berikutnya, SDK memprioritaskan konfigurasi yang di-cache.

Konfigurasi dinamis memerlukan versi SDK 0.0.37 atau lebih baru saat mengimpor melalui CDN dengan versi yang ditentukan.

Contoh

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

getConfig

Ambil konfigurasi SDK saat ini:

const config = ArmsRum.getConfig();

setConfig

Perbarui konfigurasi SDK saat runtime. Teruskan pasangan kunci-nilai tunggal atau objek konfigurasi lengkap:

// Tetapkan nilai tunggal
ArmsRum.setConfig('env', 'pre');

// Tetapkan beberapa nilai
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
  ...config,
  version: '1.0.0',
  env: 'pre',
});

sendCustom

Laporkan event kustom. Bidang type dan name wajib diisi.

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

sendException

Laporkan exception kustom. Bidang name dan message wajib diisi.

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

sendResource

Laporkan event resource kustom. Bidang name, type, dan duration wajib diisi.

ArmsRum.sendResource({
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  url: 'https://www.aliyun.com/data/getListByPage',
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});