@blueking/open-telemetry 0.0.1

package/src/core/sampling.ts

@@ -0,0 +1,64 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import type { NormalizedBkOTConfig } from './config';
+
+const SAMPLE_STORAGE_KEY = '__bk_ot_sampled__';
+
+// 在 sessionStorage 不可用时降级到模块内单例缓存，避免同会话内多次结果不一致
+const memoryCache = new Map<string, boolean>();
+
+const readMemory = (key: string) => memoryCache.get(key);
+const writeMemory = (key: string, value: boolean) => {
+  memoryCache.set(key, value);
+  return value;
+};
+
+export const isBkOTSampled = ({ sampleRate }: Pick<NormalizedBkOTConfig, 'sampleRate'>) => {
+  if (sampleRate <= 0) {
+    return false;
+  }
+  if (sampleRate >= 1) {
+    return true;
+  }
+
+  try {
+    const cached = sessionStorage.getItem(SAMPLE_STORAGE_KEY);
+    if (cached) {
+      return cached === '1';
+    }
+    const sampled = Math.random() < sampleRate;
+    sessionStorage.setItem(SAMPLE_STORAGE_KEY, sampled ? '1' : '0');
+    writeMemory(SAMPLE_STORAGE_KEY, sampled);
+    return sampled;
+  } catch {
+    const cached = readMemory(SAMPLE_STORAGE_KEY);
+    if (typeof cached === 'boolean') {
+      return cached;
+    }
+    return writeMemory(SAMPLE_STORAGE_KEY, Math.random() < sampleRate);
+  }
+};

package/src/core/sdk.ts

@@ -0,0 +1,327 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import {
+  type Attributes,
+  type Span,
+  context,
+  metrics,
+  propagation,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+} from '@opentelemetry/api';
+import { logs } from '@opentelemetry/api-logs';
+import { ZoneContextManager } from '@opentelemetry/context-zone';
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs';
+import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { BatchSpanProcessor, ParentBasedSampler, TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';
+import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
+
+import { createBlankScreenPlugin } from '../plugins/blank-screen';
+import { createCommonInstrumentationsPlugin } from '../plugins/common';
+import { createCspViolationPlugin } from '../plugins/csp-violation';
+import { createDevicePlugin } from '../plugins/device';
+import { createErrorPlugin } from '../plugins/error';
+import { createHttpBodyPlugin } from '../plugins/http-body';
+import { createLongTaskPlugin } from '../plugins/long-task';
+import { createPageViewPlugin } from '../plugins/page-view';
+import { createRouteTimingPlugin } from '../plugins/route-timing';
+import { createSessionPlugin } from '../plugins/session';
+import { createWebVitalsPlugin } from '../plugins/web-vitals';
+import { createWebSocketPlugin } from '../plugins/websocket';
+import { type BkOTConfig, type BkOTCustomEventPayload, type NormalizedBkOTConfig, normalizeConfig } from './config';
+import { type BkOTPlugin, type BkOTRuntimeContext, PluginManager } from './plugin';
+import { FilteringSpanProcessor } from './processor';
+import { isBkOTSampled } from './sampling';
+
+import type { LogRecord } from '@opentelemetry/api-logs';
+
+export interface BkOTInstance extends BkOTRuntimeContext {
+  flush: () => Promise<void>;
+  reportCustomEvent: (payload: BkOTCustomEventPayload) => void;
+  shutdown: () => Promise<void>;
+  start: () => Promise<void>;
+}
+
+const createExporterOptions = (config: NormalizedBkOTConfig['traces']) => ({
+  url: config.endpoint,
+  headers: config.headers,
+  concurrencyLimit: config.concurrencyLimit,
+  timeoutMillis: config.timeoutMillis,
+});
+
+type DebugSignal = 'logs' | 'metrics' | 'traces';
+
+const BK_OT_INSTRUMENTATION_NAME = 'bk-rum';
+
+/**
+ * 用 Proxy 包装一层 debug 旁路，避免直接 mutate 第三方 exporter 实例（其内部可能含 #private fields）。
+ */
+const wrapWithDebug = <TExporter extends { export: (...args: any[]) => any }>(
+  exporter: TExporter,
+  signal: DebugSignal,
+  enabled: boolean,
+): TExporter => {
+  if (!enabled) {
+    return exporter;
+  }
+  return new Proxy(exporter, {
+    get(target, prop, receiver) {
+      if (prop === 'export') {
+        return (records: unknown, callback: unknown) => {
+          globalThis.console?.log(`[bk-ot][${signal}]`, records);
+          return (target as { export: (...args: unknown[]) => unknown }).export(records, callback);
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+};
+
+// 负责给原生 fetch/xhr 注入 W3C traceparent 头；仅 SDK 启用时装载，避免 disabled 状态仍 patch 全局 API
+const getCorePlugins = (config: NormalizedBkOTConfig): BkOTPlugin[] => [
+  createCommonInstrumentationsPlugin(config.instrumentations),
+];
+
+// 仅在采样命中时启用的"会主动产生数据"的 RUM 插件
+const getRumPlugins = (config: NormalizedBkOTConfig): BkOTPlugin[] => [
+  createDevicePlugin(config.rum.device),
+  createHttpBodyPlugin(config.rum.httpBody),
+  createSessionPlugin(config.rum.session),
+  createPageViewPlugin(config.rum.pageView),
+  createErrorPlugin(config.rum.error),
+  createWebVitalsPlugin(config.rum.webVitals),
+  createBlankScreenPlugin(config.rum.blankScreen),
+  createWebSocketPlugin(config.rum.websocket),
+  createLongTaskPlugin(config.rum.longTask),
+  createCspViolationPlugin(config.rum.cspViolation),
+  createRouteTimingPlugin(config.rum.routeTiming),
+];
+
+type SdkLifecyclePhase = 'idle' | 'started' | 'stopped';
+
+export const createBkOT = (inputConfig: BkOTConfig): BkOTInstance => {
+  const config = normalizeConfig(inputConfig);
+  const sampled = config.enabled && isBkOTSampled(config);
+  const resource = resourceFromAttributes(config.resourceAttributes);
+  const spanExporter = wrapWithDebug(
+    new OTLPTraceExporter(createExporterOptions(config.traces)),
+    'traces',
+    config.debug,
+  );
+  const metricExporter = wrapWithDebug(
+    new OTLPMetricExporter(createExporterOptions(config.metrics)),
+    'metrics',
+    config.debug,
+  );
+  const logExporter = wrapWithDebug(new OTLPLogExporter(createExporterOptions(config.logs)), 'logs', config.debug);
+  const batchSpanProcessor = new BatchSpanProcessor(spanExporter, config.spanBatch);
+  const spanProcessor = new FilteringSpanProcessor(batchSpanProcessor, config);
+  const metricReader = new PeriodicExportingMetricReader({
+    exporter: metricExporter,
+    exportIntervalMillis: config.metricIntervalMillis,
+  });
+  const logProcessor = new BatchLogRecordProcessor(logExporter);
+  const tracerProvider = new WebTracerProvider({
+    resource,
+    sampler: new ParentBasedSampler({
+      root: new TraceIdRatioBasedSampler(sampled ? 1 : 0),
+    }),
+    spanProcessors: [spanProcessor],
+  });
+  const meterProvider = new MeterProvider({
+    resource,
+    readers: [metricReader],
+  });
+  const loggerProvider = new LoggerProvider({
+    resource,
+    processors: [logProcessor],
+  });
+  const tracer = tracerProvider.getTracer(BK_OT_INSTRUMENTATION_NAME);
+  const meter = meterProvider.getMeter(BK_OT_INSTRUMENTATION_NAME);
+  const logger = loggerProvider.getLogger(BK_OT_INSTRUMENTATION_NAME);
+  const runtimeAttributes: Attributes = {
+    'bk.rum.sampled': sampled,
+  };
+  // 核心插件在 SDK 启用时装载；RUM 数据上报类插件仅在采样命中时装载
+  const pluginManager = new PluginManager([
+    ...(config.enabled ? getCorePlugins(config) : []),
+    ...(sampled ? [...getRumPlugins(config), ...config.plugins] : []),
+  ]);
+  const teardownCallbacks: Array<() => void> = [];
+  let phase: SdkLifecyclePhase = 'idle';
+
+  const getRuntimeAttributes = () => ({ ...runtimeAttributes });
+  const setRuntimeAttributes = (attributes: Attributes) => {
+    Object.assign(runtimeAttributes, attributes);
+  };
+  const applyRedact = (attributes: Attributes) => config.redactAttributes(attributes);
+  const startSpan = (name: string, attributes: Attributes = {}): Span =>
+    tracer.startSpan(name, {
+      kind: SpanKind.INTERNAL,
+      attributes: applyRedact({
+        ...getRuntimeAttributes(),
+        ...attributes,
+      }),
+    });
+  const emitLog = (record: LogRecord) => {
+    const merged: LogRecord = {
+      ...record,
+      attributes: applyRedact({
+        ...getRuntimeAttributes(),
+        ...((record.attributes ?? {}) as Attributes),
+      }),
+    };
+    logger.emit(merged);
+  };
+
+  const instance: BkOTInstance = {
+    config,
+    tracer,
+    meter,
+    logger,
+    applyRedact,
+    emitLog,
+    getRuntimeAttributes,
+    setRuntimeAttributes,
+    startSpan,
+    reportCustomEvent({ attributes = {}, error, name }) {
+      if (!sampled) {
+        // 未采样时静默丢弃；如需调试请把 debug 选项打开
+        if (config.debug) {
+          globalThis.console?.warn('[bk-ot] custom event dropped (not sampled):', name);
+        }
+        return;
+      }
+
+      const span = startSpan(`custom.${name}`, {
+        ...config.getPageAttributes(),
+        ...config.getCustomAttributes(),
+        ...attributes,
+        'rum.custom.name': name,
+      });
+
+      if (error) {
+        span.recordException(error);
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: error.message,
+        });
+      }
+
+      span.end();
+    },
+    async start() {
+      if (phase === 'started') {
+        return;
+      }
+      if (phase === 'stopped') {
+        // shutdown 已经销毁了 provider/processor，此处禁止再次启动
+        throw new Error('[bk-ot] instance has been shut down and cannot be restarted; create a new instance instead.');
+      }
+      if (!config.enabled) {
+        phase = 'started';
+        return;
+      }
+      propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+      tracerProvider.register({
+        contextManager: new ZoneContextManager(),
+      });
+      metrics.setGlobalMeterProvider(meterProvider);
+      logs.setGlobalLoggerProvider(loggerProvider);
+      try {
+        await pluginManager.start(instance);
+        if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+          const flushOnPageHide = () => {
+            void instance.flush();
+          };
+          const flushOnHidden = () => {
+            if (document.visibilityState === 'hidden') {
+              void instance.flush();
+            }
+          };
+          window.addEventListener('pagehide', flushOnPageHide);
+          document.addEventListener('visibilitychange', flushOnHidden);
+          teardownCallbacks.push(
+            () => window.removeEventListener('pagehide', flushOnPageHide),
+            () => document.removeEventListener('visibilitychange', flushOnHidden),
+          );
+        }
+      } catch (error) {
+        while (teardownCallbacks.length) {
+          teardownCallbacks.pop()?.();
+        }
+        await pluginManager.shutdown();
+        trace.disable();
+        metrics.disable();
+        context.disable();
+        throw error;
+      }
+      phase = 'started';
+    },
+    async flush() {
+      await pluginManager.flush();
+      await tracerProvider.forceFlush();
+      await meterProvider.forceFlush();
+      await loggerProvider.forceFlush();
+    },
+    async shutdown() {
+      if (phase === 'stopped') {
+        return;
+      }
+      await instance.flush();
+      while (teardownCallbacks.length) {
+        teardownCallbacks.pop()?.();
+      }
+      await pluginManager.shutdown();
+      await tracerProvider.shutdown();
+      await meterProvider.shutdown();
+      await loggerProvider.shutdown();
+      trace.disable();
+      metrics.disable();
+      context.disable();
+      phase = 'stopped';
+    },
+  };
+
+  if (config.autoStart) {
+    void instance.start().catch(error => {
+      globalThis.console?.warn('[bk-ot] auto start failed:', error);
+    });
+  }
+
+  return instance;
+};
+
+export const initBkOT = createBkOT;

package/src/core/url.ts

@@ -0,0 +1,66 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import type { NormalizedBkOTConfig } from './config';
+
+const getBaseUrl = () => (typeof window === 'undefined' ? 'http://localhost' : window.location.origin);
+
+const toAbsoluteUrl = (url: string) => {
+  try {
+    return new URL(url, getBaseUrl()).href;
+  } catch {
+    return url;
+  }
+};
+
+// 去掉 trailing slash，便于 path 边界对齐比较
+const stripTrailingSlash = (value: string) => (value.length > 1 ? value.replace(/\/+$/, '') : value);
+
+// 比较两个 URL 是否指向同一资源（忽略 query/fragment 与末尾斜杠）
+const isSameResource = (left: string, right: string) => {
+  const stripped = (value: string) => stripTrailingSlash(value.replace(/[?#].*$/, ''));
+  return stripped(left) === stripped(right);
+};
+
+const isSameOrigin = (url: string) => {
+  try {
+    return new URL(url, getBaseUrl()).origin === getBaseUrl();
+  } catch {
+    return false;
+  }
+};
+
+export const isBkOTEndpoint = (config: NormalizedBkOTConfig, url: string) => {
+  const targetUrl = toAbsoluteUrl(url);
+
+  return [config.traces.endpoint, config.metrics.endpoint, config.logs.endpoint].some(endpoint =>
+    isSameResource(targetUrl, toAbsoluteUrl(endpoint))
+  );
+};
+
+export const shouldIgnoreUrl = (config: NormalizedBkOTConfig, url: string) => isBkOTEndpoint(config, url);
+
+export const shouldPropagateTraceHeader = (_config: NormalizedBkOTConfig, url: string) => isSameOrigin(url);

package/src/index.ts

@@ -0,0 +1,55 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+export {
+  type BkOTAttributesConfig,
+  type BkOTAttributeValue,
+  type BkOTBatchConfig,
+  type BkOTConfig,
+  type BkOTCustomEventPayload,
+  type BkOTHttpBodyConfig,
+  type BkOTHttpBodyRedactPayload,
+  type BkOTRedactConfig,
+  type BkOTRumConfig,
+  normalizeConfig,
+  type NormalizedBkOTConfig,
+  type SignalExporterConfig,
+} from './core/config';
+export { type BkOTPlugin, type BkOTRuntimeContext, createPlugin, type PluginManager } from './core/plugin';
+export { FilteringSpanProcessor } from './core/processor';
+export { type BkOTInstance, createBkOT, initBkOT } from './core/sdk';
+export { createBlankScreenPlugin } from './plugins/blank-screen';
+export { createCommonInstrumentationsPlugin } from './plugins/common';
+export { createCspViolationPlugin } from './plugins/csp-violation';
+export { createDevicePlugin } from './plugins/device';
+export { createErrorPlugin } from './plugins/error';
+export { createHttpBodyPlugin } from './plugins/http-body';
+export { createLongTaskPlugin } from './plugins/long-task';
+export { createPageViewPlugin } from './plugins/page-view';
+export { createRouteTimingPlugin } from './plugins/route-timing';
+export { createSessionPlugin } from './plugins/session';
+export { createWebVitalsPlugin } from './plugins/web-vitals';
+export { createWebSocketPlugin } from './plugins/websocket';

package/src/plugins/blank-screen.ts

@@ -0,0 +1,170 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import { SeverityNumber } from '@opentelemetry/api-logs';
+
+import type { BkOTRumConfig } from '../core/config';
+import type { BkOTPlugin } from '../core/plugin';
+
+const DEFAULT_SELECTOR = 'body';
+const DEFAULT_CHECK_DELAY = 3000;
+const DEFAULT_THRESHOLD = 0.8;
+// 常见 loading mask / spinner 选择器，命中说明页面正在加载而非空白
+const DEFAULT_LOADING_SELECTORS = [
+  '[data-loading="true"]',
+  '[aria-busy="true"]',
+  '.loading',
+  '.is-loading',
+  '.spinner',
+  '.skeleton',
+  '.bk-loading',
+];
+
+const SAMPLE_POINTS: Array<[number, number]> = [
+  [0.5, 0.5],
+  [0.25, 0.25],
+  [0.75, 0.25],
+  [0.25, 0.75],
+  [0.75, 0.75],
+];
+
+const getElementSelector = (element: Element | null) => {
+  if (!element) {
+    return '';
+  }
+  const tag = element.tagName.toLowerCase();
+  if (element.id) {
+    return `${tag}#${element.id}`;
+  }
+  return tag;
+};
+
+const matchesAny = (element: Element | null, selectors: string[]) => {
+  if (!element) return false;
+  return selectors.some(selector => {
+    try {
+      return element.matches(selector) || !!element.closest(selector);
+    } catch {
+      return false;
+    }
+  });
+};
+
+// 页面就绪后再开始计时，避免 SPA / 慢加载场景下检测时机过早
+const whenDocumentReady = (callback: () => void) => {
+  if (typeof document === 'undefined') return;
+  if (document.readyState === 'complete' || document.readyState === 'interactive') {
+    callback();
+    return;
+  }
+  const handler = () => {
+    document.removeEventListener('DOMContentLoaded', handler);
+    callback();
+  };
+  document.addEventListener('DOMContentLoaded', handler);
+};
+
+export const createBlankScreenPlugin = (option: BkOTRumConfig['blankScreen']): BkOTPlugin => {
+  let timer: number | undefined;
+
+  return {
+    name: 'blank-screen',
+    enabled: Boolean(option),
+    init(context) {
+      if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return;
+      }
+
+      const optionObj = typeof option === 'object' ? option : {};
+      const rootSelector = optionObj.rootSelector ?? DEFAULT_SELECTOR;
+      const checkDelay = optionObj.checkDelay ?? DEFAULT_CHECK_DELAY;
+      const threshold = optionObj.threshold ?? DEFAULT_THRESHOLD;
+      const loadingSelectors = [...DEFAULT_LOADING_SELECTORS, ...(optionObj.ignoreSelectors ?? [])];
+
+      // 仅创建一次 counter，避免每次回调都触发一次 meter lookup
+      const counter = context.meter.createCounter('browser.blank_screen.count', {
+        description: 'Number of suspected blank screen detections',
+      });
+
+      whenDocumentReady(() => {
+        timer = window.setTimeout(() => {
+          const root = document.querySelector(rootSelector);
+          let emptyCount = 0;
+          let loadingCount = 0;
+
+          for (const [x, y] of SAMPLE_POINTS) {
+            const element = document.elementFromPoint(window.innerWidth * x, window.innerHeight * y);
+            if (matchesAny(element, loadingSelectors)) {
+              loadingCount += 1;
+              continue;
+            }
+            if (element === root || element === document.body || element === document.documentElement) {
+              emptyCount += 1;
+            }
+          }
+
+          const score = emptyCount / SAMPLE_POINTS.length;
+          // 触发 loading mask 的样本算"非空"，但若全部点都是 loading，则视为待定不上报
+          if (loadingCount === SAMPLE_POINTS.length) {
+            return;
+          }
+          const isBlank = score >= threshold;
+          const attributes = {
+            'bk.rum.blank_screen.score': score,
+            'bk.rum.blank_screen.threshold': threshold,
+            'bk.rum.blank_screen.root': rootSelector,
+            'bk.rum.blank_screen.detected': isBlank,
+            'bk.rum.blank_screen.center_element': getElementSelector(
+              document.elementFromPoint(window.innerWidth / 2, window.innerHeight / 2),
+            ),
+            'bk.rum.blank_screen.dom_node_count': document.body?.getElementsByTagName('*').length ?? 0,
+          };
+
+          if (isBlank) {
+            counter.add(
+              1,
+              context.applyRedact({
+                // 仅放进低基数维度，center_element 等高基数字段只走 log
+                'bk.rum.blank_screen.root': rootSelector,
+              }),
+            );
+            context.emitLog({
+              severityNumber: SeverityNumber.ERROR,
+              severityText: 'ERROR',
+              body: 'browser.blank_screen',
+              attributes,
+            });
+          }
+        }, checkDelay);
+      });
+    },
+    shutdown() {
+      if (timer !== undefined && typeof window !== 'undefined') {
+        window.clearTimeout(timer);
+      }
+    },
+  };
+};