@vivix-ai/ivi-frontend-sdk 0.3.10 → 0.3.12

package/README.md

@@ -246,11 +246,12 @@ await runtime.start();
 
 会被串联的关键 spans 包括：
 
-- `ivi.session.create`：HTTP 创建 IVI Session
-- `ivi.runtime.create` / `ivi.runtime.start` / `ivi.runtime.stop`
-- `ivi.runtime.state_change`
-- `ivi.client.*`：底层 `@vivix-ai/ivi-sdk-ts` WebSocket 连接、发送、接收等 spans
-- `ivi.media.trtc.*` / `ivi.media.livekit.*`：远端视频可用、开始渲染、渲染完成等首屏关键点
+- `sdk.session.create`：HTTP 创建 IVI Session
+- `sdk.runtime.create` / `sdk.runtime.start` / `sdk.runtime.stop`
+- `sdk.client.connect` / `sdk.client.connection`：底层 `@vivix-ai/ivi-sdk-ts` WebSocket 连接与聚合消息计数
+- `sdk.media.trtc.join_room` / `sdk.media.livekit.join_room`：媒体进房耗时
+- `sdk.media.trtc.waiting_remote_video_available` / `sdk.media.trtc.start_remote_video` / `sdk.media.trtc.remote_video_rendered`：TRTC 远端视频事件等待、开始渲染、渲染完成等首屏关键点
+- `sdk.media.livekit.*`：LiveKit 远端视频可用等首屏关键点
 
 SDK span 不会写入 token、`user_sig`、TRTC `secret_key` 或完整业务 payload。低基数字段可以放在 `telemetry.attributes` 中统一附加。
 

package/dist/index.cjs

@@ -1540,14 +1540,14 @@ var TrtcSourceManager = class {
       const client = TRTC.create();
       const onRemoteVideoAvailable = (event) => {
         this.log("info", `\u8FDC\u7AEF\u89C6\u9891\u53EF\u7528 source=${session.sourceId} userId=${event.userId} streamType=${event.streamType}`);
-        recordIviTelemetrySpan(
-          "ivi.media.trtc.remote_video_available",
-          this.telemetry,
-          buildTrtcMediaTelemetryAttributes(session.sourceId, event.userId, event.streamType)
-        );
+        const telemetryAttributes = buildTrtcMediaTelemetryAttributes(session.sourceId, event.userId, event.streamType);
         const remoteVideoKey = buildRemoteVideoKey(event.userId, String(event.streamType));
         session.remoteVideoStreams.add(remoteVideoKey);
         if (!session.hasEverReceivedRemoteVideo) {
+          this.endRemoteVideoAvailableWait(session, {
+            ...telemetryAttributes,
+            "ivi.media.trtc.waiting_remote_video_available.result": "available"
+          });
           session.hasEverReceivedRemoteVideo = true;
           for (const waiter of session.remoteVideoWaiters) {
             waiter(true);
@@ -1594,15 +1594,38 @@ var TrtcSourceManager = class {
       client.on(TRTC.EVENT.REMOTE_AUDIO_AVAILABLE, onRemoteAudioAvailable);
       client.on(TRTC.EVENT.REMOTE_AUDIO_UNAVAILABLE, onRemoteAudioUnavailable);
       this.log("info", `\u6B63\u5728\u8FDB\u623F source=${session.sourceId} room=${roomId} sdkAppId=${sdkAppId} userId=${userId}`);
-      await client.enterRoom({
-        sdkAppId,
-        userId,
-        userSig,
-        scene: TRTC.TYPE.SCENE_LIVE,
-        role: TRTC.TYPE.ROLE_AUDIENCE,
-        autoReceiveAudio: true,
-        ...isStringRoomId ? { strRoomId: roomId } : { roomId: Number(roomId) }
-      });
+      session.remoteVideoAvailableSpan = startIviTelemetrySpan(
+        "sdk.media.trtc.waiting_remote_video_available",
+        this.telemetry,
+        buildTrtcWaitingRemoteVideoTelemetryAttributes(session.sourceId, roomId, sdkAppId, isStringRoomId)
+      );
+      const joinRoomSpan = startIviTelemetrySpan(
+        "sdk.media.trtc.join_room",
+        this.telemetry,
+        buildTrtcJoinRoomTelemetryAttributes(session.sourceId, roomId, userId, sdkAppId, isStringRoomId)
+      );
+      try {
+        await client.enterRoom({
+          sdkAppId,
+          userId,
+          userSig,
+          scene: TRTC.TYPE.SCENE_LIVE,
+          role: TRTC.TYPE.ROLE_AUDIENCE,
+          autoReceiveAudio: true,
+          ...isStringRoomId ? { strRoomId: roomId } : { roomId: Number(roomId) }
+        });
+        endIviTelemetrySpan(joinRoomSpan.span, {
+          "ivi.media.trtc.join_room.result": "connected"
+        });
+      } catch (error) {
+        this.failRemoteVideoAvailableWait(session, error, {
+          "ivi.media.trtc.waiting_remote_video_available.result": "join_failed"
+        });
+        failIviTelemetrySpan(joinRoomSpan.span, error, {
+          "ivi.media.trtc.join_room.result": "failed"
+        });
+        throw error;
+      }
       session.TRTC = TRTC;
       session.client = client;
       session.status = "connected";
@@ -1614,6 +1637,9 @@ var TrtcSourceManager = class {
       });
       await this.applyAudioPolicy(session);
     })().catch((error) => {
+      this.failRemoteVideoAvailableWait(session, error, {
+        "ivi.media.trtc.waiting_remote_video_available.result": "connect_failed"
+      });
       session.status = "error";
       session.error = error instanceof Error ? error.message : String(error);
       this.log("error", `\u8FDE\u63A5\u5931\u8D25 source=${session.sourceId} error=${session.error}`);
@@ -1658,7 +1684,7 @@ var TrtcSourceManager = class {
       streamType
     );
     const telemetrySpan = startIviTelemetrySpan(
-      "ivi.media.trtc.start_remote_video",
+      "sdk.media.trtc.start_remote_video",
       this.telemetry,
       telemetryAttributes
     );
@@ -1672,7 +1698,7 @@ var TrtcSourceManager = class {
       });
       endIviTelemetrySpan(telemetrySpan.span);
       recordIviTelemetrySpan(
-        "ivi.media.trtc.remote_video_rendered",
+        "sdk.media.trtc.remote_video_rendered",
         this.telemetry,
         telemetryAttributes
       );
@@ -1736,6 +1762,22 @@ var TrtcSourceManager = class {
       this.log("warn", `TRTC AIDenoiser \u5F00\u542F\u5931\u8D25 source=${session.sourceId}`, error);
     }
   }
+  endRemoteVideoAvailableWait(session, attributes) {
+    const waitingSpan = session.remoteVideoAvailableSpan;
+    if (!waitingSpan) {
+      return;
+    }
+    session.remoteVideoAvailableSpan = void 0;
+    endIviTelemetrySpan(waitingSpan.span, attributes);
+  }
+  failRemoteVideoAvailableWait(session, error, attributes) {
+    const waitingSpan = session.remoteVideoAvailableSpan;
+    if (!waitingSpan) {
+      return;
+    }
+    session.remoteVideoAvailableSpan = void 0;
+    failIviTelemetrySpan(waitingSpan.span, error, attributes);
+  }
   /**
    * 销毁单个 source 会话：
    * 解绑事件、停止远端视频、退出房间并销毁客户端。
@@ -1749,6 +1791,9 @@ var TrtcSourceManager = class {
     session.remoteVideoStreams.clear();
     session.status = "idle";
     session.error = void 0;
+    this.endRemoteVideoAvailableWait(session, {
+      "ivi.media.trtc.waiting_remote_video_available.result": "cancelled"
+    });
     for (const waiter of session.remoteVideoWaiters) {
       waiter(false);
     }
@@ -1908,6 +1953,23 @@ function buildTrtcMediaTelemetryAttributes(sourceId, userId, streamType) {
     "ivi.trtc.stream_type": String(streamType)
   };
 }
+function buildTrtcJoinRoomTelemetryAttributes(sourceId, roomId, userId, sdkAppId, isStringRoomId) {
+  return {
+    "ivi.source.id": sourceId,
+    "ivi.trtc.room_id": roomId,
+    "ivi.trtc.user_id": userId,
+    "ivi.trtc.sdk_app_id": sdkAppId,
+    "ivi.trtc.room_id.is_string": isStringRoomId
+  };
+}
+function buildTrtcWaitingRemoteVideoTelemetryAttributes(sourceId, roomId, sdkAppId, isStringRoomId) {
+  return {
+    "ivi.source.id": sourceId,
+    "ivi.trtc.room_id": roomId,
+    "ivi.trtc.sdk_app_id": sdkAppId,
+    "ivi.trtc.room_id.is_string": isStringRoomId
+  };
+}
 function parseRemoteVideoKey(key) {
   const separatorIndex = key.indexOf("::");
   if (separatorIndex < 0) {
@@ -2196,7 +2258,7 @@ var LivekitSourceManager = class {
         });
         if (kind === "video" && !session.hasEverReceivedRemoteVideo) {
           recordIviTelemetrySpan(
-            "ivi.media.livekit.remote_video_available",
+            "sdk.media.livekit.remote_video_available",
             this.telemetry,
             {
               "ivi.source.id": session.sourceId,
@@ -2241,7 +2303,22 @@ var LivekitSourceManager = class {
         "info",
         `\u6B63\u5728\u8FDB\u623F source=${session.sourceId} room=${describeLivekitRoom(session.livekit)} ws=${session.livekit.ws_url}`
       );
-      await room.connect(session.livekit.ws_url, session.livekit.token);
+      const joinRoomSpan = startIviTelemetrySpan(
+        "sdk.media.livekit.join_room",
+        this.telemetry,
+        buildLivekitJoinRoomTelemetryAttributes(session)
+      );
+      try {
+        await room.connect(session.livekit.ws_url, session.livekit.token);
+        endIviTelemetrySpan(joinRoomSpan.span, {
+          "ivi.media.livekit.join_room.result": "connected"
+        });
+      } catch (error) {
+        failIviTelemetrySpan(joinRoomSpan.span, error, {
+          "ivi.media.livekit.join_room.result": "failed"
+        });
+        throw error;
+      }
       session.room = room;
       session.livekitModule = livekitModule;
       session.status = "connected";
@@ -2376,6 +2453,13 @@ var LivekitSourceManager = class {
 function buildRemoteTrackKey(identity, trackId) {
   return `${identity}::${trackId}`;
 }
+function buildLivekitJoinRoomTelemetryAttributes(session) {
+  return {
+    "ivi.source.id": session.sourceId,
+    "ivi.livekit.room": session.livekit.room,
+    "ivi.livekit.identity": session.livekit.identity
+  };
+}
 function enforceContainMedia2(element) {
   element.style.setProperty("width", "100%", "important");
   element.style.setProperty("height", "100%", "important");
@@ -2471,9 +2555,9 @@ var IviRuntimeCoordinator = class {
    * 启动后状态会从 idle/stopped 进入 connecting，连接成功后由事件驱动进入后续状态。
    */
   async start() {
-    const telemetrySpan = startIviTelemetrySpan("ivi.runtime.start", this.config.telemetry, {
+    const telemetrySpan = startIviTelemetrySpan("sdk.runtime.start", this.config.telemetry, {
       "ivi.runtime.status": this.state.status,
-      "ivi.session.id": this.state.session?.id
+      "session.id": this.state.session?.id
     });
     try {
       this.setState({
@@ -2484,13 +2568,13 @@ var IviRuntimeCoordinator = class {
       await this.client.connect();
       endIviTelemetrySpan(telemetrySpan.span, {
         "ivi.runtime.status": this.state.status,
-        "ivi.session.id": this.state.session?.id
+        "session.id": this.state.session?.id
       });
     } catch (error) {
       this.stop();
       failIviTelemetrySpan(telemetrySpan.span, error, {
         "ivi.runtime.status": this.state.status,
-        "ivi.session.id": this.state.session?.id
+        "session.id": this.state.session?.id
       });
       throw error;
     }
@@ -2499,9 +2583,9 @@ var IviRuntimeCoordinator = class {
    * 停止协调器并断开实时连接，同时重置运行态数据为 stopped。
    */
   stop() {
-    const telemetrySpan = startIviTelemetrySpan("ivi.runtime.stop", this.config.telemetry, {
+    const telemetrySpan = startIviTelemetrySpan("sdk.runtime.stop", this.config.telemetry, {
       "ivi.runtime.status": this.state.status,
-      "ivi.session.id": this.state.session?.id
+      "session.id": this.state.session?.id
     });
     try {
       this.dispatcher.stop();
@@ -2513,7 +2597,7 @@ var IviRuntimeCoordinator = class {
     } catch (error) {
       failIviTelemetrySpan(telemetrySpan.span, error, {
         "ivi.runtime.status": this.state.status,
-        "ivi.session.id": this.state.session?.id
+        "session.id": this.state.session?.id
       });
       throw error;
     }
@@ -2814,16 +2898,7 @@ var IviRuntimeCoordinator = class {
     if (this.state.status === composedNextState.status && this.state.session === composedNextState.session && this.state.stage === composedNextState.stage && this.state.tracks === composedNextState.tracks && this.state.sources === composedNextState.sources && this.state.streams === composedNextState.streams && this.state.conversationItems === composedNextState.conversationItems && this.state.conversations === composedNextState.conversations && isSameBootstrapState(this.state.bootstrap, composedNextState.bootstrap)) {
       return;
     }
-    const previousState = this.state;
     this.state = composedNextState;
-    if (previousState.status !== composedNextState.status) {
-      recordIviTelemetrySpan("ivi.runtime.state_change", this.config.telemetry, {
-        "ivi.runtime.status.previous": previousState.status,
-        "ivi.runtime.status.next": composedNextState.status,
-        "ivi.runtime.state_change.reason": "state_update",
-        "ivi.session.id": composedNextState.session?.id ?? previousState.session?.id
-      });
-    }
     this.stateListeners.forEach((listener) => listener(this.state));
   }
   composeBootstrapState(nextState) {
@@ -3107,7 +3182,7 @@ async function createIVISession(request, options) {
     throw new Error("fetch is not available. Pass options.fetch to createIVISession.");
   }
   const telemetrySpan = startIviTelemetrySpan(
-    "ivi.session.create",
+    "sdk.session.create",
     options.telemetry,
     buildCreateSessionTelemetryAttributes(request)
   );
@@ -3134,7 +3209,7 @@ async function createIVISession(request, options) {
     const result = normalizeCreateIVISessionResponse(responseBody, request, requestBody);
     endIviTelemetrySpan(telemetrySpan.span, {
       "http.response.status_code": response.status,
-      "ivi.session.id": result.iviSessionId,
+      "session.id": result.iviSessionId,
       "ivi.prebuild.playback.kind": result.prebuiltPlayback?.kind
     });
     return result;
@@ -3146,14 +3221,18 @@ async function createIVISession(request, options) {
   }
 }
 function createRuntimeFromSession(session, options = {}) {
-  const telemetrySpan = startIviTelemetrySpan("ivi.runtime.create", options.telemetry, {
-    "ivi.session.id": session.iviSessionId,
-    "ivi.prebuild.playback.kind": session.prebuiltPlayback?.kind
+  const fastStartEnabled = options.fastStart !== false;
+  const fastStartApplied = fastStartEnabled && Boolean(session.prebuiltPlayback);
+  const telemetrySpan = startIviTelemetrySpan("sdk.runtime.create", options.telemetry, {
+    "session.id": session.iviSessionId,
+    "ivi.prebuild.playback.kind": session.prebuiltPlayback?.kind,
+    "ivi.fast_start.enabled": fastStartEnabled,
+    "ivi.fast_start.applied": fastStartApplied
   });
   try {
     const websocketUrl = buildWebSocketUrl(session.endpoint, options.websocket);
     const childTelemetry = withIviTelemetryContext(options.telemetry, telemetrySpan.context, {
-      "ivi.session.id": session.iviSessionId
+      "session.id": session.iviSessionId
     });
     const clientTelemetry = mergeIviTelemetryOptions(
       options.clientConfig?.telemetry,
@@ -3177,7 +3256,7 @@ function createRuntimeFromSession(session, options = {}) {
       ...options.runtimeConfig ?? {},
       telemetry: runtimeTelemetry
     });
-    if (options.fastStart !== false && session.prebuiltPlayback) {
+    if (fastStartEnabled && session.prebuiltPlayback) {
       runtime.setBootstrapSource(toBootstrapSource(session.prebuiltPlayback, options));
     }
     endIviTelemetrySpan(telemetrySpan.span);
@@ -4805,7 +4884,7 @@ function IVIHlsVideo(props) {
     const onVideoError = () => {
       const el = videoRef.current;
       const mediaErr = el?.error;
-      recordVideoTelemetry("ivi.media.video.error", telemetry, sourceId, "hls", mediaErr);
+      recordVideoTelemetry("sdk.media.video.error", telemetry, sourceId, "hls", mediaErr);
       emitHlsLog(onLog, "warn", "<video> \u5143\u7D20\u62A5\u9519", {
         code: mediaErr?.code,
         message: mediaErr?.message,
@@ -4816,7 +4895,7 @@ function IVIHlsVideo(props) {
     };
     const onVideoStalled = () => {
       recordVideoTelemetry(
-        "ivi.media.video.stalled",
+        "sdk.media.video.stalled",
         telemetry,
         sourceId,
         "hls",
@@ -5212,7 +5291,7 @@ function SlotVideo(props) {
   }, [props.paused]);
   const onError = (event) => {
     recordPlainVideoTelemetry(
-      "ivi.media.video.error",
+      "sdk.media.video.error",
       props.telemetry,
       props.sourceId,
       event.currentTarget.error
@@ -5221,7 +5300,7 @@ function SlotVideo(props) {
   };
   const onStalled = (event) => {
     recordPlainVideoTelemetry(
-      "ivi.media.video.stalled",
+      "sdk.media.video.stalled",
       props.telemetry,
       props.sourceId,
       new Error("<video> stalled")