@blueking/open-telemetry 0.0.1

package/playground/bk-ot.ts

@@ -0,0 +1,110 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2021 THL A29 Limited, a Tencent company.  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 BkOTPlugin, createPlugin, initBkOT } from '../src';
+
+// 自定义插件示例：在初始化时挂载一个无副作用的"自定义桥接"插件
+// 用来演示 createPlugin 的写法以及 BkOTRuntimeContext 的用法
+const customBridgePlugin: BkOTPlugin = createPlugin({
+  name: 'playground-bridge',
+  init(context) {
+    // 在 runtime attributes 注入示例标识，所有后续 span / log 都会带上
+    context.setRuntimeAttributes({
+      'playground.boot_at': Date.now(),
+      'playground.demo': true,
+    });
+
+    // 暴露一个手动触发的辅助方法到 window，方便在控制台或页面里调试
+    Object.assign(globalThis, {
+      __bkotEmitDemoSpan: (name = 'playground.manual') => {
+        const span = context.startSpan(name, {
+          'playground.manual': true,
+        });
+        span.end();
+      },
+    });
+  },
+});
+
+// initBkOT 会在 autoStart=true（默认）时自动调用 start()
+// 这里 endpoint 指向本机 OTLP collector，没起 collector 时打开 debug 即可在控制台看到产物
+export const bkot = initBkOT({
+  environment: 'development',
+  endpoint: 'http://localhost:4318',
+  token: 'playground-token',
+  debug: true,
+  sampleRate: 1,
+  // 采集能力统一放在 rum 下；默认开启项这里显式写出，便于 playground 展示完整入口
+  rum: {
+    documentLoad: true,
+    fetch: true,
+    xhr: true,
+    userInteraction: true,
+    longTask: { threshold: 50 },
+    cspViolation: true,
+    routeTiming: true,
+    httpBody: {
+      maxBodySize: 4 * 1024,
+      // redact 用于隐私脱敏：演示如何拦截敏感字段
+      redact: ({ body, type }) => {
+        if (type === 'request') {
+          return body.replace(/("password"\s*:\s*)"[^"]*"/g, '$1"***"');
+        }
+        return body;
+      },
+    },
+    blankScreen: {
+      checkDelay: 2000,
+      threshold: 0.85,
+    },
+  },
+  // 用户自定义插件
+  plugins: [customBridgePlugin],
+  redact: {
+    // 全局属性脱敏：示例屏蔽身份证号格式
+    attributes: attributes => {
+      const result = { ...attributes };
+      for (const key of Object.keys(result)) {
+        const value = result[key];
+        if (typeof value === 'string' && /\b\d{15}|\d{18}\b/.test(value)) {
+          result[key] = value.replace(/\d/g, '*');
+        }
+      }
+      return result;
+    },
+  },
+  attributes: {
+    // 业务侧可在每个 span 上附加页面级公共属性
+    page: () => ({
+      'rum.page.host': window.location.host,
+      'rum.page.path': window.location.pathname,
+      'rum.page.hash': window.location.hash,
+    }),
+    custom: () => ({
+      'biz.team': 'rum-demo',
+    }),
+  },
+});

package/playground/components/DemoLogPanel.vue

@@ -0,0 +1,89 @@
+<template>
+  <div class="log-panel">
+    <div class="log-panel__header">
+      <span class="log-panel__title">操作日志</span>
+      <button
+        class="demo-btn demo-btn--ghost log-panel__clear"
+        :disabled="!entries.length"
+        type="button"
+        @click="$emit('clear')"
+      >
+        清空
+      </button>
+    </div>
+    <div
+      v-if="entries.length"
+      class="demo-log"
+    >
+      <p
+        v-for="entry in entries"
+        :key="entry.timestamp + entry.message"
+        class="demo-log__line"
+        :class="`demo-log__line--${entry.level}`"
+      >
+        [{{ formatTime(entry.timestamp) }}] {{ entry.message }}
+      </p>
+    </div>
+    <p
+      v-else
+      class="log-panel__empty"
+    >
+      尚未触发任何事件，请点击上面的按钮开始。
+    </p>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { type DemoLogEntry, formatTime } from '../composables/use-demo-log';
+
+  defineProps<{
+    entries: DemoLogEntry[];
+  }>();
+
+  defineEmits<{
+    clear: [];
+  }>();
+</script>
+
+<style scoped>
+  .log-panel {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .log-panel__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+
+  .log-panel__title {
+    font-size: 13px;
+    font-weight: 500;
+    color: var(--color-text-secondary);
+  }
+
+  .log-panel__clear {
+    padding: 2px 10px;
+    font-size: 12px;
+  }
+
+  .log-panel__empty {
+    padding: var(--space-md);
+    margin: 0;
+    font-size: 12px;
+    color: var(--color-text-muted);
+    text-align: center;
+    background: var(--color-bg);
+    border-radius: var(--radius-sm);
+  }
+
+  .demo-log__line--warn {
+    color: #fbbf24;
+  }
+
+  .demo-log__line--error {
+    color: #f87171;
+  }
+</style>

package/playground/composables/use-demo-log.ts

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+
+import { shallowRef, triggerRef } from 'vue';
+
+export interface DemoLogEntry {
+  level: 'error' | 'info' | 'warn';
+  message: string;
+  timestamp: number;
+}
+
+// 每个 demo 页面用一个独立日志栈，刷新页面即重置
+export const useDemoLog = (max = 20) => {
+  const entries = shallowRef<DemoLogEntry[]>([]);
+
+  const push = (message: string, level: DemoLogEntry['level'] = 'info') => {
+    const next = [{ message, level, timestamp: Date.now() }, ...entries.value];
+    entries.value = next.slice(0, max);
+    triggerRef(entries);
+  };
+
+  const clear = () => {
+    entries.value = [];
+    triggerRef(entries);
+  };
+
+  return { entries, push, clear };
+};
+
+export const formatTime = (timestamp: number) => {
+  const date = new Date(timestamp);
+  return date.toLocaleTimeString('zh-CN', { hour12: false });
+};

package/playground/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>bkui-chat-x</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/playground/main.ts

@@ -0,0 +1,36 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2021 THL A29 Limited, a Tencent company.  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 { createApp } from 'vue';
+
+import App from './App.vue';
+// SDK 必须在业务代码之前完成初始化，副作用 import 放在最顶部
+import './bk-ot';
+import { router } from './router';
+
+import './style.css';
+
+createApp(App).use(router).mount('#app');

package/playground/mock/index.ts

@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+
+// playground 演示用的 mock 数据，避免散落在组件文件里
+export const httpEndpoints = {
+  // 公共可访问的 echo 接口，可以观察 fetch / xhr 自动埋点
+  echoGet: 'https://httpbin.org/get?source=bk-ot',
+  echoPost: 'https://httpbin.org/post',
+  // 故意 404 用于演示 error 上报
+  notFound: 'https://httpbin.org/status/404',
+};
+
+export const websocketEndpoint = 'wss://echo.websocket.events';
+
+export const customEvents = [
+  {
+    name: 'login',
+    description: '用户登录成功',
+    payload: { 'biz.user_id': 'u_demo_1024', 'biz.login_method': 'oauth' },
+  },
+  {
+    name: 'order.checkout',
+    description: '提交订单',
+    payload: { 'biz.order_id': 'O20260508001', 'biz.order_amount': 199.0 },
+  },
+  {
+    name: 'video.play',
+    description: '视频播放',
+    payload: { 'biz.video_id': 'v_42', 'biz.video_position_ms': 0 },
+  },
+];
+
+export const samplePostBody = {
+  username: 'demo_user',
+  password: 'should-be-redacted',
+  message: '这条 body 会被 http-body 插件捕获',
+};

package/playground/pages/BlankScreenDemo.vue

@@ -0,0 +1,97 @@
+<template>
+  <section class="demo-page">
+    <header>
+      <h2 class="demo-page__title">白屏检测 · blank-screen 插件</h2>
+      <p class="demo-page__desc">
+        加载延时（默认
+        3s）后，从根节点采样像素分布判断"是否白屏"。本页面提供一个被监控容器，可手动切换其内容验证检测结果。
+      </p>
+    </header>
+
+    <div class="demo-card">
+      <h3 class="demo-card__title">监控目标容器</h3>
+      <p class="demo-card__hint">
+        SDK 启动时已经做了一次全局检测；如需针对子容器复测，请配合 <code>rootSelector</code> 与
+        <code>checkDelay</code> 配置（见首页 SDK 配置）。
+      </p>
+      <div
+        ref="targetRef"
+        class="blank-target"
+        :class="{ 'blank-target--empty': empty }"
+      >
+        <template v-if="!empty">
+          <p>当前页面区域有正常内容渲染。</p>
+          <p>点击下方"清空区域"模拟白屏场景，再切换路由即可触发新的页面 PV。</p>
+        </template>
+      </div>
+      <div class="demo-actions">
+        <button
+          class="demo-btn demo-btn--warning"
+          type="button"
+          @click="empty = true"
+        >
+          清空区域（模拟白屏）
+        </button>
+        <button
+          class="demo-btn"
+          type="button"
+          @click="empty = false"
+        >
+          恢复内容
+        </button>
+      </div>
+    </div>
+
+    <div class="demo-card">
+      <h3 class="demo-card__title">使用建议</h3>
+      <ul class="advice">
+        <li>SDK 仅在 <code>autoStart</code> 后采样一次根节点，不做后续轮询；如需多次检测需自行触发。</li>
+        <li>避免把 loading 占位 / 骨架屏当成空白，可在 <code>ignoreSelectors</code> 中把它们排除。</li>
+        <li>对单页应用，每次路由切换可视为一次潜在白屏窗口，可结合 <code>route-timing</code> 联合分析。</li>
+      </ul>
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+  import { shallowRef } from 'vue';
+
+  const empty = shallowRef(false);
+  const targetRef = shallowRef<HTMLDivElement | null>(null);
+</script>
+
+<style scoped>
+  .blank-target {
+    min-height: 160px;
+    padding: var(--space-md);
+    margin-bottom: var(--space-md);
+    background: var(--color-bg);
+    border: 1px dashed var(--color-border);
+    border-radius: var(--radius-sm);
+  }
+
+  .blank-target--empty {
+    background: #fff;
+    border-color: #fff;
+    border-style: solid;
+  }
+
+  .blank-target p {
+    margin: 0 0 var(--space-sm);
+    color: var(--color-text-secondary);
+  }
+
+  .advice {
+    padding-left: var(--space-md);
+    margin: 0;
+    color: var(--color-text-secondary);
+  }
+
+  .advice li + li {
+    margin-top: var(--space-xs);
+  }
+
+  .advice code {
+    color: var(--color-text-primary);
+  }
+</style>

package/playground/pages/BusinessDemo.vue

@@ -0,0 +1,74 @@
+<template>
+  <section class="demo-page">
+    <header>
+      <h2 class="demo-page__title">自定义事件 · reportCustomEvent</h2>
+      <p class="demo-page__desc">
+        通过 <code>BkOTInstance.reportCustomEvent({ name, attributes, error })</code> 上报自定义事件，会同时叠加
+        <code>attributes.page()</code> 与 <code>attributes.custom()</code>。
+      </p>
+    </header>
+
+    <div class="demo-card">
+      <h3 class="demo-card__title">触发自定义事件</h3>
+      <div class="demo-actions">
+        <button
+          v-for="event in customEvents"
+          :key="event.name"
+          class="demo-btn"
+          type="button"
+          @click="report(event)"
+        >
+          {{ event.description }}（{{ event.name }}）
+        </button>
+        <button
+          class="demo-btn demo-btn--danger"
+          type="button"
+          @click="reportFailure"
+        >
+          上报失败事件（带 error）
+        </button>
+      </div>
+    </div>
+
+    <div class="demo-card">
+      <h3 class="demo-card__title">代码片段</h3>
+      <pre class="demo-snippet">{{ snippet }}</pre>
+    </div>
+
+    <div class="demo-card">
+      <DemoLogPanel
+        :entries="entries"
+        @clear="clear"
+      />
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+  import { bkot } from '../bk-ot';
+  import DemoLogPanel from '../components/DemoLogPanel.vue';
+  import { useDemoLog } from '../composables/use-demo-log';
+  import { customEvents } from '../mock';
+
+  const { entries, push, clear } = useDemoLog();
+
+  const report = (event: (typeof customEvents)[number]) => {
+    bkot.reportCustomEvent({ name: event.name, attributes: event.payload });
+    push(`已上报 custom.${event.name}`);
+  };
+
+  const reportFailure = () => {
+    bkot.reportCustomEvent({
+      name: 'order.checkout',
+      attributes: { 'biz.order_id': 'O20260508_FAIL' },
+      error: new Error('库存不足'),
+    });
+    push('已上报失败的 custom.order.checkout（含 exception 事件）', 'warn');
+  };
+
+  const snippet = `bkot.reportCustomEvent({
+  name: 'order.checkout',
+  attributes: { 'biz.order_id': 'O20260508001', 'biz.order_amount': 199 },
+  error: optionalErrorObject,
+});`;
+</script>

package/playground/pages/CustomPluginDemo.vue

@@ -0,0 +1,104 @@
+<template>
+  <section class="demo-page">
+    <header>
+      <h2 class="demo-page__title">自定义插件 · createPlugin</h2>
+      <p class="demo-page__desc">
+        SDK 通过 <code>createPlugin</code> 暴露统一的扩展点。本 playground 在初始化时挂载了一个名为
+        <code>playground-bridge</code> 的演示插件：注入 runtime attributes，并在 window 上暴露
+        <code>__bkotEmitDemoSpan</code> 用于手动产生 span。
+      </p>
+    </header>
+
+    <div class="demo-card">
+      <h3 class="demo-card__title">代码片段</h3>
+      <pre class="demo-snippet">{{ snippet }}</pre>
+    </div>
+
+    <div class="demo-card">
+      <h3 class="demo-card__title">手动触发自定义 span</h3>
+      <p class="demo-card__hint">
+        查看控制台 <code>[bk-ot][traces]</code> 中带 <code>playground.manual=true</code> 的 span。
+      </p>
+      <div class="demo-actions">
+        <input
+          v-model="spanName"
+          class="span-input"
+          placeholder="span 名称"
+        />
+        <button
+          class="demo-btn"
+          :disabled="!spanName.trim()"
+          type="button"
+          @click="emitSpan"
+        >
+          发射 span
+        </button>
+      </div>
+    </div>
+
+    <div class="demo-card">
+      <DemoLogPanel
+        :entries="entries"
+        @clear="clear"
+      />
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+  import { shallowRef } from 'vue';
+
+  import DemoLogPanel from '../components/DemoLogPanel.vue';
+  import { useDemoLog } from '../composables/use-demo-log';
+
+  type EmitDemoSpan = (name?: string) => void;
+
+  const { entries, push, clear } = useDemoLog();
+  const spanName = shallowRef('playground.custom_event');
+
+  const emitSpan = () => {
+    const fn = (globalThis as unknown as { __bkotEmitDemoSpan?: EmitDemoSpan }).__bkotEmitDemoSpan;
+    if (typeof fn !== 'function') {
+      push('__bkotEmitDemoSpan 未注册，请检查 SDK 是否成功启动', 'error');
+      return;
+    }
+    fn(spanName.value.trim());
+    push(`已通过自定义插件发射 span：${spanName.value}`);
+  };
+
+  const snippet = `import { initBkOT, createPlugin, type BkOTPlugin } from '@blueking/open-telemetry';
+
+const myPlugin: BkOTPlugin = createPlugin({
+  name: 'playground-bridge',
+  init(context) {
+    context.setRuntimeAttributes({ 'playground.demo': true });
+
+    // 自定义业务 span / metric / log，统一走 context 提供的 API
+    const span = context.startSpan('boot.bridge_ready', { 'plugin.boot': true });
+    span.end();
+  },
+});
+
+initBkOT({
+  plugins: [myPlugin],
+});`;
+</script>
+
+<style scoped>
+  .span-input {
+    flex: 1;
+    min-width: 200px;
+    padding: 8px 12px;
+    font-family: inherit;
+    font-size: 14px;
+    color: var(--color-text-primary);
+    background: var(--color-bg);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-sm);
+  }
+
+  .span-input:focus {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 1px;
+  }
+</style>

package/playground/pages/ErrorDemo.vue

@@ -0,0 +1,75 @@
+<template>
+  <section class="demo-page">
+    <header>
+      <h2 class="demo-page__title">错误捕获 · error 插件</h2>
+      <p class="demo-page__desc">
+        监听 <code>window.error</code> 与 <code>unhandledrejection</code>，按错误堆栈 hash 节流（默认 60s 内同 hash 最多
+        5 条）。
+      </p>
+    </header>
+
+    <div class="demo-card">
+      <h3 class="demo-card__title">触发错误</h3>
+      <p class="demo-card__hint">触发后查看控制台 <code>[bk-ot][traces]</code> 中 <code>browser.error</code> span。</p>
+      <div class="demo-actions">
+        <button
+          class="demo-btn demo-btn--danger"
+          type="button"
+          @click="throwSync"
+        >
+          同步抛错
+        </button>
+        <button
+          class="demo-btn demo-btn--danger"
+          type="button"
+          @click="throwAsync"
+        >
+          异步 Promise 拒绝
+        </button>
+        <button
+          class="demo-btn demo-btn--warning"
+          type="button"
+          @click="throwBurst"
+        >
+          连续抛 8 次（演示节流）
+        </button>
+      </div>
+    </div>
+
+    <div class="demo-card">
+      <DemoLogPanel
+        :entries="entries"
+        @clear="clear"
+      />
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+  import DemoLogPanel from '../components/DemoLogPanel.vue';
+  import { useDemoLog } from '../composables/use-demo-log';
+
+  const { entries, push, clear } = useDemoLog();
+
+  const throwSync = () => {
+    push('准备触发同步异常', 'warn');
+    // 用 setTimeout 让 error 真正进入 window.error 而不是被 click handler 吞掉
+    setTimeout(() => {
+      throw new Error('Demo: 同步异常 ' + Date.now());
+    }, 0);
+  };
+
+  const throwAsync = () => {
+    push('准备触发未捕获 Promise 拒绝', 'warn');
+    void Promise.reject(new Error('Demo: 未处理 promise rejection ' + Date.now()));
+  };
+
+  const throwBurst = () => {
+    push('一秒内连续抛 8 次相同错误，预期前 5 条上报、后 3 条被节流', 'warn');
+    for (let i = 0; i < 8; i += 1) {
+      setTimeout(() => {
+        throw new Error('Demo: 节流测试错误');
+      }, i * 50);
+    }
+  };
+</script>