@blueking/open-telemetry 0.0.21 → 0.0.22-beta.1

package/skills/bk-rum-otele/references/transport-sampling.md

@@ -2,9 +2,9 @@
 
 # 传输与采样
 
-## Endpoint
+## 单一 Endpoint
 
-`transport.endpoint` 是可选根地址。未配置独立地址的已开启信号会基于它生成 `/v1/rum`、`/v1/metrics`、`/v1/logs`；单信号 `endpoint` 是完整 URL，不再拼接路径。
+`transport.endpoint` 是必填根地址，SDK 去掉末尾斜杠后拼接 `/v1/rum`。没有 `/v1/metrics`、`/v1/logs` 或独立信号开关。
 
 ```ts
 new BkOpenTelemetry({
@@ -12,54 +12,20 @@ new BkOpenTelemetry({
   transport: {
     endpoint: 'https://collector.example.com',
     token: 'report-token',
-    signals: {
-      traces: {
-        endpoint: 'https://trace.example.com/v1/rum',
-        processor: 'batch',
-        batch: {
-          maxQueueSize: 2048,
-          maxExportBatchSize: 512,
-          scheduledDelayMillis: 5000,
-          exportTimeoutMillis: 30000,
-        },
-      },
-      metrics: { endpoint: 'https://metric.example.com/v1/metrics', intervalMillis: 60_000 },
-      logs: { endpoint: 'https://log.example.com/v1/logs' },
+    processor: 'batch',
+    batch: {
+      maxQueueSize: 2048,
+      maxExportBatchSize: 512,
+      scheduledDelayMillis: 5000,
+      exportTimeoutMillis: 30000,
     },
+    timeoutMillis: 10_000,
+    concurrencyLimit: 10,
   },
 });
 ```
 
-## 独立信号开关
-
-三类信号默认全部开启。设为 `false` 时，不创建对应 exporter、processor 或 metric reader：
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'trace-only-demo' },
-  transport: {
-    signals: {
-      traces: { endpoint: 'https://trace.example.com/v1/rum' },
-      metrics: false,
-      logs: false,
-    },
-  },
-});
-```
-
-校验规则：
-
-- 至少开启一种信号，三类不能全部为 `false`。
-- 每个开启信号必须有独立 endpoint，或能回退到根 `transport.endpoint`。
-- 关闭 Trace 后不记录 Span，也不会向 `allowedTracingUrls` 注入 `traceparent`。
-- 关闭 Metric 后不启动周期导出定时器。
-- 关闭 Log 不影响 Session/View 上下文维护，但不会产生 Session、View Snapshot、HTTP body 等 Log。
-
-只开启 Metric 时没有精确 `view.id` 下钻链路；需要从指标定位具体 View 时，至少开启 Trace。
-
-请求头优先级：`token` 生成的 Authorization < `transport.headers` < 单 signal `headers`。
-
-浏览器 OTLP HTTP exporter 负责实际传输，SDK 在 `pagehide` 和页面进入 hidden 时触发 flush。`shutdown()` 会先结束 View 和插件，再 flush final Snapshot，最后关闭 provider。
+`token` 生成默认 `Authorization: Bearer <token>`，显式 `headers` 可覆盖它。SDK 在 `pagehide` 和页面进入 hidden 时触发 flush。
 
 ## Session 级确定性采样
 
@@ -72,8 +38,7 @@ new BkOpenTelemetry({
 ```
 
 - `1` 表示全量，`0` 表示全部丢弃。
-- 决定由 `application.name + session.id` 的稳定 hash 得出。
-- 采样决定不写额外 storage；同一 Session 内 span/log/metric 决定一致。
-- Session 续期后使用新 ID 重新计算。
-
-Metric exporter 只接受带内部采样标记的数据点，并在传输前移除该标记。Metric 只保留低基数 `view.url_path_group`，精确 View 关联由 span/log/View Snapshot 的 `view.id` 提供。
+- 采样由 `application.name + session.id` 的稳定 hash 决定。
+- Session 轮换后使用新 ID 重新计算。
+- `session.sample_rate` 写入 Resource，供后端做采样率修正。
+- 未采样 Session 不创建可导出的 RUM Span。

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

@@ -17,9 +17,7 @@ new BkOpenTelemetry({
   },
   transport: {
     endpoint: 'http://localhost:4318',
-    signals: {
-      traces: { processor: 'simple' },
-    },
+    processor: 'simple',
   },
 });
 ```
@@ -27,7 +25,7 @@ new BkOpenTelemetry({
 检查点：
 
 - Collector 是否监听 `4318`。
-- 浏览器 Network 中是否有 `/v1/rum`、`/v1/metrics`、`/v1/logs` 请求。
+- 浏览器 Network 中是否有 `/v1/rum` 请求。
 - 是否被采样丢弃。
 - `enabled` 是否为 `false`。
 
@@ -131,28 +129,9 @@ new BkOpenTelemetry({
 });
 ```
 
-## HTTP body 没有数据
-
-请求/响应 body 默认关闭。需要采集时配置 `tracking.request.body`，并提供必填的 `redact`：
-
-```ts
-new BkOpenTelemetry({
-  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":"***"'),
-      },
-    },
-  },
-});
-```
+## HTTP Body 没有数据
 
-`capture` 默认就是 `errors`，成功请求不会产生 body Log；要采集成功请求需显式设为 `all`。如果仍然没有数据，依次检查 Content-Type 是否命中 `allowedContentTypes`、body 是否为支持的文本类型，以及 `redact` 是否返回了 `undefined`。FormData、ArrayBuffer 和二进制响应会跳过。
+这是预期行为：SDK 不读取或上报请求/响应 Body。
 
 ## WebSocket 采集异常
 
@@ -231,22 +210,16 @@ bkOT.reportAction({
 
 ## 可以只上报 traces，不上报 metrics/logs 吗？
 
-可以。将不需要的信号设为 `false`；根 endpoint 在所有已开启信号都配置独立地址时可以省略。
+SDK 固定只上报 RUM Trace，不创建 Metrics/Logs Provider，无需配置开关。
 
 ```ts
 new BkOpenTelemetry({
   application: { name: 'demo' },
-  transport: {
-    signals: {
-      traces: { endpoint: 'https://trace-gateway.example.com/v1/rum' },
-      metrics: false,
-      logs: false,
-    },
-  },
+  transport: { endpoint: 'https://trace-gateway.example.com' },
 });
 ```
 
-三类信号不能全部关闭。关闭 Trace 后也不会注入 `traceparent`。
+Endpoint 会解析为 `https://trace-gateway.example.com/v1/rum`。
 
 ## 为什么不建议多个实例同时运行？
 

package/dist/core/metric.d.ts

@@ -1,2 +0,0 @@
-export declare const CLS_HISTOGRAM_BOUNDARIES: number[];
-export declare const DURATION_HISTOGRAM_BOUNDARIES: number[];

package/dist/core/signal.d.ts

@@ -1,3 +0,0 @@
-import type { BkOTRuntimeContext } from './plugin';
-export type BkOTSignal = 'logs' | 'metrics' | 'traces';
-export declare const shouldRecordSignal: (context: BkOTRuntimeContext, signal: BkOTSignal) => boolean;

package/dist/core/throttle.d.ts

@@ -1,20 +0,0 @@
-/**
- * 简易 djb2 字符串 hash。结果稳定、短（base36），足以区分常见 fingerprint 字符串组合。
- * 不是密码学安全 hash，仅用于事件聚合分组场景。
- */
-export declare const hashString: (input: string) => string;
-export interface ThrottleResult {
-    /** 是否允许本次上报 */
-    allowed: boolean;
-    /** 当前窗口内同 fingerprint 的触发序号（含本次） */
-    count: number;
-}
-/**
- * 时间窗节流：同一 key 在 windowMs 窗口内最多允许 maxPerWindow 次通过；
- * 超出则被拦截，但 `count` 仍累加，供调用方维护内部统计。
- *
- * 长会话场景下避免 records 无限累积——按窗口长度节奏轻量清理一次过期 entry。
- */
-export declare const createThrottle: (windowMs: number, maxPerWindow: number) => {
-    allow(key: string): ThrottleResult;
-};

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

@@ -1,15 +0,0 @@
-import type { BkOTRequestBodyConfig, BkOTRequestContext, BkOTRequestEvent } from '../core/config';
-import type { BkOTRuntimeContext } from '../core/plugin';
-import type { Span } from '@opentelemetry/api';
-interface CaptureRequestBodyLogOptions {
-    bodyConfig: BkOTRequestBodyConfig;
-    domainContext: BkOTRequestContext;
-    event: BkOTRequestEvent;
-    fetchRequest?: Request | RequestInit;
-    occurredAt?: number;
-    runtimeContext: Pick<BkOTRuntimeContext, 'emitLog'>;
-    span: Span;
-}
-export declare const prepareFetchRequestBodySource: (request: Request | RequestInit) => Request | RequestInit | undefined;
-export declare const captureRequestBodyLog: ({ bodyConfig, domainContext, event, fetchRequest, occurredAt, runtimeContext, span, }: CaptureRequestBodyLogOptions) => Promise<void>;
-export {};