@sanseng/liveavatar-js-sdk-skywalking 1.0.1 → 1.1.0

package/README.md

@@ -1,11 +1,15 @@
 # LiveAvatar SkyWalking Plugin
 
+[中文](README.zh-CN.md)
+
 `@sanseng/liveavatar-js-sdk-skywalking` connects LiveAvatar client diagnostics to SkyWalking. It bundles SkyWalking js-sdk `1.1.27`, so applications do not need to add a script tag or directly call `window.ClientMonitor.register(...)`.
 
 ## What it solves
 
-- Reports SDK-generated LiveAvatar A/V Sync alert lifecycles with compact, causally ordered diagnostic evidence for investigation in SkyWalking.
-- Reports qualifying SDK Operational Log errors without uploading the original error message, stack, token, or business payload.
+- Reports SDK-generated LiveAvatar A/V Sync alert lifecycles with complete v2 diagnostic evidence in lossless text fragments for investigation in SkyWalking.
+- Reports the SDK’s single `sdk.failure` fact with captured context; operation outcomes retain references to that failure.
+- Reports an allowlisted session timeline covering configuration, connection, RTC state, media, conversation and shutdown.
+- Samples the complete public playback status immediately after connection and every 5 seconds until RTC disconnects, with immediate SkyWalking dispatch.
 - Reports every terminal `performance.first-frame` Operational Log, including success, connection failure, and first-frame timeout.
 - Adds observability through the public LiveAvatar Plugin API v1, without subscribing to legacy SDK events or using SDK internals.
 - Bundles and registers a browser SkyWalking client when one has not already been supplied by the application.
@@ -13,7 +17,7 @@
 ## Quick start
 
 ```sh
-npm install @sanseng/liveavatar-js-sdk @sanseng/liveavatar-js-sdk-skywalking
+npm install @sanseng/liveavatar-js-sdk@^2.6.0 @sanseng/liveavatar-js-sdk-skywalking@1.1.0
 ```
 
 ```ts
@@ -28,7 +32,7 @@ const client = createClient({
 });
 ```
 
-The plugin registers SkyWalking during client setup. SDK errors, terminal first-frame logs, and SDK-generated A/V Sync alerts are all reported by default. Its service is always `yy-tx::liveavatar-js-sdk`; it cannot be configured. If `window.ClientMonitor` already exists, the plugin treats it as externally registered and never overwrites or registers it. The bundled client registers only once per page; later differing configurations are ignored with a console warning.
+The plugin registers SkyWalking during client setup. SDK errors, terminal first-frame logs, SDK-generated A/V Sync alerts, the session timeline, and playback status are all reported by default. Its service is always `yy-tx::liveavatar-js-sdk`; it cannot be configured. If `window.ClientMonitor` already exists, the plugin treats it as externally registered and never overwrites or registers it. The bundled client registers only once per page; later differing configurations are ignored with a console warning.
 
 Enable SDK A/V Sync diagnostics only when automatic A/V Sync alerts and their evidence are needed. When it is disabled, the SDK produces no automatic A/V Sync alerts, so the plugin does not query A/V telemetry or send A/V logs:
 
@@ -48,12 +52,51 @@ Use `reporting` to disable individual automatic report types; every type default
 
 ```ts
 createSkyWalkingPlugin({
-  reporting: { sdkError: true, firstFrame: false, avSync: true },
+  reporting: {
+    sdkError: true,
+    firstFrame: false,
+    avSync: true,
+    timeline: true,
+    playbackStatus: true,
+  },
 });
 ```
 
-When all three report types are `false`, the plugin does not initialize SkyWalking or subscribe to SDK extension points.
+When all five report types are `false`, the plugin does not initialize SkyWalking or subscribe to SDK extension points.
+
+Playback status is controlled independently by `reporting.playbackStatus` (default `true`); `playbackStatusIntervalMs` defaults to `5000`. It starts with an immediate sample, pauses during reconnect, and stops on actual RTC disconnect, session end or disposal. Most metrics need no debug; unavailable values remain `null`. See [playback status](api.en.md#playback-status) for fields and cancellation behavior.
+
+Each SDK `performance.first-frame` Operational Log produces one SkyWalking structured log through `reportFrameErrors` with a one-millisecond dispatch timeout. “First frame” means the SDK-owned private video element reached `loadeddata`; it does not claim that pixels have already appeared in the application's visible UI. See the [API reference](api.en.md#first-frame-log) for outcomes, payload fields, and omission rules.
+
+Plugin **1.1.0** requires LiveAvatar SDK **2.6.0** or a compatible later 2.x release (peer range `^2.6.0`); development and release checks use the published SDK pinned to `2.6.0`. Logging uses `SDK_OPERATIONAL_LOGS_V2` and `SDK_AVSYNC_DIAGNOSTICS_V2`; playback sampling separately uses `SDK_AVSYNC_DIAGNOSTICS_V1.getPlaybackStatus()`. Plugin API remains v1. Upgrade the plugin with the SDK.
+
+Query `content.clientInstanceId + content.monitoringSessionId` for a monitoring session. Parse `content.error` for the v2 error, operation and captured snapshot. Auth uses `serverSessionId`; diagnostic segments use `avsyncSessionId`. Source eventId/streamId are opaque; sort sequence only within a stream. See the [API reference](api.en.md#session-timeline-and-correlation).
+
+The plugin opts into synchronous pending-observer handoff before SDK disposal. Playback samples, errors, first-frame reports, monitoring-session end and client disposal use `timeout: 1`; ordinary timeline records use the configured batch delay. Handoff to ClientMonitor and XHR dispatch do not confirm server ingestion. No persistence or page-exit delivery guarantee is added.
+
+## Upgrade to 1.1.0
+
+Although published as a minor version, **1.1.0 includes incompatible changes**. Upgrade applications and log consumers together:
+
+- Upgrade LiveAvatar SDK to at least `2.6.0`. Logging and A/V evidence use v2 extension points; public Plugin API stays v1.
+- Automatic payloads use `schemaVersion: 4`; older payload schemas and compact A/V evidence formats are unsupported. Update queries and evidence reconstruction accordingly.
+- Session timeline and playback status reporting are enabled by default. Playback status is sampled immediately on connection and every 5 seconds; disable them with `reporting.timeline` and `reporting.playbackStatus` when needed.
+- Remove `SkyWalkingPluginConfig.serviceVersion`. Registration and automatic reports use the SDK exported `VERSION`; outer `sdkVersion` still identifies the SkyWalking client. Manual frame-error helper parameters remain caller-controlled.
+
+## Capability boundaries
+
+Registration and automatic reports use SDK `VERSION` as outer `serviceVersion`; outer `sdkVersion` identifies SkyWalking `v1.1.27`. Every automatic content uses **schemaVersion 4**; SDK source records remain version 2. Old payloads are unsupported. Manual helpers still forward caller parameters.
+
+A/V evidence preserves complete SDK pages without sampling or v1 telemetry stitching. The whole document becomes reconstructable `chunk.data` text fragments; oversized records and metadata split without field loss. Each final content JSON stays within **28 KiB** and third-level containers become JSON strings to limit field expansion. Verify fragments, bytes and source coverage before analysis. See [A/V payloads](api.en.md#av-sync-alerts).
+
+The SDK owns failure merging; the plugin owns v2 subscriptions, allowlisted projection and lossless framing; SkyWalking owns transport; the server owns ingestion and indexing. ClientMonitor handoff is not delivery acknowledgment. Production ingestion and searchability require separate platform acceptance. See [capability boundaries (Chinese)](docs/capability-boundaries.md).
 
-Each SDK `performance.first-frame` Operational Log produces one SkyWalking structured log through `reportFrameErrors` with a one-millisecond dispatch timeout. “First frame” means the SDK-owned private video element reached `loadeddata`; it does not claim that pixels have already appeared in the application's visible UI. See the [API reference](docs/api.en.md#first-frame-log) for outcomes, payload fields, and omission rules.
+## Documentation
 
-The package requires `@sanseng/liveavatar-js-sdk` `^2.4.0`.
+| Document                                                                                                                        | Contents                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| [English API](api.en.md) / [中文 API](api.md)                                                                                   | Configuration, exports, report payloads, and runtime behavior.                                       |
+| [Project knowledge graph (Chinese)](docs/knowledge-graph.md)                                                                    | Module relationships, event and identity flows, development tasks, tests, and troubleshooting paths. |
+| [Reported events and fields (Chinese)](skywalking-reported-events.zh-CN.md)                                                     | Event meanings, triggers, and correlation fields.                                                    |
+| [A/V Sync platform analysis guide](.agents/skills/skywalking-log-analysis/references/skywalking-avsync-platform-analysis.en.md) | Evidence completeness checks and A/V Sync investigation.                                             |
+| [Maintenance index](docs/README.md) / [Capability boundaries](docs/capability-boundaries.md)                                    | Known issues, optimizations, future plans, and responsibilities; both in Chinese.                    |

package/README.zh-CN.md

@@ -0,0 +1,102 @@
+# LiveAvatar SkyWalking 插件
+
+[English](README.md)
+
+`@sanseng/liveavatar-js-sdk-skywalking` 将 LiveAvatar 客户端诊断数据接入 SkyWalking。插件内置 SkyWalking js-sdk `1.1.27`，应用无需额外添加脚本标签，也无需直接调用 `window.ClientMonitor.register(...)`。
+
+## 可解决的问题
+
+- 将 SDK 产生的 A/V Sync 告警和完整 v2 证据无损分片上报到 SkyWalking，支持平台侧排障。
+- 上报 SDK 唯一 sdk.failure 及捕获现场，操作结果保留失败引用；同次失败的合并由 SDK 负责。
+- 上报配置、连接、RTC 状态、媒体、问答与结束过程的关键会话时间线。
+- 连接成功后立即获取完整公开播放状态，随后每 5 秒采样并立即发送，RTC 实际断开后停止。
+- 上报每个 SDK `performance.first-frame` Operational Log 终态，包括成功、连接失败和首帧超时。
+- 通过公开的 LiveAvatar Plugin API v1 添加观测能力，不订阅旧 SDK 事件，也不依赖 SDK 内部实现。
+- 当应用未提供 SkyWalking 客户端时，自动加载并注册内置的浏览器 SkyWalking 客户端。
+
+## 快速接入
+
+```sh
+npm install @sanseng/liveavatar-js-sdk@^2.6.0 @sanseng/liveavatar-js-sdk-skywalking@1.1.0
+```
+
+```ts
+import { createClient } from "@sanseng/liveavatar-js-sdk";
+import { createSkyWalkingPlugin } from "@sanseng/liveavatar-js-sdk-skywalking";
+
+const client = createClient({
+  plugins: [createSkyWalkingPlugin()],
+  connectConfig: {
+    // 正常的 LiveAvatar 连接配置。
+  },
+});
+```
+
+插件会在客户端 setup 期间注册 SkyWalking。SDK error、终态首帧日志、SDK 产生的 A/V Sync 告警、关键会话时间线及播放状态默认都会上报。其 service 固定为 `yy-tx::liveavatar-js-sdk`，不能配置。若页面已有 `window.ClientMonitor`，插件会将其视为已由应用注册，不会覆盖或再次注册。内置客户端每个页面只注册一次；后续传入不同配置会被忽略并输出控制台警告。
+
+仅在需要自动 A/V Sync 告警及其证据时开启 SDK A/V Sync 诊断。未开启时 SDK 不会产生自动 A/V Sync 告警，插件也不会查询 A/V 遥测或发送 A/V 日志：
+
+```ts
+const client = createClient({
+  debug: { avSync: { enabled: true } },
+  plugins: [createSkyWalkingPlugin()],
+  connectConfig: {
+    // 正常的 LiveAvatar 连接配置。
+  },
+});
+```
+
+## 上报类型控制
+
+使用 `reporting` 控制各自动上报类型；五个类型默认均为 `true`：
+
+```ts
+createSkyWalkingPlugin({
+  reporting: {
+    sdkError: true,
+    firstFrame: false,
+    avSync: true,
+    timeline: true,
+    playbackStatus: true,
+  },
+});
+```
+
+五个上报类型都为 `false` 时，插件不会初始化 SkyWalking，也不会订阅 SDK 扩展点。
+
+播放状态由 `reporting.playbackStatus` 独立控制，默认开启；`playbackStatusIntervalMs` 默认 `5000` 毫秒。连接成功时立即采样，重连期间暂停，RTC 实际断开、会话结束或销毁后停止。多数指标无需 debug，不可用值保留为 `null`。字段与取消规则见[播放状态 API](api.md#播放状态)。
+
+每条 SDK `performance.first-frame` Operational Log 都会通过 `reportFrameErrors` 产生一条 SkyWalking 结构化日志，并使用一毫秒发送延迟。“首帧”指 SDK 私有 video 元素触发 `loadeddata`，不表示用户可见界面已完成像素呈现。outcome、字段和省略规则请见 [API 参考](api.md#首帧日志)。
+
+插件 **1.1.0** 最低要求 LiveAvatar SDK **2.6.0**，peer 范围为 `^2.6.0`；开发与发布检查固定使用正式发布包 `2.6.0`。日志使用 `SDK_OPERATIONAL_LOGS_V2` 和 `SDK_AVSYNC_DIAGNOSTICS_V2`，播放状态单独使用 `SDK_AVSYNC_DIAGNOSTICS_V1.getPlaybackStatus()`，Plugin API 仍为 v1。插件需与 SDK 一起升级。
+
+通过 `content.clientInstanceId + content.monitoringSessionId` 查监控会话；解析 `content.error` 查看 v2 失败记录的 error、operation、snapshot。Auth 使用 `serverSessionId`，媒体诊断段使用 `avsyncSessionId`。源 eventId/streamId 不透明，sequence 只在同一 stream 内排序。见 [API 参考](api.md#会话时间线与关联)。
+
+插件选择加入 SDK dispose 前的 pending Observer 同步交接。播放状态、错误、首帧、监控会话结束和实例销毁使用 `timeout: 1`，普通时间线沿用批量延迟。交给 ClientMonitor 与 XHR 已发送均不代表服务端已入库；本次不增加持久化队列或页面退出送达保证。
+
+## 升级到 1.1.0
+
+本次采用次版本号，但 **1.1.0 包含不兼容变化**，应用与日志消费端需一起升级：
+
+- LiveAvatar SDK 升级到至少 `2.6.0`。日志和 A/V 证据使用 v2 扩展点，公开 Plugin API 保持 v1。
+- 自动载荷统一为 `schemaVersion: 4`，不支持旧载荷 schema 和旧紧凑 A/V 证据格式，需同步调整查询与证据重组。
+- 会话时间线和播放状态默认开启；播放状态连接成功立即采样，随后每 5 秒采样。可通过 `reporting.timeline` 和 `reporting.playbackStatus` 关闭。
+- 移除 `SkyWalkingPluginConfig.serviceVersion`；注册与自动上报使用 SDK 导出的 `VERSION`，外层 `sdkVersion` 仍标识 SkyWalking 客户端。手动 frame-error 辅助接口仍由调用者传入参数。
+
+## 能力边界
+
+注册和自动上报的外层 `serviceVersion` 固定为 SDK `VERSION`；外层 `sdkVersion` 标识 SkyWalking 客户端 `v1.1.27`。所有自动 content 均为 **schemaVersion 4**，SDK 源记录仍为版本 2；不兼容旧载荷。手动辅助接口继续透传调用参数。
+
+A/V 证据保存完整 SDK 返回页，不再抽样压缩或拼接 v1 遥测。整个文档拆成可重组的 `chunk.data` 文本，单条超大记录和元数据也无损拆片；每条最终 content JSON 均不超过 **28 KiB**，并在第三级编码容器，避免继续展开字段。分析前须校验分片总数、顺序、字节数和源完整性。详见 [A/V 载荷](api.md#av-sync-告警)。
+
+SDK 负责失败合并，插件负责 v2 订阅、白名单投影和无损分片，SkyWalking 客户端负责传输，服务端负责入库及索引。ClientMonitor 交接不证明线上送达；生产入库和服务端可检索性需另行平台验收。参见[能力边界](docs/capability-boundaries.md)。
+
+## 文档导航
+
+| 文档                                                                                                              | 说明                                                     |
+| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| [中文 API 参考](api.md) / [English API](api.en.md)                                                                | 配置、导出接口、上报载荷及运行行为。                     |
+| [项目知识图谱](docs/knowledge-graph.md)                                                                           | 模块关系、事件与身份链路、开发修改、测试入口及排障路径。 |
+| [上报事件与字段](skywalking-reported-events.zh-CN.md)                                                             | 事件含义、触发条件和查询关联字段。                       |
+| [A/V Sync 平台分析手册](.agents/skills/skywalking-log-analysis/references/skywalking-avsync-platform-analysis.md) | 验证证据完整性并分析 A/V Sync 事件。                     |
+| [维护索引](docs/README.md) / [能力边界](docs/capability-boundaries.md)                                            | 遗留问题、待优化内容、后续计划及职责划分。               |