@arms/rum-core 0.1.4 → 0.1.6

package/README.md

@@ -1,3 +1,27 @@
-## @arms/rum-core
+# @arms/rum-core
 
-Core 为 SDK 上报提供核心流程角色抽象
+ARMS RUM SDK 多端方案的核心抽象层，为各平台 shell（`browser` / `uniapp` / `miniapp` / `minigame` / `electron` / `reactnative` 等）提供统一的角色模型、事件协议与跨运行时工具。
+
+## 角色模型
+
+- **Client**：装载并编排 `Collector` / `Processor` / `Reporter`，串联事件管线。
+- **Context**：运行时上下文，承载 `config` / `session` / `views` / `emitter`。
+- **Shell**：对外 API 入口，提供 `sendCustom` / `sendView` / `sendException` / `sendResource`。
+- **ConfigManager**：本地+远端配置编排，支持 `launch-first` / `remote-first` 两种模式。
+- **Collector / Processor / Reporter**：平台扩展点，分别负责数据采集、加工、上报。
+
+事件流：`Collector → sendEvent → Processor 链 → Reporter（队列 / 合并 / 重试） → Transport`。
+
+## 支持运行时
+
+浏览器（ES2017+，不含 IE）、Node.js 16+、Deno、Bun、Electron、React Native 0.68+、微信/支付宝/字节小程序（基础库 2.10+ 同等能力）、uni-app 3.x。
+
+`core` 自身不依赖任何浏览器或 Node 专属 API（`window` / `document` / `fetch` / `localStorage` / `XMLHttpRequest` 等）；host API 通过 `env/` 抽象由 shell 注入。
+
+
+## 开发
+
+```bash
+npm run build    # 产出 lib/ (CJS) + es/ (ESM)
+npm test         # 单元测试（先 build 后 test，重构后改为直接跑 ts 源码）
+```

package/es/index.d.ts

@@ -19,4 +19,5 @@ export * from './utils/trace';
 export * from './utils/verify';
 export * from './utils/url';
 export * from './utils/events';
+export * from './monitor';
 export { Client, Context, Reporter, Shell };

package/es/index.js

@@ -19,4 +19,5 @@ export * from './utils/trace';
 export * from './utils/verify';
 export * from './utils/url';
 export * from './utils/events';
+export * from './monitor';
 export { Client, Context, Reporter, Shell };

package/es/model/client.d.ts

@@ -4,13 +4,14 @@ import { RumEvent } from '../types/rum-event';
 import { IProcessor } from '../types/processor';
 import { ICollector } from '../types/collector';
 import { IReporter } from '../types/reporter';
+import { IMonitorReporter } from '../monitor/types';
 declare class Client implements IClient {
     private emitter;
     private collectors;
     private processors;
     private reporter;
     private ctx;
-    init(config: IConfiguration, rumSession?: IRumSession, configManager?: IConfigManager): void;
+    init(config: IConfiguration, rumSession?: IRumSession, configManager?: IConfigManager, monitorReporter?: IMonitorReporter): void;
     sendEvent: (payload: RumEvent) => void;
     setContext(ctx: IContext): void;
     getContext(): IContext;

package/es/model/client.js

@@ -3,6 +3,7 @@ function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r)
 function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
 import { EventType } from '../types/client';
 import { EventEmitter } from '../utils/events';
+import { Telemetry } from '../monitor/telemetry';
 import Context from './context';
 import { isFunction } from "../utils/is";
 var Client = /*#__PURE__*/function () {
@@ -18,9 +19,34 @@ var Client = /*#__PURE__*/function () {
     };
   }
   var _proto = Client.prototype;
-  _proto.init = function init(config, rumSession, configManager) {
+  _proto.init = function init(config, rumSession, configManager, monitorReporter) {
     var _this2 = this;
     this.ctx = new Context(config, rumSession, configManager);
+
+    // Telemetry 初始化 —— 统一在 Core 中完成，各平台仅需传入 reporter
+    if (monitorReporter) {
+      var telemetryConfig = {
+        appType: (rumSession === null || rumSession === void 0 ? void 0 : rumSession.appType) || '',
+        sdkVersion: (rumSession === null || rumSession === void 0 ? void 0 : rumSession.sdkVersion) || '',
+        endpoint: config.endpoint,
+        getSessionId: rumSession ? function () {
+          return rumSession.getSessionId();
+        } : undefined,
+        getSessionSampled: rumSession ? function () {
+          return rumSession.getSampled();
+        } : undefined,
+        getViewId: function getViewId() {
+          var _this2$ctx;
+          var views = (_this2$ctx = _this2.ctx) === null || _this2$ctx === void 0 ? void 0 : _this2$ctx.getViews();
+          return views && views.length ? views[views.length - 1].id : undefined;
+        },
+        selfMonitor: config.selfMonitor
+      };
+      if (config.pid) {
+        telemetryConfig['app.id'] = config.pid;
+      }
+      Telemetry.init(telemetryConfig, monitorReporter);
+    }
     var ctx = this.ctx,
       collectors = this.collectors,
       processors = this.processors,

package/es/model/configManager.js

@@ -101,7 +101,7 @@ export var ConfigManager = /*#__PURE__*/function () {
    * 获取配置
    * @returns 配置数据
    */
-  ;
+;
   _proto.getConfig = function getConfig() {
     if (!this.currentConfig) {
       throw new Error('Config not initialized');
@@ -143,7 +143,7 @@ export var ConfigManager = /*#__PURE__*/function () {
    * @param cachedData 缓存数据
    * @param cacheTimeout 缓存超时时间
    */
-  ;
+;
   _proto.isCacheValid = function isCacheValid(cachedData, cacheTimeout) {
     if (!cachedData || !cachedData.timestamp) {
       return false;

package/es/model/reporter.js

@@ -1,6 +1,7 @@
 import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
 import _extends from "@babel/runtime/helpers/extends";
 import _regeneratorRuntime from "@babel/runtime/regenerator";
+import { logger } from '../monitor/logger';
 import { RumEventType } from '../types/rum-event';
 import { getErrorID } from '../utils/exception';
 import { isNumber, isObject, isString } from "../utils/is";
@@ -217,6 +218,8 @@ var Reporter = /*#__PURE__*/function () {
               setTimeout(function () {
                 return _this2.tryRequest(bundle, retry + 1);
               }, retryDelay);
+            } else {
+              logger.error('reporter', "Request failed after " + (retry + 1) + " attempts", _t);
             }
           case 4:
           case "end":
@@ -232,7 +235,7 @@ var Reporter = /*#__PURE__*/function () {
   /**
    * 接口请求由各平台 sdk reporter 实现
    */
-  ;
+;
   /**
    * 初始化时
    */

package/es/monitor/index.d.ts

@@ -0,0 +1,6 @@
+export { logger, callMonitored } from './logger';
+export type { ILogger } from './logger';
+export { Telemetry, convertBundlesToLogGroup } from './telemetry';
+export type { TelemetryContext } from './telemetry';
+export type { MonitorLogEvent, MonitorLogLevel, MonitorEventBundle, IMonitorReporter, ISelfMonitorConfig } from './types';
+export { encodeLogGroup } from '../utils/protobuf';

package/es/monitor/index.js

@@ -0,0 +1,3 @@
+export { logger, callMonitored } from './logger';
+export { Telemetry, convertBundlesToLogGroup } from './telemetry';
+export { encodeLogGroup } from '../utils/protobuf';

package/es/monitor/logger.d.ts

@@ -0,0 +1,34 @@
+import { MonitorLogEvent, MonitorLogLevel } from './types';
+type LogArgs = [module: string, message: string, error?: unknown, context?: Record<string, unknown>];
+export interface ILogger {
+    debug(...args: LogArgs): void;
+    info(...args: LogArgs): void;
+    warn(...args: LogArgs): void;
+    error(...args: LogArgs): void;
+    crash(...args: LogArgs): void;
+}
+declare class Logger implements ILogger {
+    private console;
+    private reportLevels;
+    private onError?;
+    setConsole(enabled: boolean): void;
+    setReportLevels(levels: MonitorLogLevel[]): void;
+    setOnError(handler?: (event: MonitorLogEvent) => void): void;
+    debug(...args: LogArgs): void;
+    info(...args: LogArgs): void;
+    warn(...args: LogArgs): void;
+    error(...args: LogArgs): void;
+    crash(...args: LogArgs): void;
+    private log;
+    /**
+     * 函数包装器 — 用于箭头函数属性
+     * 用法: private handler = logger.wrap((e) => {...}, 'module', 'message?')
+     */
+    wrap<T extends (...args: any[]) => unknown>(fn: T, module: string, message?: string): T;
+}
+export declare const logger: Logger;
+/**
+ * 执行被监控函数，异常时自动上报
+ */
+export declare function callMonitored<T extends (...args: any[]) => unknown>(fn: T, context?: any, args?: any, module?: string, message?: string): ReturnType<T> | undefined;
+export {};

package/es/monitor/logger.js

@@ -0,0 +1,112 @@
+var DEFAULT_REPORT_LEVELS = ['debug', 'error', 'crash'];
+var Logger = /*#__PURE__*/function () {
+  function Logger() {
+    this.console = false;
+    this.reportLevels = DEFAULT_REPORT_LEVELS;
+    this.onError = void 0;
+  }
+  var _proto = Logger.prototype;
+  _proto.setConsole = function setConsole(enabled) {
+    this.console = enabled;
+  };
+  _proto.setReportLevels = function setReportLevels(levels) {
+    this.reportLevels = levels;
+  };
+  _proto.setOnError = function setOnError(handler) {
+    this.onError = handler;
+  };
+  _proto.debug = function debug() {
+    for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+      args[_key] = arguments[_key];
+    }
+    this.log('debug', args);
+  };
+  _proto.info = function info() {
+    for (var _len2 = arguments.length, args = new Array(_len2), _key2 = 0; _key2 < _len2; _key2++) {
+      args[_key2] = arguments[_key2];
+    }
+    this.log('info', args);
+  };
+  _proto.warn = function warn() {
+    for (var _len3 = arguments.length, args = new Array(_len3), _key3 = 0; _key3 < _len3; _key3++) {
+      args[_key3] = arguments[_key3];
+    }
+    this.log('warn', args);
+  };
+  _proto.error = function error() {
+    for (var _len4 = arguments.length, args = new Array(_len4), _key4 = 0; _key4 < _len4; _key4++) {
+      args[_key4] = arguments[_key4];
+    }
+    this.log('error', args);
+  };
+  _proto.crash = function crash() {
+    for (var _len5 = arguments.length, args = new Array(_len5), _key5 = 0; _key5 < _len5; _key5++) {
+      args[_key5] = arguments[_key5];
+    }
+    this.log('crash', args);
+  };
+  _proto.log = function log(level, _ref) {
+    var _this$onError;
+    var module = _ref[0],
+      message = _ref[1],
+      error = _ref[2],
+      context = _ref[3];
+    if (this.console) {
+      var consoleFn = level === 'crash' ? 'error' : level === 'debug' ? 'log' : level;
+      console[consoleFn]("[RUM-SDK][" + module + "]", message, error || '');
+    }
+
+    // 仅上报配置中指定的级别
+    if (!this.reportLevels.includes(level)) return;
+    var stack;
+    if (error instanceof Error) {
+      stack = error.stack;
+    } else if (error && typeof error === 'object' && 'stack' in error) {
+      stack = String(error.stack);
+    }
+
+    // 截断过长的 stack（与 content 同等 12KB 上限）
+    if (stack && stack.length > 12288) {
+      stack = stack.slice(0, 12288);
+    }
+    (_this$onError = this.onError) === null || _this$onError === void 0 ? void 0 : _this$onError.call(this, Object.assign({
+      level: level,
+      content: message,
+      type: module,
+      stack: stack
+    }, context));
+  }
+
+  /**
+   * 函数包装器 — 用于箭头函数属性
+   * 用法: private handler = logger.wrap((e) => {...}, 'module', 'message?')
+   */;
+  _proto.wrap = function wrap(fn, module, message) {
+    return function () {
+      for (var _len6 = arguments.length, args = new Array(_len6), _key6 = 0; _key6 < _len6; _key6++) {
+        args[_key6] = arguments[_key6];
+      }
+      return callMonitored(fn, this, args, module, message);
+    };
+  };
+  return Logger;
+}();
+export var logger = new Logger();
+
+/**
+ * 执行被监控函数，异常时自动上报
+ */
+export function callMonitored(fn, context, args, module, message) {
+  try {
+    var result = fn.apply(context, args);
+    // 检测 async 函数返回的 Promise，附加 .catch 处理
+    if (result && typeof result["catch"] === 'function') {
+      result["catch"](function (e) {
+        logger.error(module || 'unknown', message || (e instanceof Error ? e.message : String(e)), e);
+      });
+    }
+    return result;
+  } catch (e) {
+    logger.error(module || 'unknown', message || (e instanceof Error ? e.message : String(e)), e);
+  }
+}

package/es/monitor/telemetry.d.ts

@@ -0,0 +1,42 @@
+import { MonitorLogEvent, MonitorEventBundle, IMonitorReporter, ISelfMonitorConfig } from './types';
+export interface TelemetryContext {
+    appType: string;
+    sdkVersion: string;
+    endpoint: string;
+    getSessionId?: () => string | undefined;
+    getViewId?: () => string | undefined;
+    getSessionSampled?: () => boolean;
+    /** 自监控配置 */
+    selfMonitor?: ISelfMonitorConfig | boolean;
+    [key: string]: unknown;
+}
+export declare class Telemetry {
+    private static instance;
+    static init(context: TelemetryContext, reporter?: IMonitorReporter): Telemetry;
+    static get(): Telemetry | undefined;
+    private buffer;
+    private queue;
+    private sentEvents;
+    private started;
+    private enabled;
+    private sampled;
+    private timer;
+    private reporter?;
+    private context;
+    private isReporting;
+    private endpointParams;
+    constructor(context: TelemetryContext, reporter?: IMonitorReporter);
+    private start;
+    addEvent(event: MonitorLogEvent): void;
+    flush(): void;
+    setReporter(reporter: IMonitorReporter): void;
+    private flushBuffer;
+    private processSnapshot;
+    private shouldSend;
+    private buildBundle;
+    private sendBatch;
+}
+/**
+ * 将 MonitorEventBundle 数组转换并编码为 SLS LogGroup Protobuf 格式
+ */
+export declare function convertBundlesToLogGroup(data: MonitorEventBundle[]): Uint8Array;

package/es/monitor/telemetry.js

@@ -0,0 +1,210 @@
+import _extends from "@babel/runtime/helpers/extends";
+var _Telemetry;
+import { logger } from './logger';
+import { getUrlParams } from '../utils/url';
+import { encodeLogGroup } from '../utils/protobuf';
+import { performDraw } from '../utils/number';
+var MAX_EVENTS_PER_PAGE = 15;
+var BUFFER_SIZE = 100;
+var LOG_CONTENT_MAX_SIZE = 12288;
+var FLUSH_TIME = 5000;
+var MAX_BATCH_SIZE = 10;
+var DEFAULT_SAMPLE_RATE = 100;
+
+/** 事件快照：在事件产生时就捕获上下文 */
+
+export var Telemetry = /*#__PURE__*/function () {
+  function Telemetry(context, reporter) {
+    this.buffer = [];
+    this.queue = [];
+    this.sentEvents = new Set();
+    this.started = false;
+    this.enabled = true;
+    this.sampled = void 0;
+    this.timer = null;
+    this.reporter = void 0;
+    this.context = void 0;
+    this.isReporting = false;
+    this.endpointParams = void 0;
+    this.context = context;
+    this.reporter = reporter;
+    this.endpointParams = getUrlParams(context.endpoint);
+
+    // 解析自监控配置
+    var selfMonitor = context.selfMonitor;
+    if (typeof selfMonitor === 'boolean') {
+      this.enabled = selfMonitor;
+      this.sampled = performDraw(DEFAULT_SAMPLE_RATE);
+    } else if (selfMonitor && typeof selfMonitor === 'object') {
+      this.enabled = selfMonitor.enable !== false;
+      var rate = selfMonitor.sampling;
+      this.sampled = performDraw(typeof rate === 'number' && rate >= 0 && rate <= 100 ? rate : DEFAULT_SAMPLE_RATE);
+      if (selfMonitor.console) {
+        logger.setConsole(true);
+      }
+      if (selfMonitor.reportLevels) {
+        logger.setReportLevels(selfMonitor.reportLevels);
+      }
+    } else {
+      this.enabled = true;
+      this.sampled = performDraw(DEFAULT_SAMPLE_RATE);
+    }
+  }
+  Telemetry.init = function init(context, reporter) {
+    if (Telemetry.instance) {
+      Telemetry.instance.flush();
+    }
+    Telemetry.instance = new Telemetry(context, reporter);
+    Telemetry.instance.start();
+    return Telemetry.instance;
+  };
+  Telemetry.get = function get() {
+    return Telemetry.instance;
+  };
+  var _proto = Telemetry.prototype;
+  _proto.start = function start() {
+    var _this = this;
+    if (this.started) return;
+    this.started = true;
+    logger.setOnError(function (event) {
+      return _this.addEvent(event);
+    });
+    this.flushBuffer();
+  };
+  _proto.addEvent = function addEvent(event) {
+    var _this$context$getSess, _this$context, _this$context$getView, _this$context2;
+    if (!this.enabled || !event) return;
+    if (event.content && event.content.length > LOG_CONTENT_MAX_SIZE) {
+      event = _extends({}, event, {
+        content: event.content.slice(0, LOG_CONTENT_MAX_SIZE)
+      });
+    }
+    if (event.stack && event.stack.length > LOG_CONTENT_MAX_SIZE) {
+      event = _extends({}, event, {
+        stack: event.stack.slice(0, LOG_CONTENT_MAX_SIZE)
+      });
+    }
+
+    // 在事件产生时就捕获快照
+    var snapshot = {
+      event: event,
+      sessionId: (_this$context$getSess = (_this$context = this.context).getSessionId) === null || _this$context$getSess === void 0 ? void 0 : _this$context$getSess.call(_this$context),
+      viewId: (_this$context$getView = (_this$context2 = this.context).getViewId) === null || _this$context$getView === void 0 ? void 0 : _this$context$getView.call(_this$context2),
+      timestamp: Date.now()
+    };
+    if (!this.started || !this.reporter) {
+      if (this.buffer.length < BUFFER_SIZE) {
+        this.buffer.push(snapshot);
+      }
+      return;
+    }
+    this.processSnapshot(snapshot);
+  };
+  _proto.flush = function flush() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.sendBatch();
+  };
+  _proto.setReporter = function setReporter(reporter) {
+    this.reporter = reporter;
+    if (this.started) {
+      this.flushBuffer();
+    }
+  };
+  _proto.flushBuffer = function flushBuffer() {
+    var _this2 = this;
+    var buffered = this.buffer.splice(0);
+    buffered.forEach(function (snapshot) {
+      return _this2.processSnapshot(snapshot);
+    });
+  };
+  _proto.processSnapshot = function processSnapshot(snapshot) {
+    var _this3 = this;
+    if (!this.shouldSend(snapshot.event)) return;
+    var bundle = this.buildBundle(snapshot);
+    this.queue.push(bundle);
+    if (this.queue.length >= MAX_BATCH_SIZE) {
+      this.flush();
+    } else if (!this.timer) {
+      this.timer = setTimeout(function () {
+        return _this3.flush();
+      }, FLUSH_TIME);
+    }
+  };
+  _proto.shouldSend = function shouldSend(event) {
+    // 先检查 Session 采样，未命中则不上报
+    if (this.context.getSessionSampled && !this.context.getSessionSampled()) return false;
+    // 再检查自监控自身采样
+    if (!this.sampled) return false;
+    if (this.sentEvents.size >= MAX_EVENTS_PER_PAGE) return false;
+    var key = (event.content || '') + (event.stack || '');
+    if (this.sentEvents.has(key)) return false;
+    this.sentEvents.add(key);
+    return true;
+  };
+  _proto.buildBundle = function buildBundle(snapshot) {
+    var _this$context3 = this.context,
+      appType = _this$context3.appType,
+      sdkVersion = _this$context3.sdkVersion,
+      endpoint = _this$context3.endpoint;
+    return _extends({
+      'app.type': appType,
+      _v: sdkVersion,
+      endpoint: endpoint,
+      'session.id': snapshot.sessionId,
+      'view.id': snapshot.viewId,
+      timestamp: snapshot.timestamp,
+      event_type: 'log',
+      log: snapshot.event
+    }, this.endpointParams);
+  };
+  _proto.sendBatch = function sendBatch() {
+    if (this.queue.length === 0 || !this.reporter) return;
+    if (this.isReporting) return;
+    var batch = this.queue.splice(0);
+    this.isReporting = true;
+    try {
+      this.reporter.send(batch);
+    } catch (e) {
+      // 不通过 logger（避免反馈循环），直接 console 仅供开发调试
+      try {
+        console.warn('[RUM-Telemetry] send failed:', e);
+      } catch (_) {}
+    } finally {
+      this.isReporting = false;
+    }
+  };
+  return Telemetry;
+}();
+
+/**
+ * 将 MonitorEventBundle 数组转换并编码为 SLS LogGroup Protobuf 格式
+ */
+_Telemetry = Telemetry;
+Telemetry.instance = void 0;
+export function convertBundlesToLogGroup(data) {
+  var logs = data.map(function (bundle) {
+    var contents = [];
+
+    // 遍历 bundle 顶层字段，跳过 timestamp（映射到 time），对象类型整体序列化
+    for (var _i = 0, _Object$entries = Object.entries(bundle); _i < _Object$entries.length; _i++) {
+      var _Object$entries$_i = _Object$entries[_i],
+        _key = _Object$entries$_i[0],
+        val = _Object$entries$_i[1];
+      if (_key === 'timestamp') continue;
+      if (val !== undefined && val !== null) {
+        contents.push({
+          key: _key,
+          value: typeof val === 'object' ? JSON.stringify(val) : String(val)
+        });
+      }
+    }
+    return {
+      time: Math.floor(bundle.timestamp / 1000),
+      contents: contents
+    };
+  });
+  return encodeLogGroup(logs);
+}

package/es/monitor/types.d.ts

@@ -0,0 +1,46 @@
+export type MonitorLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'crash';
+export interface MonitorLogEvent {
+    level: MonitorLogLevel;
+    content: string;
+    stack?: string;
+    type?: string;
+    [key: string]: unknown;
+}
+export interface MonitorEventBundle {
+    'app.type': string;
+    _v: string;
+    endpoint: string;
+    'session.id'?: string;
+    'view.id'?: string;
+    timestamp: number;
+    event_type: 'log';
+    log?: MonitorLogEvent;
+    [key: string]: unknown;
+}
+export interface IMonitorReporter {
+    send(data: MonitorEventBundle[]): void;
+}
+/**
+ * 自监控配置
+ */
+export interface ISelfMonitorConfig {
+    /**
+     * 是否启用自监控，默认 true
+     */
+    enable?: boolean;
+    /**
+     * 采样率，取值范围 0 - 100，支持小数（如 50.5 表示 50.5%）
+     * 所有级别日志统一受采样率控制
+     */
+    sampling?: number;
+    /**
+     * 是否在浏览器控制台输出自监控日志，默认 false
+     * 设为 true 时，所有级别日志会同时输出到控制台
+     */
+    console?: boolean;
+    /**
+     * 需要上报到 Telemetry 的日志级别列表
+     * 默认值: ['debug', 'error', 'crash']
+     */
+    reportLevels?: MonitorLogLevel[];
+}

package/es/monitor/types.js

@@ -0,0 +1 @@
+export {};

package/es/types/client.d.ts

@@ -5,6 +5,7 @@ import { RumEvent, RumEventBundle, IViewData } from './rum-event';
 import { MatchOption } from '../utils/match';
 import { IConfigManager } from './config';
 import { EventEmitter } from '../utils/events';
+import { ISelfMonitorConfig, IMonitorReporter } from '../monitor/types';
 export declare enum EventType {
     /**
      * 收集数据
@@ -33,7 +34,15 @@ export interface IContext {
     [key: string]: any;
 }
 export interface SessionConfig {
+    /**
+     * Session 采样率，取值范围 0 - 1 的小数
+     * @deprecated 该字段将在未来版本下线，请使用 {@link SessionConfig.sampling} 替代
+     */
     sampleRate?: number;
+    /**
+     * Session 采样率，取值范围 0 - 100，支持小数（如 50.5 表示 50.5%）
+     */
+    sampling?: number;
     maxDuration?: number;
     overtime?: number;
     storage?: string;
@@ -46,6 +55,10 @@ export interface IReportConfig {
 }
 export interface IRumSession {
     init(ctx: IContext): void;
+    /** 平台类型标识，如 'browser'/'miniapp' */
+    appType: string;
+    /** SDK 版本号 */
+    sdkVersion: string;
     sessionConfig: SessionConfig;
     getSessionId: () => string;
     getSampled: () => boolean;
@@ -102,7 +115,7 @@ export interface IClient {
     /**
      * 初始化
      */
-    init: (configuration: IConfiguration, rumSession?: IRumSession, configManager?: IConfigManager) => void;
+    init: (configuration: IConfiguration, rumSession?: IRumSession, configManager?: IConfigManager, monitorReporter?: IMonitorReporter) => void;
     /**
      * 业务自定义上传数据
      */
@@ -227,5 +240,13 @@ export interface IConfiguration {
         attributeName: string;
         attributeValue?: Array<string | RegExp> | null;
     }>;
+    /**
+     * 自监控（Self-Monitor）配置
+     * 用于控制 SDK 内部异常和错误的自动上报行为
+     * - `boolean`: 简单启用/禁用自监控
+     * - `ISelfMonitorConfig`: 详细配置，可指定采样率等
+     * @default true
+     */
+    selfMonitor?: boolean | ISelfMonitorConfig;
     [key: string]: unknown;
 }