@blueking/open-telemetry 0.0.14 → 0.0.16

package/skills/bk-rum-otele/references/troubleshooting.md

@@ -10,13 +10,16 @@
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
   debug: true,
-  spanProcessor: 'simple',
-  sampling: {
-    rate: 1,
+  session: {
+    sampleRate: 1,
   },
   transport: {
     endpoint: 'http://localhost:4318',
+    signals: {
+      traces: { processor: 'simple' },
+    },
   },
 });
 ```
@@ -34,10 +37,12 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
   debug: true,
-  sampling: {
-    rate: 1,
+  session: {
+    sampleRate: 1,
   },
+  transport: { endpoint: 'https://rum-collector.example.com' },
 });
 ```
 
@@ -47,7 +52,9 @@ new BkOpenTelemetry({
 
 ```ts
 const bkOT = new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
   autoStart: false,
+  transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
 bkOT.use(myPlugin);
@@ -61,7 +68,9 @@ SPA 应用应配置 `rootSelector` 和 loading/skeleton 忽略选择器。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     blankScreen: {
       rootSelector: '#app',
       ignoreSelectors: ['.bk-loading', '.skeleton'],
@@ -73,13 +82,16 @@ new BkOpenTelemetry({
 
 ## 接口 span 太多
 
-先确认是否有多个 SDK 实例重复初始化，尤其是微前端场景。其次可以关闭不需要的 instrumentation。
+先确认是否有多个 SDK 实例重复初始化，尤其是微前端场景。其次用 `excludedUrls` 排除探活或高频无价值请求。
 
 ```ts
 new BkOpenTelemetry({
-  instrumentations: {
-    fetch: true,
-    xhr: false,
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
+    request: {
+      excludedUrls: [/\/health(?:\?|$)/, /\/polling\//],
+    },
   },
 });
 ```
@@ -90,6 +102,8 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
   privacy: {
     redactUrl: url => url.replace(/([?&]token=)[^&]+/g, '$1***'),
     redactAttributes: attributes => {
@@ -107,7 +121,9 @@ Long Task API 并非所有浏览器都支持。Firefox 不支持时插件会跳
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     longTask: {
       threshold: 50,
     },
@@ -117,26 +133,36 @@ new BkOpenTelemetry({
 
 ## HTTP body 没有数据
 
-`httpBody` 只在错误路径采集，且默认关闭。
+请求/响应 body 默认关闭。需要采集时配置 `tracking.request.body`，并提供必填的 `redact`：
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
-    httpBody: {
-      maxBodySize: 4096,
-      redact: ({ body }) => body,
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
+    request: {
+      body: {
+        capture: 'errors',
+        allowedContentTypes: ['application/json'],
+        maxSize: 10 * 1024,
+        redact: ({ body }) => body.replace(/"password"\s*:\s*"[^"]+"/g, '"password":"***"'),
+      },
     },
   },
 });
 ```
 
+`capture` 默认就是 `errors`，成功请求不会产生 body Log；要采集成功请求需显式设为 `all`。如果仍然没有数据，依次检查 Content-Type 是否命中 `allowedContentTypes`、body 是否为支持的文本类型，以及 `redact` 是否返回了 `undefined`。FormData、ArrayBuffer 和二进制响应会跳过。
+
 ## WebSocket 采集异常
 
 WebSocket 插件会 Proxy 全局 `WebSocket`。如果应用或第三方库也 patch 了 WebSocket，应避免重复 patch。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     websocket: true,
   },
 });
@@ -146,14 +172,15 @@ new BkOpenTelemetry({
 
 ## SDK 会采集哪些数据？
 
-默认采集页面访问、资源加载、fetch/xhr、JavaScript 错误、Web Vitals、空白屏、设备信息和会话信息。动作、HTTP body、Long Task、路由耗时、CSP、WebSocket 默认关闭。
+默认采集页面访问与稳定耗时、用户动作、资源加载、fetch/xhr、JavaScript 错误、Web Vitals、空白屏、设备信息和会话信息。HTTP body、Long Task、CSP、WebSocket 默认关闭。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     action: true,
     longTask: true,
-    routeTiming: true,
     websocket: true,
   },
 });
@@ -165,32 +192,37 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
-  user: {
-    id: hashUserId(rawUserId),
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  context: {
+    user: {
+      id: hashUserId(rawUserId),
+    },
   },
 });
 ```
 
-## `sampling.rate` 是 trace 级采样吗？
+## `session.sampleRate` 是 trace 级采样吗？
 
-不是。它是会话级 sticky 采样，同一会话内保持一致。
+不是。它是会话级确定性采样，同一会话内保持一致。
 
 ```ts
 new BkOpenTelemetry({
-  sampling: {
-    rate: 0.2,
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  session: {
+    sampleRate: 0.2,
   },
 });
 ```
 
-## 为什么开启了 userInteraction 还需要 action 插件？
+## 为什么不使用 OpenTelemetry userInteraction instrumentation？
 
-`userInteraction` 是 OpenTelemetry 官方 instrumentation，产生的是官方用户交互 span；`action` 插件和 `reportAction()` 会写入 SDK 的 RUM action 归一字段。需要稳定的业务动作模型时，推荐使用 `action` 或 `reportAction()`。
+官方 userInteraction instrumentation 主要用于把交互回调中的异步任务组织成 trace，但没有稳定的 RUM action 语义、动作命名、页面活动窗口和关联计数。本 SDK 统一使用 `action` 插件，避免同一次点击重复上报；内置 request 采集统一负责 Fetch/XHR 网络 trace。
 
 ```ts
 bkOT.reportAction({
-  type: 'click',
-  targetText: '确认提交',
+  name: '确认提交',
   attributes: {
     'biz.scene': 'strategy-create',
   },
@@ -199,29 +231,31 @@ bkOT.reportAction({
 
 ## 可以只上报 traces，不上报 metrics/logs 吗？
 
-当前 SDK 会初始化三类 provider。可以在 Collector 或网关层按信号丢弃，也可以为不同信号配置不同 endpoint。
+可以。将不需要的信号设为 `false`；根 endpoint 在所有已开启信号都配置独立地址时可以省略。
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'demo' },
   transport: {
     signals: {
-      endpoints: {
-        traces: 'https://trace-gateway.example.com/v1/rum',
-        metrics: 'https://metric-gateway.example.com/v1/metrics',
-        logs: 'https://log-gateway.example.com/v1/logs',
-      },
+      traces: { endpoint: 'https://trace-gateway.example.com/v1/rum' },
+      metrics: false,
+      logs: false,
     },
   },
 });
 ```
 
+三类信号不能全部关闭。关闭 Trace 后也不会注入 `traceparent`。
+
 ## 为什么不建议多个实例同时运行？
 
-fetch、xhr、userInteraction、websocket 等能力会 patch 全局 API。多个实例可能重复 patch、重复上报或互相影响。
+fetch、xhr、action、websocket 等能力会监听或 patch 全局 API。多个实例可能重复采集、重复上报或互相影响。
 
 ```ts
 if (!window.__BK_RUM_INSTANCE__) {
   window.__BK_RUM_INSTANCE__ = new BkOpenTelemetry({
+    application: { name: 'demo' },
     transport: {
       endpoint: 'https://rum-collector.example.com',
     },

package/dist/plugins/http-body.d.ts

@@ -1,3 +0,0 @@
-import type { BkOTHttpBodyConfig } from '../core/config';
-import type { BkOTPlugin } from '../core/plugin';
-export declare const createHttpBodyPlugin: (options?: BkOTHttpBodyConfig) => BkOTPlugin;

package/dist/plugins/route-timing.d.ts

@@ -1,2 +0,0 @@
-import type { BkOTPlugin } from '../core/plugin';
-export declare const createRouteTimingPlugin: () => BkOTPlugin;