@blueking/open-telemetry 0.0.22 → 0.0.24

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

@@ -1,44 +1,330 @@
 <!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
 
-# 传输与采样
+# 上报协议、批处理与采样
 
-## 单一 Endpoint
+本文描述当前源码真正使用的传输链路。SDK 只创建 Trace Provider，不创建 Metric Provider 或 Log Provider；所有 RUM 数据都编码为 Span，并从一个 OTLP/HTTP 入口上报。
 
-`transport.endpoint` 是必填根地址，SDK 去掉末尾斜杠后拼接 `/v1/rum`。没有 `/v1/metrics`、`/v1/logs` 或独立信号开关。
+## 最终请求
+
+```text
+POST <transport.endpoint 去除末尾斜杠>/v1/rum
+Content-Type: application/json
+Authorization: Bearer <transport.token>    # 配置 token 时
+
+<OTLP ExportTraceServiceRequest JSON>
+```
+
+例如 `endpoint: 'https://rum.example.com/collector/'` 最终会请求：
+
+```text
+https://rum.example.com/collector/v1/rum
+```
+
+`endpoint` 是必填的上报根地址。SDK 不支持分别配置 trace、metric、log 地址，也不会自动追加标准 OTLP 的 `/v1/traces`。
+
+请求体的完整层级与字段归属见[RUM 数据模型](./data-model.md)和[遥测字段字典](./telemetry-reference.md)。
+
+### 实际 OTLP JSON 示例
+
+下面是当前 `JsonTraceSerializer` 会生成的真实编码形态。为了让单条请求可读，示例使用 `tracking.device=false`，只放一个没有 Resource Timing 增强字段的成功 Fetch Span；ID 和时间值是示例值，但字段名、枚举数字、Attribute Value 包装和数据类型与当前依赖一致：
+
+```json
+{
+  "resourceSpans": [
+    {
+      "resource": {
+        "attributes": [
+          { "key": "deployment.environment.name", "value": { "stringValue": "production" } },
+          { "key": "service.name", "value": { "stringValue": "order-center" } },
+          { "key": "session.sample_rate", "value": { "intValue": 1 } },
+          { "key": "telemetry.sdk.language", "value": { "stringValue": "webjs" } },
+          { "key": "telemetry.sdk.name", "value": { "stringValue": "@blueking/open-telemetry" } },
+          { "key": "telemetry.sdk.version", "value": { "stringValue": "0.0.22" } }
+        ],
+        "droppedAttributesCount": 0
+      },
+      "scopeSpans": [
+        {
+          "scope": { "name": "bk-rum" },
+          "spans": [
+            {
+              "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+              "spanId": "00f067aa0ba902b7",
+              "name": "browser.resource",
+              "kind": 3,
+              "startTimeUnixNano": "1784592000123000000",
+              "endTimeUnixNano": "1784592000248000000",
+              "attributes": [
+                { "key": "session.id", "value": { "stringValue": "session-01" } },
+                { "key": "session.start_time", "value": { "intValue": 1784592000000 } },
+                { "key": "session.type", "value": { "stringValue": "user" } },
+                { "key": "session.has_replay", "value": { "boolValue": false } },
+                { "key": "view.id", "value": { "stringValue": "view-01" } },
+                { "key": "view.name", "value": { "stringValue": "/orders/:id" } },
+                { "key": "view.url", "value": { "stringValue": "https://app.example.com/orders/123" } },
+                { "key": "view.url_path_group", "value": { "stringValue": "/orders/:id" } },
+                { "key": "view.loading_type", "value": { "stringValue": "initial_load" } },
+                { "key": "span_type", "value": { "stringValue": "resource" } },
+                { "key": "outcome.type", "value": { "stringValue": "success" } },
+                { "key": "resource.type", "value": { "stringValue": "fetch" } },
+                { "key": "http.request.method", "value": { "stringValue": "GET" } },
+                { "key": "http.response.status_code", "value": { "intValue": 200 } },
+                { "key": "url.full", "value": { "stringValue": "https://api.example.com/orders/123" } },
+                { "key": "server.address", "value": { "stringValue": "api.example.com" } }
+              ],
+              "droppedAttributesCount": 0,
+              "events": [],
+              "droppedEventsCount": 0,
+              "status": { "code": 0 },
+              "links": [],
+              "droppedLinksCount": 0,
+              "flags": 257
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Wire 编码注意点：
+
+- `kind=3` 是 OTLP 的 `SPAN_KIND_CLIENT`；INTERNAL 为 `1`；
+- Status `code=0` 是 UNSET，ERROR 为 `2`；
+- `startTimeUnixNano`、`endTimeUnixNano` 和 Event `timeUnixNano` 编码为十进制字符串；
+- Attribute 不是普通扁平对象，而是 `{ key, value }` 数组；value 使用 `stringValue`、`intValue`、`doubleValue`、`boolValue` 或 `arrayValue`；
+- `traceId` 是 32 位十六进制字符串，`spanId` / `parentSpanId` 是 16 位；没有父 Span 时省略 `parentSpanId`；
+- `events` 中的 exception/Long Task Event 也使用同样的 Attribute Value 包装；
+- `flags=257` 是当前 transformer 写出的“本地 sampled Span 且携带 isRemote 有效位”组合值，不要把它当作业务字段；
+- 数组顺序和 Attribute 顺序不应作为 Collector 契约，Collector 应按 key 读取。
+
+发生 Fetch 网络异常时，同一 Span 的 `events` 会采用以下实际形态，并把 `status.code` 设为 `2`：
+
+```json
+{
+  "events": [
+    {
+      "attributes": [
+        { "key": "exception.type", "value": { "stringValue": "TypeError" } },
+        { "key": "exception.message", "value": { "stringValue": "Failed to fetch" } },
+        { "key": "exception.stacktrace", "value": { "stringValue": "TypeError: Failed to fetch\n    at ..." } }
+      ],
+      "name": "exception",
+      "timeUnixNano": "1784592000248000000",
+      "droppedAttributesCount": 0
+    }
+  ],
+  "status": { "code": 2 }
+}
+```
+
+这是 Span 内对应字段的片段，不是独立请求体；exception 字段是否齐全取决于浏览器实际 Error。
+
+## 请求格式
+
+当前使用 `@opentelemetry/exporter-trace-otlp-http@0.217.0` 的浏览器 JSON exporter：
+
+| 项目 | 当前行为 |
+| --- | --- |
+| HTTP 方法 | `POST` |
+| 编码 | OTLP/HTTP JSON |
+| Content-Type | `application/json` |
+| 压缩 | 不压缩 |
+| 浏览器 API | `fetch` |
+| 成功响应 | HTTP `200`–`299`；响应 Body 不解析 |
+| 默认单次导出超时 | `10000ms` |
+| 默认并发导出上限 | `30` |
+
+Collector 至少需要：
+
+1. 接受浏览器发出的 OTLP JSON Trace 请求；
+2. 暴露 SDK 约定的 `/v1/rum` 路径；
+3. 跨域时正确处理 CORS 和预检请求；
+4. 返回 2xx 表示整批接收成功；
+5. 如需限流恢复，返回受支持的重试状态和可选 `Retry-After`。
+
+当前浏览器 transport 只判断 HTTP status，不读取成功或失败响应 Body。2xx 可以返回空 Body；即使返回 OTLP `partialSuccess` JSON，SDK 也不会解析或打印其中的 rejected span 数量。部分拒绝必须由 Collector 自身监控，不能依赖浏览器 SDK 感知。
+
+## 鉴权与自定义请求头
+
+```ts
+transport: {
+  endpoint: 'https://rum.example.com',
+  token: 'report-token',
+  headers: {
+    'X-Tenant-ID': 'tenant-a',
+  },
+}
+```
+
+`token` 会生成默认请求头：
+
+```text
+Authorization: Bearer report-token
+```
+
+`headers` 在合并时优先级更高，因此可以显式覆盖 `Authorization`：
+
+```ts
+transport: {
+  endpoint: 'https://rum.example.com',
+  token: 'will-be-overridden',
+  headers: {
+    Authorization: 'Custom credential',
+  },
+}
+```
+
+不要把长期有效、权限过大的后台密钥写入浏览器。浏览器内的 token 和 header 对访问页面的用户可见，应使用受限的上报凭证，并在服务端限制来源、租户和权限。
+
+## 批处理器
+
+默认 `processor: 'batch'`。结束的 Span 先进入内存队列，满足批量大小、调度延迟，或调用 `flush()` 时导出。
+
+| 配置 | 默认值 | 作用 |
+| --- | ---: | --- |
+| `transport.batch.maxQueueSize` | `2048` | 内存中最多排队的已结束 Span；满后新 Span 被丢弃 |
+| `transport.batch.maxExportBatchSize` | `512` | 一次 export 最多取出的 Span 数 |
+| `transport.batch.scheduledDelayMillis` | `5000` | 未达到批量大小时的最长调度等待 |
+| `transport.batch.exportTimeoutMillis` | `30000` | BatchSpanProcessor 等待一次 export 完成的上限 |
+
+约束与行为：
+
+- `maxExportBatchSize` 大于 `maxQueueSize` 时，OpenTelemetry 会把它降为 `maxQueueSize`；
+- 队列已满时，新结束的 Span 会直接丢弃，不会落盘；
+- 上表是当前 `@opentelemetry/sdk-trace-base@2.7.1` 默认值；浏览器构建通常没有 Node 环境变量，但依赖本身也识别 `OTEL_BSP_*`；
+- `exportTimeoutMillis` 是批处理器等待出口的上限，`transport.timeoutMillis` 是 exporter 请求及重试总期限，两者不是同一个配置。
+
+生产环境通常保留 batch：
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: {
-    endpoint: 'https://collector.example.com',
-    token: 'report-token',
-    processor: 'batch',
-    batch: {
-      maxQueueSize: 2048,
-      maxExportBatchSize: 512,
-      scheduledDelayMillis: 5000,
-      exportTimeoutMillis: 30000,
-    },
-    timeoutMillis: 10_000,
-    concurrencyLimit: 10,
+transport: {
+  endpoint: 'https://rum.example.com',
+  processor: 'batch',
+  timeoutMillis: 10_000,
+  batch: {
+    maxQueueSize: 2048,
+    maxExportBatchSize: 512,
+    scheduledDelayMillis: 5000,
+    exportTimeoutMillis: 30_000,
   },
-});
+}
+```
+
+## SimpleSpanProcessor
+
+`processor: 'simple'` 会在每个 Span 结束后立即触发 export，不经过批量队列：
+
+```ts
+transport: {
+  endpoint: 'https://rum.example.com',
+  processor: 'simple',
+}
+```
+
+它适合本地验证时观察请求，不建议作为高流量页面的默认生产配置。`transport.batch` 在 simple 模式下不会生效。
+
+## 超时、并发与重试
+
+```ts
+transport: {
+  endpoint: 'https://rum.example.com',
+  timeoutMillis: 15_000,
+  concurrencyLimit: 10,
+}
 ```
 
-`token` 生成默认 `Authorization: Bearer <token>`，显式 `headers` 可覆盖它。SDK 在 `pagehide` 和页面进入 hidden 时触发 flush。
+当前 exporter 的默认值和重试规则如下：
+
+| 项目 | 当前行为 |
+| --- | --- |
+| `timeoutMillis` | 默认 `10000ms`，且必须是大于 0 的有限数值 |
+| `concurrencyLimit` | 默认 `30` 个待处理 export Promise |
+| 可重试 HTTP 状态 | `429`、`502`、`503`、`504` |
+| 可重试网络错误 | 浏览器 Fetch 的部分 `TypeError` 网络错误 |
+| 最大重试次数 | 初次请求后最多再尝试 5 次，但不能超过总体超时期限 |
+| 退避 | 初始 1 秒、倍率 1.5、上限 5 秒、±20% jitter |
+| `Retry-After` | 支持秒数或 HTTP 日期；优先于本地退避 |
+
+其余 4xx/5xx 是不可重试失败。即使状态码可重试，如果预计等待时间超过本次 export 剩余期限，也不会继续重试。
+
+这些数值来自当前锁定的 OpenTelemetry exporter，并不是服务端协议字段。升级依赖时需要重新核对本文。
+
+## 页面退出与 keepalive
+
+SDK 在以下时机主动调用 `flush()`：
+
+- `document.visibilityState` 变为 `hidden`；
+- `window.pagehide`；
+- 业务显式调用 `flush()`；
+- 撤销 Consent 时，停止插件后 flush；
+- `shutdown()` 时，停止插件并导出剩余 Span。
 
-## Session 级确定性采样
+浏览器 exporter 在待发送 `keepalive` 请求累计 body 不超过约 60 KiB，且当前少于 9 个 `keepalive` 请求时使用 `fetch(..., { keepalive: true })`；超过限制时仍会发送请求，但关闭 `keepalive`。因此页面退出时的发送是“尽力而为”，不是持久队列或交付保证。
+
+不要把 `flush()` 理解为服务端已经持久化：它只等待 SDK 的插件和 Trace Provider 完成导出调用；浏览器终止、网络中断、CORS 拒绝或服务端失败仍可能造成丢失。
+
+## Session 采样
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  session: { sampleRate: 0.05 },
-});
-```
-
-- `1` 表示全量，`0` 表示全部丢弃。
-- 采样由 `application.name + session.id` 的稳定 hash 决定。
-- Session 轮换后使用新 ID 重新计算。
-- `session.sample_rate` 写入 Resource，供后端做采样率修正。
-- 未采样 Session 不创建可导出的 RUM Span。
+session: {
+  sampleRate: 0.2,
+}
+```
+
+`sampleRate`：
+
+- 范围是 `0`–`1`，默认 `1`；
+- 非有限数值回退为 `1`，小于 0 截为 0，大于 1 截为 1；
+- 以 `application.name + session.id` 计算稳定 hash；
+- 同一 Session 内的所有 SDK RUM Span 使用相同采样决定；
+- Session 轮换后会重新计算；
+- 采样率作为 Resource 属性 `session.sample_rate` 一并上报。
+
+未命中采样时：
+
+- `startSpan()` 返回 non-recording Span；
+- `reportAction()`、`reportCustomEvent()`、手动 View 控制不会产生可导出数据；
+- SDK 仍需运行 Session 生命周期逻辑以建立稳定的采样边界；
+- 不会先创建完整 Span 再在网络层抽样。
+
+排查“手动事件没有上报”时，先暂时设置 `sampleRate: 1`。
+
+## 导出前过滤
+
+一个已结束 Span 还需要通过 `FilteringSpanProcessor` 才会进入 simple/batch processor。以下数据会被丢弃：
+
+- 没有命中当前 Session 采样；
+- 没有关联有效 Session；
+- 除 `browser.session` 外，没有关联有效 View；
+- 命中 SDK 自身的 `/v1/rum` 上报地址；
+- 被内部插件标记为丢弃；
+- 被全局 `tracking.beforeSend` 返回 `false` 拒绝。
+
+过滤层会在 Span 创建时补齐缺失的运行时和页面属性；Span 结束时执行上述过滤，并在交给 exporter 前移除仅供内部使用的采样标记。详细顺序见[架构与数据流](./architecture.md)。
+
+## CORS 基线
+
+跨域 Collector 至少需要允许：
+
+```text
+Access-Control-Allow-Origin: https://your-web-app.example.com
+Access-Control-Allow-Methods: POST, OPTIONS
+Access-Control-Allow-Headers: content-type, authorization, x-tenant-id
+```
+
+实际 header 清单以你的 `transport.headers` 为准。上报 CORS 与业务接口注入 `traceparent` 的 CORS 是两件事：前者影响 `/v1/rum` 数据能否发送，后者影响被观测 API 请求能否携带分布式追踪头。
+
+## Collector 验收清单
+
+联调时逐项确认：
+
+1. Network 面板中真实 URL 是 `<endpoint>/v1/rum`，没有重复路径；
+2. 预检和 POST 都成功，返回 2xx；
+3. 请求体顶层是 `resourceSpans`，其中是 Span 而非 metric/log；
+4. Collector 能读取 JSON 形式的 `traceId`、`spanId`、纳秒时间戳和 attributes；
+5. Collector 不依赖 SDK 从浏览器发送聚合计数、错误指纹或地理位置；
+6. 429/503 场景能返回合理 `Retry-After`，且不会诱导客户端超长等待；
+7. token 只能用于 RUM 写入，不能读取或管理后台数据；
+8. 服务端按 `service.name`、环境和租户做权限与路由校验。