@blueking/open-telemetry 0.0.1

package/src/plugins/common.ts

@@ -0,0 +1,131 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/naming-convention */
+/*
+ * 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 Instrumentation, registerInstrumentations } from '@opentelemetry/instrumentation';
+
+import { shouldIgnoreUrl, shouldPropagateTraceHeader } from '../core/url';
+
+import type { BkOTInstrumentationsConfig } from '../core/config';
+import type { BkOTPlugin, BkOTRuntimeContext } from '../core/plugin';
+
+const URL_KEYS = ['http.url', 'url.full'];
+
+// OTel 官方 instrumentation 内部对每个 URL 调用 matcher.test(url)，
+// 这里把"用户函数 + 自身 endpoint 过滤"包装成具备 .test 的对象，是与 OTel 一致的扩展用法
+const toUrlPredicateMatcher = (predicate: (url: string) => boolean): RegExp =>
+  ({ test: predicate }) as unknown as RegExp;
+
+// 对官方 instrumentation 创建的 span，统一附加 page attributes 与 URL 脱敏
+const decorateSpan = (
+  context: BkOTRuntimeContext,
+  span: {
+    attributes?: Record<string, any>;
+    setAttribute: (key: string, value: any) => void;
+    setAttributes: (attrs: Record<string, any>) => void;
+  },
+) => {
+  span.setAttributes(context.applyRedact(context.config.getPageAttributes()));
+  for (const key of URL_KEYS) {
+    const value = span.attributes?.[key];
+    if (typeof value === 'string') {
+      const redactedAttributes = context.applyRedact({ [key]: context.config.redactUrl(value) });
+      const redactedUrl = redactedAttributes[key];
+      if (typeof redactedUrl === 'string') {
+        span.setAttribute(key, redactedUrl);
+      }
+    }
+  }
+};
+
+export const createCommonInstrumentationsPlugin = (option: BkOTInstrumentationsConfig): BkOTPlugin => {
+  const instrumentations: Instrumentation[] = [];
+
+  return {
+    name: 'official-instrumentations',
+    enabled: Boolean(option.documentLoad || option.fetch || option.xhr || option.userInteraction),
+    async init(context) {
+      const loadedInstrumentations: Instrumentation[] = [];
+      const ignoreUrls = [toUrlPredicateMatcher(url => shouldIgnoreUrl(context.config, url))];
+      const propagateTraceHeaderCorsUrls = [
+        toUrlPredicateMatcher(url => shouldPropagateTraceHeader(context.config, url)),
+      ];
+
+      if (option.documentLoad) {
+        const { DocumentLoadInstrumentation } = await import('@opentelemetry/instrumentation-document-load');
+        loadedInstrumentations.push(
+          new DocumentLoadInstrumentation({
+            semconvStabilityOptIn: 'http',
+          }),
+        );
+      }
+
+      if (option.fetch) {
+        const { FetchInstrumentation } = await import('@opentelemetry/instrumentation-fetch');
+        loadedInstrumentations.push(
+          new FetchInstrumentation({
+            applyCustomAttributesOnSpan: span => decorateSpan(context, span as any),
+            ignoreUrls,
+            propagateTraceHeaderCorsUrls,
+            semconvStabilityOptIn: 'http',
+            ignoreNetworkEvents: false,
+          }),
+        );
+      }
+
+      if (option.xhr) {
+        const { XMLHttpRequestInstrumentation } = await import('@opentelemetry/instrumentation-xml-http-request');
+        loadedInstrumentations.push(
+          new XMLHttpRequestInstrumentation({
+            applyCustomAttributesOnSpan: span => decorateSpan(context, span as any),
+            ignoreUrls,
+            propagateTraceHeaderCorsUrls,
+            semconvStabilityOptIn: 'http',
+            ignoreNetworkEvents: false,
+          }),
+        );
+      }
+
+      if (option.userInteraction) {
+        const { UserInteractionInstrumentation } = await import('@opentelemetry/instrumentation-user-interaction');
+        const userInteractionConfig =
+          typeof option.userInteraction === 'object'
+            ? { eventNames: option.userInteraction.eventNames as Array<keyof HTMLElementEventMap> }
+            : undefined;
+        loadedInstrumentations.push(new UserInteractionInstrumentation(userInteractionConfig));
+      }
+
+      instrumentations.push(...loadedInstrumentations);
+      registerInstrumentations({ instrumentations: loadedInstrumentations });
+    },
+    shutdown() {
+      while (instrumentations.length) {
+        instrumentations.pop()?.disable?.();
+      }
+    },
+  };
+};

package/src/plugins/csp-violation.ts

@@ -0,0 +1,74 @@
+/*
+ * 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';
+
+/**
+ * 监听 CSP 违规事件并以 log 形式上报，便于排查脚本/资源被 CSP 拦截的问题。
+ */
+export const createCspViolationPlugin = (enabled: BkOTRumConfig['cspViolation']): BkOTPlugin => {
+  let teardown: (() => void) | undefined;
+
+  return {
+    name: 'csp-violation',
+    enabled: Boolean(enabled),
+    init(context) {
+      if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return;
+      }
+
+      const handler = (event: SecurityPolicyViolationEvent) => {
+        context.emitLog({
+          severityNumber: SeverityNumber.WARN,
+          severityText: 'WARN',
+          body: 'csp.violation',
+          attributes: {
+            ...context.config.getPageAttributes(),
+            'csp.blocked_uri': context.config.redactUrl(event.blockedURI || ''),
+            'csp.violated_directive': event.violatedDirective,
+            'csp.effective_directive': event.effectiveDirective,
+            'csp.original_policy': event.originalPolicy,
+            'csp.disposition': event.disposition,
+            'csp.source_file': context.config.redactUrl(event.sourceFile || ''),
+            'csp.line_number': event.lineNumber,
+            'csp.column_number': event.columnNumber,
+            'csp.status_code': event.statusCode,
+          },
+        });
+      };
+
+      document.addEventListener('securitypolicyviolation', handler);
+      teardown = () => document.removeEventListener('securitypolicyviolation', handler);
+    },
+    shutdown() {
+      teardown?.();
+      teardown = undefined;
+    },
+  };
+};

package/src/plugins/device.ts

@@ -0,0 +1,91 @@
+/*
+ * 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 { BkOTRumConfig } from '../core/config';
+import type { BkOTPlugin } from '../core/plugin';
+import type { Attributes } from '@opentelemetry/api';
+
+// 复用旧 session 插件的 storageKey，避免升级后丢失现网累计的设备标识
+const DEFAULT_DEVICE_STORAGE_KEY = 'bk_ot_session_id';
+
+const createId = () => {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `device-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+};
+
+const readDeviceId = (storageKey: string) => {
+  try {
+    const existed = window.localStorage.getItem(storageKey);
+    if (existed) {
+      return existed;
+    }
+    const deviceId = createId();
+    window.localStorage.setItem(storageKey, deviceId);
+    return deviceId;
+  } catch {
+    return createId();
+  }
+};
+
+const getViewportAttributes = (): Attributes => {
+  if (typeof window === 'undefined') {
+    return {};
+  }
+  const connection = (
+    navigator as Navigator & {
+      connection?: { effectiveType?: string; type?: string };
+    }
+  ).connection;
+
+  return {
+    'browser.viewport.width': window.innerWidth,
+    'browser.viewport.height': window.innerHeight,
+    'browser.screen.width': window.screen?.width,
+    'browser.screen.height': window.screen?.height,
+    'network.effective_type': connection?.effectiveType ?? connection?.type,
+  };
+};
+
+/**
+ * 设备级永久标识 + 视口 / 网络元数据。
+ * 与 session 插件区分：device 跨会话持久，session 有过期与续期。
+ */
+export const createDevicePlugin = (option: BkOTRumConfig['device']): BkOTPlugin => ({
+  name: 'device',
+  enabled: Boolean(option),
+  init(context) {
+    const storageKey =
+      typeof option === 'object' ? (option.storageKey ?? DEFAULT_DEVICE_STORAGE_KEY) : DEFAULT_DEVICE_STORAGE_KEY;
+    const deviceId = typeof window === 'undefined' ? createId() : readDeviceId(storageKey);
+
+    context.setRuntimeAttributes({
+      'device.id': deviceId,
+      ...getViewportAttributes(),
+    });
+  },
+});

package/src/plugins/error.ts

@@ -0,0 +1,211 @@
+/*
+ * 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 { SpanStatusCode, trace } from '@opentelemetry/api';
+import { SeverityNumber } from '@opentelemetry/api-logs';
+
+import type { BkOTRumConfig } from '../core/config';
+import type { BkOTPlugin, BkOTRuntimeContext } from '../core/plugin';
+
+const DEFAULT_WINDOW_MS = 60_000;
+const DEFAULT_MAX_PER_WINDOW = 5;
+
+const getErrorMessage = (value: unknown) => {
+  if (value instanceof Error) {
+    return value.message;
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+};
+
+const getErrorStack = (value: unknown) => (value instanceof Error ? (value.stack ?? '') : '');
+
+// 简易 djb2 hash，足够区分常见 error 字符串组合
+const hashString = (input: string): string => {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash * 33) ^ input.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(36);
+};
+
+interface ThrottleEntry {
+  count: number;
+  windowStart: number;
+}
+
+const createThrottle = (windowMs: number, maxPerWindow: number) => {
+  const records = new Map<string, ThrottleEntry>();
+  return {
+    /** 返回 true 表示允许上报；false 表示触发节流被抛弃 */
+    allow(key: string): boolean {
+      const now = Date.now();
+      const entry = records.get(key);
+      if (!entry || now - entry.windowStart > windowMs) {
+        records.set(key, { count: 1, windowStart: now });
+        return true;
+      }
+      if (entry.count >= maxPerWindow) {
+        return false;
+      }
+      entry.count += 1;
+      return true;
+    },
+  };
+};
+
+interface EmitErrorOptions {
+  context: BkOTRuntimeContext;
+  error: unknown;
+  exceptionType?: string;
+  extra?: Record<string, unknown>;
+  source: string;
+  spanName: string;
+  throttle: ReturnType<typeof createThrottle>;
+}
+
+const emitError = ({ context, error, exceptionType, extra = {}, source, spanName, throttle }: EmitErrorOptions) => {
+  const message = getErrorMessage(error);
+  const stack = getErrorStack(error);
+  const throttleKey = hashString(`${source}|${message}|${stack.slice(0, 256)}`);
+
+  if (!throttle.allow(throttleKey)) {
+    return;
+  }
+
+  const activeSpan = trace.getActiveSpan();
+  const exceptionLike = error instanceof Error ? error : { message, name: exceptionType ?? source };
+  const attributes = {
+    ...context.config.getPageAttributes(),
+    ...context.config.getErrorAttributes(),
+    'exception.message': message,
+    'exception.stacktrace': stack,
+    'exception.type': error instanceof Error ? error.name : (exceptionType ?? source),
+    'bk.rum.error.source': source,
+    'bk.rum.error.fingerprint': throttleKey,
+    ...extra,
+  };
+  const errorSpan = context.startSpan(spanName, attributes);
+
+  activeSpan?.recordException(exceptionLike);
+  activeSpan?.setStatus({ code: SpanStatusCode.ERROR, message });
+  errorSpan.recordException(exceptionLike);
+  errorSpan.setStatus({ code: SpanStatusCode.ERROR, message });
+  errorSpan.end();
+  context.emitLog({
+    severityNumber: SeverityNumber.ERROR,
+    severityText: 'ERROR',
+    body: message,
+    attributes,
+  });
+};
+
+export const createErrorPlugin = (option: BkOTRumConfig['error']): BkOTPlugin => {
+  const listeners: Array<() => void> = [];
+
+  return {
+    name: 'error',
+    enabled: Boolean(option),
+    init(context) {
+      if (typeof window === 'undefined') {
+        return;
+      }
+
+      const windowMs = typeof option === 'object' ? (option.windowMs ?? DEFAULT_WINDOW_MS) : DEFAULT_WINDOW_MS;
+      const maxPerWindow =
+        typeof option === 'object' ? (option.maxPerWindow ?? DEFAULT_MAX_PER_WINDOW) : DEFAULT_MAX_PER_WINDOW;
+      const throttle = createThrottle(windowMs, maxPerWindow);
+
+      const onError = (event: ErrorEvent) => {
+        emitError({
+          context,
+          throttle,
+          spanName: 'browser.error',
+          source: 'window.error',
+          error: event.error ?? event.message,
+          extra: {
+            'code.filepath': event.filename,
+            'code.lineno': event.lineno,
+            'code.column': event.colno,
+          },
+        });
+      };
+      const onUnhandledRejection = (event: PromiseRejectionEvent) => {
+        emitError({
+          context,
+          throttle,
+          spanName: 'browser.unhandledrejection',
+          source: 'unhandledrejection',
+          error: event.reason,
+          exceptionType: event.reason instanceof Error ? event.reason.name : 'UnhandledRejection',
+        });
+      };
+      const onResourceError = (event: Event) => {
+        const target = event.target as EventTarget & {
+          href?: string;
+          src?: string;
+          tagName?: string;
+        };
+        if (target === window) {
+          return;
+        }
+        const resourceUrl = target.src || target.href || '';
+        emitError({
+          context,
+          throttle,
+          spanName: 'browser.resource_error',
+          source: 'resource',
+          error: new Error(`Resource load failed: ${target.tagName?.toLowerCase() || 'unknown'} ${resourceUrl}`),
+          exceptionType: 'ResourceError',
+          extra: {
+            'url.full': context.config.redactUrl(resourceUrl),
+            'html.tag': target.tagName || '',
+          },
+        });
+      };
+
+      window.addEventListener('error', onError);
+      window.addEventListener('unhandledrejection', onUnhandledRejection);
+      window.addEventListener('error', onResourceError, true);
+      listeners.push(
+        () => window.removeEventListener('error', onError),
+        () => window.removeEventListener('unhandledrejection', onUnhandledRejection),
+        () => window.removeEventListener('error', onResourceError, true)
+      );
+    },
+    shutdown() {
+      while (listeners.length) {
+        listeners.pop()?.();
+      }
+    },
+  };
+};