@vivix-ai/ivi-frontend-sdk 0.3.9 → 0.3.11

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var iviSdkTs = require('@vivix-ai/ivi-sdk-ts');
+var api = require('@opentelemetry/api');
 var websocket = require('@vivix-ai/ivi-sdk-ts/transports/websocket');
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
@@ -1141,6 +1142,94 @@ var ConversationManager = class {
     ];
   }
 };
+var DEFAULT_TRACER_NAME = "@vivix-ai/ivi-frontend-sdk";
+function getIviTelemetryTracer(options) {
+  return options?.tracer ?? api.trace.getTracer(DEFAULT_TRACER_NAME);
+}
+function getIviTelemetryContext(options) {
+  return options?.context ?? api.context.active();
+}
+function startIviTelemetrySpan(name, options, attributes) {
+  const tracer = getIviTelemetryTracer(options);
+  const parentContext = getIviTelemetryContext(options);
+  const span = tracer.startSpan(
+    name,
+    {
+      kind: api.SpanKind.INTERNAL,
+      attributes: mergeIviTelemetryAttributes(options?.attributes, attributes)
+    },
+    parentContext
+  );
+  return {
+    span,
+    context: api.trace.setSpan(parentContext, span)
+  };
+}
+function endIviTelemetrySpan(span, attributes) {
+  const cleaned = cleanIviTelemetryAttributes(attributes);
+  if (cleaned) {
+    span.setAttributes(cleaned);
+  }
+  span.setStatus({ code: api.SpanStatusCode.OK });
+  span.end();
+}
+function failIviTelemetrySpan(span, error, attributes) {
+  const cleaned = cleanIviTelemetryAttributes(attributes);
+  if (cleaned) {
+    span.setAttributes(cleaned);
+  }
+  recordIviTelemetryError(span, error);
+  span.end();
+}
+function recordIviTelemetrySpan(name, options, attributes, error) {
+  const { span } = startIviTelemetrySpan(name, options, attributes);
+  if (error === void 0) {
+    span.setStatus({ code: api.SpanStatusCode.OK });
+  } else {
+    recordIviTelemetryError(span, error);
+  }
+  span.end();
+}
+function withIviTelemetryContext(options, context, attributes) {
+  return {
+    ...options,
+    context,
+    attributes: mergeIviTelemetryAttributes(options?.attributes, attributes)
+  };
+}
+function mergeIviTelemetryAttributes(base, next) {
+  return cleanIviTelemetryAttributes({
+    ...base ?? {},
+    ...next ?? {}
+  });
+}
+function cleanIviTelemetryAttributes(attributes) {
+  const cleaned = {};
+  Object.entries(attributes ?? {}).forEach(([key, value]) => {
+    if (isIviTelemetryAttributeValue(value)) {
+      cleaned[key] = value;
+    }
+  });
+  return Object.keys(cleaned).length > 0 ? cleaned : void 0;
+}
+function recordIviTelemetryError(span, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  span.recordException(error instanceof Error ? error : message);
+  span.setStatus({
+    code: api.SpanStatusCode.ERROR,
+    message
+  });
+}
+function isIviTelemetryAttributeValue(value) {
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (!Array.isArray(value)) return false;
+  const nonNullValues = value.filter((item) => item !== null && item !== void 0);
+  if (nonNullValues.length === 0) return true;
+  const firstType = typeof nonNullValues[0];
+  if (firstType !== "string" && firstType !== "number" && firstType !== "boolean") return false;
+  return nonNullValues.every((item) => typeof item === firstType && (typeof item !== "number" || Number.isFinite(item)));
+}
 
 // src/runtime/managers/trtc-source-manager.ts
 var TAG = "[IVI-TRTC]";
@@ -1151,10 +1240,11 @@ var DEFAULT_DENOISER_OPTIONS = {
   mode: "normal"
 };
 var TrtcSourceManager = class {
-  constructor(onLog, onTrtcEvent, aiDenoiser) {
+  constructor(onLog, onTrtcEvent, aiDenoiser, telemetry) {
     this.onLog = onLog;
     this.onTrtcEvent = onTrtcEvent;
     this.aiDenoiser = aiDenoiser;
+    this.telemetry = telemetry;
     this.sessions = /* @__PURE__ */ new Map();
     this.sourceSessionKeys = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
@@ -1450,9 +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}`);
+        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);
@@ -1499,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";
@@ -1519,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}`);
@@ -1557,6 +1678,16 @@ var TrtcSourceManager = class {
       return;
     }
     binding.startingVideoKeys.add(remoteVideoKey);
+    const telemetryAttributes = buildTrtcMediaTelemetryAttributes(
+      binding.sourceId,
+      userId,
+      streamType
+    );
+    const telemetrySpan = startIviTelemetrySpan(
+      "sdk.media.trtc.start_remote_video",
+      this.telemetry,
+      telemetryAttributes
+    );
     try {
       this.log("info", `\u5F00\u59CB\u6E32\u67D3\u8FDC\u7AEF\u89C6\u9891 source=${binding.sourceId} view=${remoteVideoKey} userId=${userId} streamType=${streamType}`);
       await client.startRemoteVideo({
@@ -1565,14 +1696,24 @@ var TrtcSourceManager = class {
         view: binding.container,
         option: { fillMode: "contain" }
       });
+      endIviTelemetrySpan(telemetrySpan.span);
+      recordIviTelemetrySpan(
+        "sdk.media.trtc.remote_video_rendered",
+        this.telemetry,
+        telemetryAttributes
+      );
       this.log("info", `\u8FDC\u7AEF\u89C6\u9891\u6E32\u67D3\u5B8C\u6210 source=${binding.sourceId} userId=${userId} streamType=${streamType}`);
       binding.startedVideoKeys.add(remoteVideoKey);
       enforceContainMedia(binding.container);
     } catch (error) {
       if (error instanceof Error && /already started|OPERATION_ABORT/i.test(error.message)) {
         binding.startedVideoKeys.add(remoteVideoKey);
+        endIviTelemetrySpan(telemetrySpan.span, {
+          "ivi.media.trtc.start_remote_video.result": "already_started"
+        });
         return;
       }
+      failIviTelemetrySpan(telemetrySpan.span, error);
       this.log("warn", `\u8FDC\u7AEF\u89C6\u9891\u6E32\u67D3\u5931\u8D25 userId=${userId} streamType=${streamType}`, error);
     } finally {
       binding.startingVideoKeys.delete(remoteVideoKey);
@@ -1621,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 会话：
    * 解绑事件、停止远端视频、退出房间并销毁客户端。
@@ -1634,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);
     }
@@ -1786,6 +1946,30 @@ function getAIDenoiserModeValue(mode) {
 function buildRemoteVideoKey(userId, streamType) {
   return `${userId}::${streamType}`;
 }
+function buildTrtcMediaTelemetryAttributes(sourceId, userId, streamType) {
+  return {
+    "ivi.source.id": sourceId,
+    "ivi.trtc.user_id": userId,
+    "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) {
@@ -1848,9 +2032,10 @@ function describeLivekitRoom(livekit) {
 // src/runtime/managers/livekit-source-manager.ts
 var TAG2 = "[IVI-LIVEKIT]";
 var LivekitSourceManager = class {
-  constructor(onLog, onRemoteVideoAvailable) {
+  constructor(onLog, onRemoteVideoAvailable, telemetry) {
     this.onLog = onLog;
     this.onRemoteVideoAvailable = onRemoteVideoAvailable;
+    this.telemetry = telemetry;
     this.sessions = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
   }
@@ -2072,6 +2257,15 @@ var LivekitSourceManager = class {
           kind
         });
         if (kind === "video" && !session.hasEverReceivedRemoteVideo) {
+          recordIviTelemetrySpan(
+            "sdk.media.livekit.remote_video_available",
+            this.telemetry,
+            {
+              "ivi.source.id": session.sourceId,
+              "ivi.livekit.participant_identity": participant.identity,
+              "ivi.livekit.track_sid": track.sid
+            }
+          );
           session.hasEverReceivedRemoteVideo = true;
           for (const waiter of session.remoteVideoWaiters) {
             waiter(true);
@@ -2109,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";
@@ -2244,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");
@@ -2293,11 +2509,16 @@ var IviRuntimeCoordinator = class {
     this.trtcSourceManager = new TrtcSourceManager(
       this.config.onLog,
       (event) => this.onTrtcManagerEvent(event),
-      this.config.trtcAIDenoiser
+      this.config.trtcAIDenoiser,
+      this.config.telemetry
+    );
+    this.livekitSourceManager = new LivekitSourceManager(
+      this.config.onLog,
+      () => {
+        this.recomposeBootstrapState();
+      },
+      this.config.telemetry
     );
-    this.livekitSourceManager = new LivekitSourceManager(this.config.onLog, () => {
-      this.recomposeBootstrapState();
-    });
     this.sessionHandler = new SessionEventHandler(this.sessionManager, {
       onSessionCreated: (event) => this.onSessionCreated(event),
       onSessionEnded: (event) => this.onSessionEnded(event)
@@ -2334,15 +2555,27 @@ var IviRuntimeCoordinator = class {
    * 启动后状态会从 idle/stopped 进入 connecting，连接成功后由事件驱动进入后续状态。
    */
   async start() {
-    this.setState({
-      ...this.state,
-      status: "connecting"
+    const telemetrySpan = startIviTelemetrySpan("sdk.runtime.start", this.config.telemetry, {
+      "ivi.runtime.status": this.state.status,
+      "ivi.session.id": this.state.session?.id
     });
-    this.dispatcher.start();
     try {
+      this.setState({
+        ...this.state,
+        status: "connecting"
+      });
+      this.dispatcher.start();
       await this.client.connect();
+      endIviTelemetrySpan(telemetrySpan.span, {
+        "ivi.runtime.status": this.state.status,
+        "ivi.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
+      });
       throw error;
     }
   }
@@ -2350,13 +2583,31 @@ var IviRuntimeCoordinator = class {
    * 停止协调器并断开实时连接，同时重置运行态数据为 stopped。
    */
   stop() {
-    this.dispatcher.stop();
-    this.client.disconnect();
-    this.resetStoppedState();
+    const telemetrySpan = startIviTelemetrySpan("sdk.runtime.stop", this.config.telemetry, {
+      "ivi.runtime.status": this.state.status,
+      "ivi.session.id": this.state.session?.id
+    });
+    try {
+      this.dispatcher.stop();
+      this.client.disconnect();
+      this.resetStoppedState();
+      endIviTelemetrySpan(telemetrySpan.span, {
+        "ivi.runtime.status": this.state.status
+      });
+    } catch (error) {
+      failIviTelemetrySpan(telemetrySpan.span, error, {
+        "ivi.runtime.status": this.state.status,
+        "ivi.session.id": this.state.session?.id
+      });
+      throw error;
+    }
   }
   getState() {
     return this.state;
   }
+  getTelemetryOptions() {
+    return this.config.telemetry;
+  }
   onStateChange(listener) {
     this.stateListeners.add(listener);
     return () => {
@@ -2930,44 +3181,101 @@ async function createIVISession(request, options) {
   if (!fetchImpl) {
     throw new Error("fetch is not available. Pass options.fetch to createIVISession.");
   }
-  const requestBody = toCpCreateIVISessionRequestBody(request);
-  const response = await fetchImpl(resolveCreateIVISessionUrl(options), {
-    method: "POST",
-    headers: await buildHeaders(options.headers),
-    body: JSON.stringify(requestBody),
-    credentials: options.credentials,
-    signal: options.signal
-  });
-  const responseBody = await readJsonResponse(response);
-  if (!response.ok) {
-    throw new IviCreateIVISessionError(response, responseBody);
+  const telemetrySpan = startIviTelemetrySpan(
+    "sdk.session.create",
+    options.telemetry,
+    buildCreateSessionTelemetryAttributes(request)
+  );
+  try {
+    const requestBody = toCpCreateIVISessionRequestBody(request);
+    const headers = await buildHeaders(options.headers);
+    injectIviTelemetryHeaders(headers, telemetrySpan.context);
+    const response = await fetchImpl(resolveCreateIVISessionUrl(options), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestBody),
+      credentials: options.credentials,
+      signal: options.signal
+    });
+    const responseBody = await readJsonResponse(response);
+    if (!response.ok) {
+      const error = new IviCreateIVISessionError(response, responseBody);
+      failIviTelemetrySpan(telemetrySpan.span, error, {
+        "http.response.status_code": response.status,
+        "http.response.status_text": response.statusText
+      });
+      throw error;
+    }
+    const result = normalizeCreateIVISessionResponse(responseBody, request, requestBody);
+    endIviTelemetrySpan(telemetrySpan.span, {
+      "http.response.status_code": response.status,
+      "ivi.session.id": result.iviSessionId,
+      "ivi.prebuild.playback.kind": result.prebuiltPlayback?.kind
+    });
+    return result;
+  } catch (error) {
+    if (!(error instanceof IviCreateIVISessionError)) {
+      failIviTelemetrySpan(telemetrySpan.span, error);
+    }
+    throw error;
   }
-  return normalizeCreateIVISessionResponse(responseBody, request, requestBody);
 }
 function createRuntimeFromSession(session, options = {}) {
-  const websocketUrl = buildWebSocketUrl(session.endpoint, options.websocket);
-  const client = new iviSdkTs.IviClient({
-    ...options.clientConfig ?? {},
-    transport: new websocket.WebSocketTransport({
-      url: websocketUrl,
-      sessionId: session.iviSessionId,
-      protocols: options.websocket?.protocols,
-      socketFactory: options.websocket?.socketFactory
-    })
+  const telemetrySpan = startIviTelemetrySpan("sdk.runtime.create", options.telemetry, {
+    "ivi.session.id": session.iviSessionId,
+    "ivi.prebuild.playback.kind": session.prebuiltPlayback?.kind
   });
-  const runtime = new IviRuntimeCoordinator(client, options.runtimeConfig);
-  if (options.fastStart !== false && session.prebuiltPlayback) {
-    runtime.setBootstrapSource(toBootstrapSource(session.prebuiltPlayback, options));
+  try {
+    const websocketUrl = buildWebSocketUrl(session.endpoint, options.websocket);
+    const childTelemetry = withIviTelemetryContext(options.telemetry, telemetrySpan.context, {
+      "ivi.session.id": session.iviSessionId
+    });
+    const clientTelemetry = mergeIviTelemetryOptions(
+      options.clientConfig?.telemetry,
+      childTelemetry
+    );
+    const runtimeTelemetry = mergeIviTelemetryOptions(
+      options.runtimeConfig?.telemetry,
+      childTelemetry
+    );
+    const client = new iviSdkTs.IviClient({
+      ...options.clientConfig ?? {},
+      telemetry: clientTelemetry,
+      transport: new websocket.WebSocketTransport({
+        url: websocketUrl,
+        sessionId: session.iviSessionId,
+        protocols: options.websocket?.protocols,
+        socketFactory: options.websocket?.socketFactory
+      })
+    });
+    const runtime = new IviRuntimeCoordinator(client, {
+      ...options.runtimeConfig ?? {},
+      telemetry: runtimeTelemetry
+    });
+    if (options.fastStart !== false && session.prebuiltPlayback) {
+      runtime.setBootstrapSource(toBootstrapSource(session.prebuiltPlayback, options));
+    }
+    endIviTelemetrySpan(telemetrySpan.span);
+    return {
+      session,
+      client,
+      runtime
+    };
+  } catch (error) {
+    failIviTelemetrySpan(telemetrySpan.span, error);
+    throw error;
   }
-  return {
-    session,
-    client,
-    runtime
-  };
 }
 async function createIVISessionRuntime(request, options) {
-  const session = await createIVISession(request, options.http);
-  return createRuntimeFromSession(session, options);
+  const telemetry = mergeIviTelemetryOptions(options.telemetry, options.http.telemetry);
+  const session = await createIVISession(request, {
+    ...options.http,
+    telemetry
+  });
+  return createRuntimeFromSession(session, {
+    ...options,
+    telemetry
+  });
 }
 function toCpCreateIVISessionRequestBody(request) {
   const body = { ...request };
@@ -3053,6 +3361,25 @@ function resolveCreateIVISessionUrl(options) {
   const path = options.path ?? "/v1/ivi/sessions";
   return new URL(path, ensureTrailingSlash(options.baseUrl)).toString();
 }
+function buildCreateSessionTelemetryAttributes(request) {
+  return {
+    "ivi.version": request.iviVersion,
+    "ivi.stream.type": request.streamType,
+    "ivi.prebuild.enabled": Boolean(
+      request.prebuiltStream || request.prebuiltCharacters && request.prebuiltCharacters.length > 0
+    )
+  };
+}
+function mergeIviTelemetryOptions(explicit, inherited) {
+  if (!explicit && !inherited) {
+    return void 0;
+  }
+  return {
+    tracer: explicit?.tracer ?? inherited?.tracer,
+    context: explicit?.context ?? inherited?.context,
+    attributes: mergeIviTelemetryAttributes(inherited?.attributes, explicit?.attributes)
+  };
+}
 async function buildHeaders(headers) {
   const resolvedHeaders = typeof headers === "function" ? await headers() : headers;
   const next = new Headers(resolvedHeaders);
@@ -3061,6 +3388,14 @@ async function buildHeaders(headers) {
   }
   return next;
 }
+var headersTextMapSetter = {
+  set(carrier, key, value) {
+    carrier.set(key, value);
+  }
+};
+function injectIviTelemetryHeaders(headers, context) {
+  api.propagation.inject(context, headers, headersTextMapSetter);
+}
 async function readJsonResponse(response) {
   const text = await response.text();
   if (!text) {
@@ -3234,32 +3569,71 @@ var IviFrontendSdk = class {
     this.config = config;
   }
   createClient(config) {
-    return new iviSdkTs.IviClient(config);
+    return new iviSdkTs.IviClient({
+      ...config,
+      telemetry: mergeSdkTelemetryOptions(config.telemetry, this.config.telemetry)
+    });
   }
   createRuntimeCoordinator(clientConfig, runtimeConfig) {
     const client = this.createClient(clientConfig);
-    return new IviRuntimeCoordinator(client, runtimeConfig);
+    return new IviRuntimeCoordinator(client, {
+      ...runtimeConfig ?? {},
+      telemetry: mergeSdkTelemetryOptions(runtimeConfig?.telemetry, this.config.telemetry)
+    });
   }
   createIVISession(request, options) {
+    const telemetry = mergeSdkTelemetryChain(
+      this.config.telemetry,
+      this.config.http?.telemetry,
+      options?.telemetry
+    );
     return createIVISession(request, {
       ...this.config.http ?? {},
-      ...options ?? {}
+      ...options ?? {},
+      telemetry
     });
   }
   createRuntimeFromSession(session, options) {
-    return createRuntimeFromSession(session, options);
+    return createRuntimeFromSession(session, {
+      ...options ?? {},
+      telemetry: mergeSdkTelemetryChain(this.config.telemetry, options?.telemetry)
+    });
   }
   createIVISessionRuntime(request, options) {
+    const telemetry = mergeSdkTelemetryChain(
+      this.config.telemetry,
+      this.config.http?.telemetry,
+      options?.http?.telemetry,
+      options?.telemetry
+    );
     const http = {
       ...this.config.http ?? {},
-      ...options?.http ?? {}
+      ...options?.http ?? {},
+      telemetry
     };
     return createIVISessionRuntime(request, {
       ...options ?? {},
+      telemetry,
       http
     });
   }
 };
+function mergeSdkTelemetryChain(...items) {
+  return items.reduce(
+    (merged, item) => mergeSdkTelemetryOptions(item, merged),
+    void 0
+  );
+}
+function mergeSdkTelemetryOptions(explicit, inherited) {
+  if (!explicit && !inherited) {
+    return void 0;
+  }
+  return {
+    tracer: explicit?.tracer ?? inherited?.tracer,
+    context: explicit?.context ?? inherited?.context,
+    attributes: mergeIviTelemetryAttributes(inherited?.attributes, explicit?.attributes)
+  };
+}
 var IviStageViewContext = react.createContext(null);
 var EMPTY_RUNTIME_STATE = {
   status: "idle",
@@ -4460,7 +4834,16 @@ function makeLoadPolicy(label, onLog) {
   };
 }
 function IVIHlsVideo(props) {
-  const { url, videoProps, style, aggressivePreload = false, paused = false, onLog } = props;
+  const {
+    url,
+    sourceId,
+    videoProps,
+    style,
+    aggressivePreload = false,
+    paused = false,
+    onLog,
+    telemetry
+  } = props;
   const videoRef = react.useRef(null);
   const pausedRef = react.useRef(paused);
   react.useEffect(() => {
@@ -4497,6 +4880,7 @@ function IVIHlsVideo(props) {
     const onVideoError = () => {
       const el = videoRef.current;
       const mediaErr = el?.error;
+      recordVideoTelemetry("sdk.media.video.error", telemetry, sourceId, "hls", mediaErr);
       emitHlsLog(onLog, "warn", "<video> \u5143\u7D20\u62A5\u9519", {
         code: mediaErr?.code,
         message: mediaErr?.message,
@@ -4506,6 +4890,13 @@ function IVIHlsVideo(props) {
       });
     };
     const onVideoStalled = () => {
+      recordVideoTelemetry(
+        "sdk.media.video.stalled",
+        telemetry,
+        sourceId,
+        "hls",
+        new Error("<video> stalled")
+      );
       emitHlsLog(onLog, "warn", "<video> stalled\uFF08\u7F13\u51B2\u505C\u6EDE\uFF09", {
         currentTime: videoRef.current?.currentTime,
         readyState: videoRef.current?.readyState
@@ -4648,7 +5039,7 @@ function IVIHlsVideo(props) {
       hlsInstance?.destroy();
       hlsInstance = null;
     };
-  }, [url, aggressivePreload, onLog]);
+  }, [url, sourceId, aggressivePreload, onLog, telemetry]);
   return /* @__PURE__ */ jsxRuntime.jsx(
     "video",
     {
@@ -4661,6 +5052,17 @@ function IVIHlsVideo(props) {
     }
   );
 }
+function recordVideoTelemetry(name, telemetry, sourceId, kind, error) {
+  recordIviTelemetrySpan(
+    name,
+    telemetry,
+    {
+      "ivi.source.id": sourceId,
+      "ivi.media.kind": kind
+    },
+    error
+  );
+}
 function isM3u8Url(url) {
   return /\.m3u8(?:$|[?#])/i.test(url);
 }
@@ -4726,6 +5128,7 @@ function TrackSlotMediaContent(props) {
     source,
     isPreloading: !isActive
   };
+  const telemetry = runtime?.getTelemetryOptions();
   const mediaStyle = buildAdaptiveMediaStyle(adaptToSourceSize, fitStrategy);
   const shouldMute = !isActive;
   if (renderMedia) return renderMedia(renderContext);
@@ -4797,9 +5200,11 @@ function TrackSlotMediaContent(props) {
       IVIHlsVideo,
       {
         url: playbackUrl,
+        sourceId: slotSourceId,
         videoProps: mergedVideoProps,
         style: videoStyle,
-        paused: shouldPause
+        paused: shouldPause,
+        telemetry
       }
     );
   }
@@ -4821,6 +5226,7 @@ function TrackSlotMediaContent(props) {
     SlotVideo,
     {
       src: playbackUrl,
+      sourceId: slotSourceId,
       paused: shouldPause,
       videoProps: {
         ...mergedVideoProps,
@@ -4828,7 +5234,8 @@ function TrackSlotMediaContent(props) {
         playsInline: videoProps?.playsInline ?? true,
         controls: isActive ? videoProps?.controls ?? true : false
       },
-      style: videoStyle
+      style: videoStyle,
+      telemetry
     }
   );
 }
@@ -4878,17 +5285,48 @@ function SlotVideo(props) {
       video.play().catch(() => void 0);
     }
   }, [props.paused]);
+  const onError = (event) => {
+    recordPlainVideoTelemetry(
+      "sdk.media.video.error",
+      props.telemetry,
+      props.sourceId,
+      event.currentTarget.error
+    );
+    props.videoProps.onError?.(event);
+  };
+  const onStalled = (event) => {
+    recordPlainVideoTelemetry(
+      "sdk.media.video.stalled",
+      props.telemetry,
+      props.sourceId,
+      new Error("<video> stalled")
+    );
+    props.videoProps.onStalled?.(event);
+  };
   return /* @__PURE__ */ jsxRuntime.jsx(
     "video",
     {
       ref: videoRef,
       src: props.src,
       ...props.videoProps,
+      onError,
+      onStalled,
       autoPlay: props.paused ? false : props.videoProps.autoPlay ?? true,
       style: props.style
     }
   );
 }
+function recordPlainVideoTelemetry(name, telemetry, sourceId, error) {
+  recordIviTelemetrySpan(
+    name,
+    telemetry,
+    {
+      "ivi.source.id": sourceId,
+      "ivi.media.kind": "video"
+    },
+    error
+  );
+}
 
 // src/react/internal/use-multi-preload-sources.ts
 function useMultiPreloadSources(sources, activeSourceId) {