@observertc/observer-js 1.0.0-beta.16 → 1.0.0-beta.18

package/dist/index.mjs

@@ -37,8 +37,8 @@ function createLogger(moduleName) {
     }
   }();
 }
-function setObserverLogger(logger9) {
-  mainLogger = logger9;
+function setObserverLogger(logger10) {
+  mainLogger = logger10;
 }
 
 // src/ObservedCall.ts
@@ -3456,7 +3456,6 @@ var UnconsumedTrackDetector = class _UnconsumedTrackDetector {
         type: UnconsumedTrackTypes.unconsumedPublishedTrack,
         timestamp: now,
         payload: {
-          type: UnconsumedTrackTypes.unconsumedPublishedTrack,
           trackId: outboundTrack.id,
           kind: outboundTrack.kind,
           publisherClientId: peerConnection?.client.clientId,
@@ -3602,7 +3601,6 @@ var TrackDeliveryMismatchDetector = class _TrackDeliveryMismatchDetector {
         type,
         timestamp: now,
         payload: {
-          type,
           trackId: outboundTrackId,
           publisherClientId: delivery.publisherClientId,
           publisherSending: delivery.publisherSending,
@@ -3855,12 +3853,9 @@ var CallConcurrentIssueDetector = class _CallConcurrentIssueDetector {
       this._call.addIssue({
         type: issueType,
         timestamp: now,
+        conclusion,
         payload: {
-          type: issueType,
           issueType: type,
-          scope: "call",
-          conclusion,
-          callId: this._call.callId,
           clients: group.totalClients,
           affectedClients: group.clientIds.length,
           affectedRatio: group.affectedRatio,
@@ -3984,10 +3979,9 @@ var IssueFanOutDetector = class _IssueFanOutDetector {
         this._call.addIssue({
           type,
           timestamp: now,
+          conclusion,
           payload: {
-            type,
             issueType,
-            conclusion,
             trackId: publisher.id,
             kind: publisher.kind,
             publisherClientId: publisher.getPeerConnection().client.clientId,
@@ -4134,18 +4128,14 @@ var PublisherFaultCorroborationDetector = class _PublisherFaultCorroborationDete
       this._call.addIssue({
         type: PublisherFaultTypes.corroboratedPublisherFault,
         timestamp: now,
-        payload: {
-          type: PublisherFaultTypes.corroboratedPublisherFault,
-          callId: this._call.callId,
-          ...fault,
-          conclusion: {
-            faultDomain: "published-track",
-            summary: `${fault.publisherClientId} reports ${fault.publisherIssueTypes.join(", ")} on track ${fault.trackId} while ${fault.affectedReceivers} of ${fault.receivers} subscribers report ${fault.receiverIssueTypes.join(", ")} \u2014 both ends agree`,
-            recommendation: "the source is implicated, not inferred: check that publisher's capture, encoder and uplink before looking at the SFU or the receivers",
-            // Higher than any single-ended finding: two independent parties, one conclusion.
-            confidence: 0.9
-          }
-        }
+        conclusion: {
+          faultDomain: "published-track",
+          summary: `${fault.publisherClientId} reports ${fault.publisherIssueTypes.join(", ")} on track ${fault.trackId} while ${fault.affectedReceivers} of ${fault.receivers} subscribers report ${fault.receiverIssueTypes.join(", ")} \u2014 both ends agree`,
+          recommendation: "the source is implicated, not inferred: check that publisher's capture, encoder and uplink before looking at the SFU or the receivers",
+          // Higher than any single-ended finding: two independent parties, one conclusion.
+          confidence: 0.9
+        },
+        payload: { ...fault }
       });
     }
   }
@@ -4201,6 +4191,14 @@ var ObservedCall = class extends EventEmitter3 {
     value: void 0
   };
   remoteTrackResolver;
+  /**
+   * The accumulating record of this call's life, or `undefined` when no summary was configured.
+   *
+   * Live — read it at any point during the call. It is also delivered once on `call-summary` when
+   * the call closes. See `CallSummary`: an absent section means "not collected", never "nothing
+   * happened".
+   */
+  summary;
   /**
    * Published tracks that currently have **no** subscriber linked to them.
    *
@@ -4278,6 +4276,21 @@ var ObservedCall = class extends EventEmitter3 {
     this.detectors.add(detector);
     return this;
   }
+  /**
+   * Start accumulating this call's summary, if the observer was configured for summaries.
+   *
+   * Called by `createObservedCall`; you should not need it. It takes no configuration of its own on
+   * purpose: the collector subscribes to exactly the events the observer's `include` requires, so a
+   * per-call section outside that set would be created and then never written to — an empty section
+   * that reads as "nothing happened". One shape per observer is the only shape that can be filled.
+   *
+   * The collector builds it rather than this method, so the resolved configuration never has to
+   * leave the one object that owns it. Returns `undefined` when summaries are off, and is
+   * idempotent: an existing summary is kept, not restarted.
+   */
+  enableSummary() {
+    return this.summary ??= this.observer.callSummaryCollector?.createSummary(this.callId);
+  }
   /**
    * Remove a detector from **this call** by name, returning how many were removed.
    *
@@ -4302,12 +4315,13 @@ var ObservedCall = class extends EventEmitter3 {
   /**
    * Raise a call-level (server-side) finding; surfaced on the Observer bus as `call-issue`.
    *
-   * `payload` takes an **object** — it is delivered to in-process handlers, so there is nothing to
-   * serialise for. Pass a string only if you already have one.
+   * `payload` is an **object** and holds evidence only — it is delivered to an in-process handler,
+   * so there is nothing to serialise for. `scope` is stamped here, and the `callId` is already on
+   * the event, so neither belongs in the payload. Put the interpretation in `conclusion`.
    */
   addIssue(issue) {
     if (this.closed) return;
-    this._notify("call-issue", { ...this.eventScope, issue });
+    this._notify("call-issue", { ...this.eventScope, issue: { ...issue, scope: "call" } });
   }
   close() {
     if (this.closed) return;
@@ -4328,6 +4342,10 @@ var ObservedCall = class extends EventEmitter3 {
     if (this.startedAt === void 0) this.startedAt = minSampleTimestamps;
     if (this.endedAt === void 0) this.endedAt = maxSampleTimestamps;
     this.closedAt = Date.now();
+    if (this.summary) {
+      this.observer.callSummaryCollector?.finalise(this);
+      this._notify("call-summary", { ...this.eventScope, summary: this.summary });
+    }
     this.detectors.clear();
     this.activeIssuesRegistry.clear();
     this.emit("close");
@@ -4337,7 +4355,7 @@ var ObservedCall = class extends EventEmitter3 {
     if (this.closed || !this.observedClients.has(clientId)) return;
     return this.observedClients.get(clientId);
   }
-  createObservedClient(settings) {
+  createObservedClient(settings, acceptCtx) {
     if (this.closed) {
       logger4.warn("Attempted to create a client (clientId: %s) on a closed call %s", settings.clientId, this.callId);
       return void 0;
@@ -4346,15 +4364,18 @@ var ObservedCall = class extends EventEmitter3 {
       logger4.warn("Client with id %s already exists in call %s; returning the existing instance", settings.clientId, this.callId);
       return this.observedClients.get(settings.clientId);
     }
-    if (!settings.closeClientIfIdleForMs) {
-      settings.closeClientIfIdleForMs = this.observer.config.closeClientIfIdleForMs;
-    }
-    if (settings.appData === void 0) {
-      settings.appData = this.observer.config.createClientAppData?.({ clientId: settings.clientId, observedCall: this });
-    }
+    const clientSettings = {
+      ...settings,
+      closeClientIfIdleForMs: settings.closeClientIfIdleForMs || this.observer.config.closeClientIfIdleForMs,
+      appData: settings.appData ?? this.observer.config.createClientAppData?.({
+        clientId: settings.clientId,
+        observedCall: this,
+        acceptCtx
+      })
+    };
     const observedClientIssueRegistry = new ObservedClientIssueRegistry(this.activeIssuesRegistry);
     const result = new ObservedClient(
-      settings,
+      clientSettings,
       this,
       observedClientIssueRegistry
     );
@@ -4401,8 +4422,8 @@ var ObservedCall = class extends EventEmitter3 {
     }
     return result;
   }
-  getOrCreateObservedClient(settings) {
-    return this.getObservedClient(settings.clientId) ?? this.createObservedClient(settings);
+  getOrCreateObservedClient(settings, acceptCtx) {
+    return this.getObservedClient(settings.clientId) ?? this.createObservedClient(settings, acceptCtx);
   }
   update(context) {
     if (this.closed) return;
@@ -5088,6 +5109,166 @@ var ActiveIssuesRegistry = class {
   }
 };
 
+// src/summaries/CallSummary.ts
+var defaultCallSummaryConfig = {
+  include: [],
+  maxIssues: 500,
+  maxClientIds: 1e4
+};
+function createCallSummary(callId, config) {
+  const summary = { callId, attachments: {} };
+  if (config.include.includes("clients")) {
+    summary.clients = { clientIds: [], peak: 0, joined: 0, left: 0 };
+  }
+  if (config.include.includes("issues")) {
+    summary.issues = [];
+  }
+  if (config.include.includes("turnServers")) {
+    summary.turnServers = { serverUrls: [], clientsRelayed: 0 };
+  }
+  if (config.include.includes("scores")) {
+    summary.scores = { samples: 0 };
+  }
+  return summary;
+}
+
+// src/summaries/CallSummaryCollector.ts
+var logger8 = createLogger("CallSummaryCollector");
+var CallSummaryCollector = class {
+  constructor(_observer, _config) {
+    this._observer = _observer;
+    this._config = _config;
+    this._subscribeBuiltIns();
+    this._subscribeEnrichers();
+  }
+  _observer;
+  _config;
+  _scratch = /* @__PURE__ */ new WeakMap();
+  _listeners = [];
+  _closed = false;
+  /**
+   * Build a summary for `callId` and start tracking it.
+   *
+   * Creating it here, rather than letting the call create one and hand it over, keeps the resolved
+   * configuration inside the single object that owns it — and makes it impossible to end up with a
+   * summary whose sections nobody subscribed to fill.
+   */
+  createSummary(callId) {
+    const summary = createCallSummary(callId, this._config);
+    this._scratch.set(summary, { scores: [], turnClientIds: /* @__PURE__ */ new Set() });
+    return summary;
+  }
+  /**
+   * Finalise `call`'s summary: fold in what only makes sense once, and stamp the closing times.
+   *
+   * Percentiles are computed here rather than on every update — a median recomputed per tick over a
+   * growing array is quadratic work to produce a number nobody reads until the end.
+   */
+  finalise(call) {
+    const summary = call.summary;
+    if (!summary) return;
+    const scratch = this._scratch.get(summary);
+    summary.startedAt = call.startedAt;
+    summary.endedAt = call.endedAt;
+    summary.durationInMs = summary.startedAt !== void 0 && summary.endedAt !== void 0 ? Math.max(0, summary.endedAt - summary.startedAt) : void 0;
+    summary.closedAt = Date.now();
+    if (summary.scores && scratch) {
+      summary.scores.samples = scratch.scores.length;
+      if (0 < scratch.scores.length) {
+        summary.scores.min = Math.min(...scratch.scores);
+        summary.scores.max = Math.max(...scratch.scores);
+        summary.scores.median = percentile(scratch.scores, 0.5);
+      }
+    }
+    if (summary.turnServers && scratch) {
+      summary.turnServers.clientsRelayed = scratch.turnClientIds.size;
+    }
+  }
+  /** Drop every bus subscription. Called when the observer closes. */
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    for (const { event, listener } of this._listeners) {
+      this._observer.off(event, listener);
+    }
+    this._listeners.length = 0;
+  }
+  /**
+   * Subscribe `listener` to `event`, routed to the summary of the call the event names.
+   *
+   * The `observedCall` is read off the payload rather than closed over, which is what lets one
+   * subscription serve every call.
+   */
+  _on(event, handler) {
+    const listener = (...args) => {
+      const summary = args[0].observedCall.summary;
+      if (!summary) return;
+      const scratch = this._scratch.get(summary);
+      if (!scratch) return;
+      try {
+        handler(summary, scratch, ...args);
+      } catch (err) {
+        logger8.warn("A call-summary handler for %s threw; continuing. %o", event, err);
+      }
+    };
+    this._observer.on(event, listener);
+    this._listeners.push({ event, listener });
+  }
+  _subscribeBuiltIns() {
+    const include = this._config.include;
+    if (include.includes("clients")) {
+      this._on("client-added", (summary, _scratch, { observedCall, observedClient }) => {
+        const clients = summary.clients;
+        if (!clients) return;
+        clients.joined += 1;
+        clients.peak = Math.max(clients.peak, observedCall.observedClients.size);
+        if (clients.clientIds.length < this._config.maxClientIds) {
+          clients.clientIds.push(observedClient.clientId);
+        } else {
+          summary.truncated = { ...summary.truncated, clientIds: (summary.truncated?.clientIds ?? 0) + 1 };
+        }
+      });
+      this._on("client-closed", (summary) => {
+        if (summary.clients) summary.clients.left += 1;
+      });
+    }
+    if (include.includes("issues")) {
+      this._on("call-issue", (summary, _scratch, { issue }) => {
+        const issues = summary.issues;
+        if (!issues) return;
+        if (issues.length < this._config.maxIssues) issues.push(issue);
+        else summary.truncated = { ...summary.truncated, issues: (summary.truncated?.issues ?? 0) + 1 };
+      });
+    }
+    if (include.includes("scores") || include.includes("turnServers")) {
+      this._on("call-updated", (summary, scratch, { observedCall }) => {
+        if (summary.scores && observedCall.score !== void 0) scratch.scores.push(observedCall.score);
+        if (!summary.turnServers) return;
+        for (const clientId of observedCall.clientsUsedTurn) scratch.turnClientIds.add(clientId);
+        for (const client of observedCall.observedClients.values()) {
+          for (const peerConnection of client.observedPeerConnections.values()) {
+            for (const pair of peerConnection.selectedIceCandiadtePairForTurn) {
+              const url = pair.getLocalCandidate()?.url;
+              if (url && !summary.turnServers.serverUrls.includes(url)) {
+                summary.turnServers.serverUrls.push(url);
+              }
+            }
+          }
+        }
+      });
+    }
+  }
+  _subscribeEnrichers() {
+    const enrich = this._config.enrich;
+    if (!enrich) return;
+    for (const name of Object.keys(enrich)) {
+      const enricher = enrich[name];
+      if (!enricher) continue;
+      this._on(name, (summary, _scratch, ...args) => enricher(summary, ...args));
+    }
+  }
+};
+
 // src/detectors/SfuCongestionDetector.ts
 var SfuCongestionDetector = class _SfuCongestionDetector {
   constructor(_observer, config = {}) {
@@ -5216,13 +5397,10 @@ var SfuCongestionDetector = class _SfuCongestionDetector {
       absoluteIncrease: evaluation.absoluteIncrease,
       relativeIncrease: evaluation.relativeIncrease
     };
-    this._observer.emit("observer-issue", {
-      issue: {
-        type: this._config.emittedObserverIssueType,
-        timestamp: Date.now(),
-        payload
-      },
-      observer: this._observer
+    this._observer.addIssue({
+      type: this._config.emittedObserverIssueType,
+      timestamp: Date.now(),
+      payload: { ...payload }
     });
   }
   /**
@@ -5336,11 +5514,9 @@ var ObserverConcurrentIssueDetector = class _ObserverConcurrentIssueDetector {
       this._observer.addIssue({
         type: issueType,
         timestamp: now,
+        conclusion,
         payload: {
-          type: issueType,
           issueType: type,
-          scope: "observer",
-          conclusion,
           clients: group.totalClients,
           affectedClients: group.clientIds.length,
           affectedRatio: group.affectedRatio,
@@ -5513,16 +5689,13 @@ var ClientPopulationIssueDetector = class _ClientPopulationIssueDetector {
         this._observer.addIssue({
           type: ClientPopulationIssueTypes.clientPopulationIssue,
           timestamp: now,
-          payload: {
-            type: ClientPopulationIssueTypes.clientPopulationIssue,
-            ...rollup,
-            conclusion: {
-              faultDomain: "client-population",
-              summary: `'${issueType}' is ${this._riskText(rollup.relativeRisk)} more likely on ${population} than on the rest of the fleet (${rollup.affectedClients}/${rollup.clients} vs ${rollup.controlAffectedClients}/${rollup.controlClients})`,
-              recommendation: "this is not an SFU symptom \u2014 look at what those clients share: a recent release, a browser version, or shared/virtualised hardware",
-              confidence: this._confidenceOf(rollup)
-            }
-          }
+          conclusion: {
+            faultDomain: "client-population",
+            summary: `'${issueType}' is ${this._riskText(rollup.relativeRisk)} more likely on ${population} than on the rest of the fleet (${rollup.affectedClients}/${rollup.clients} vs ${rollup.controlAffectedClients}/${rollup.controlClients})`,
+            recommendation: "this is not an SFU symptom \u2014 look at what those clients share: a recent release, a browser version, or shared/virtualised hardware",
+            confidence: this._confidenceOf(rollup)
+          },
+          payload: { ...rollup }
         });
       }
     }
@@ -5624,7 +5797,7 @@ var TurnServerHealthDetector = class _TurnServerHealthDetector {
       this._observer.addIssue({
         type: TurnServerHealthTypes.turnServerDegraded,
         timestamp: now,
-        payload: { type: TurnServerHealthTypes.turnServerDegraded, ...health, otherServers }
+        payload: { ...health, otherServers }
       });
     }
     for (const serverUrl of [...this._streaks.keys()]) {
@@ -5732,7 +5905,6 @@ var TurnServerOutageDetector = class _TurnServerOutageDetector {
         type: TurnServerOutageTypes.turnServerOutage,
         timestamp: now,
         payload: {
-          type: TurnServerOutageTypes.turnServerOutage,
           serverUrl,
           peakClients: peak,
           currentClients: live,
@@ -6006,17 +6178,13 @@ var SimulcastReceiverValidator = class _SimulcastReceiverValidator {
       this._observer.addIssue({
         type: LOWEST_COMMON_DENOMINATOR_ISSUE,
         timestamp: decidedAt,
-        payload: {
-          type: LOWEST_COMMON_DENOMINATOR_ISSUE,
-          checks: this._checks,
-          ...outcome.evidence,
-          conclusion: {
-            faultDomain: "infrastructure",
-            summary: "one bad receiver is dragging a publisher's bitrate down for everyone \u2014 the SFU is not selecting layers per consumer",
-            recommendation: "check that simulcast/SVC is enabled and layers are chosen per consumer, and that the SFU terminates receiver reports instead of forwarding them; this is a build/config property, not a transient",
-            confidence: 0.8
-          }
-        }
+        conclusion: {
+          faultDomain: "infrastructure",
+          summary: "one bad receiver is dragging a publisher's bitrate down for everyone \u2014 the SFU is not selecting layers per consumer",
+          recommendation: "check that simulcast/SVC is enabled and layers are chosen per consumer, and that the SFU terminates receiver reports instead of forwarding them; this is a build/config property, not a transient",
+          confidence: 0.8
+        },
+        payload: { checks: this._checks, ...outcome.evidence }
       });
     }
     this.onDone(this.report);
@@ -6119,17 +6287,13 @@ var RemoteTrackResolverValidator = class _RemoteTrackResolverValidator {
       this._observer.addIssue({
         type: UNRESOLVED_TRACK_LINKS_ISSUE,
         timestamp: decidedAt,
-        payload: {
-          type: UNRESOLVED_TRACK_LINKS_ISSUE,
-          checks: this._checks,
-          ...outcome.evidence,
-          conclusion: {
-            faultDomain: "infrastructure",
-            summary: "a RemoteTrackResolver is configured but has never linked a subscriber to a publisher",
-            recommendation: "check the id the resolver joins on (mediasoup producerId, or your own convention) \u2014 until it links, IssueFanOutDetector, TrackDeliveryMismatchDetector, UnconsumedTrackDetector and SimulcastReceiverValidator all silently do nothing",
-            confidence: 0.9
-          }
-        }
+        conclusion: {
+          faultDomain: "infrastructure",
+          summary: "a RemoteTrackResolver is configured but has never linked a subscriber to a publisher",
+          recommendation: "check the id the resolver joins on (mediasoup producerId, or your own convention) \u2014 until it links, IssueFanOutDetector, TrackDeliveryMismatchDetector, UnconsumedTrackDetector and SimulcastReceiverValidator all silently do nothing",
+          confidence: 0.9
+        },
+        payload: { checks: this._checks, ...outcome.evidence }
       });
     }
     this.onDone(this.report);
@@ -6240,17 +6404,16 @@ var CodecConsistencyValidator = class _CodecConsistencyValidator {
       this._observer.addIssue({
         type: CODEC_MISMATCH_ISSUE,
         timestamp: decidedAt,
+        conclusion: {
+          faultDomain: "infrastructure",
+          summary: outcome.verdict === "codec-split" ? "participants of one call are using different codecs \u2014 an SFU that forwards without transcoding cannot serve all of them" : "the deployment is consistently negotiating a codec other than the expected one",
+          recommendation: outcome.verdict === "codec-split" ? "check codec preferences and any SDP munging; a split usually means one endpoint could not negotiate the preferred codec and the others were not renegotiated with it" : "check codec preferences and endpoint support \u2014 a silent fallback keeps working, at a higher bitrate than you budgeted for",
+          confidence: 0.85
+        },
         payload: {
-          type: CODEC_MISMATCH_ISSUE,
           verdict: outcome.verdict,
           checks: this._checks,
-          evidence: outcome.evidence,
-          conclusion: {
-            faultDomain: "infrastructure",
-            summary: outcome.verdict === "codec-split" ? "participants of one call are using different codecs \u2014 an SFU that forwards without transcoding cannot serve all of them" : "the deployment is consistently negotiating a codec other than the expected one",
-            recommendation: outcome.verdict === "codec-split" ? "check codec preferences and any SDP munging; a split usually means one endpoint could not negotiate the preferred codec and the others were not renegotiated with it" : "check codec preferences and endpoint support \u2014 a silent fallback keeps working, at a higher bitrate than you budgeted for",
-            confidence: 0.85
-          }
+          evidence: outcome.evidence
         }
       });
     }
@@ -6264,7 +6427,7 @@ function mediaKindOf(mimeType) {
 }
 
 // src/Observer.ts
-var logger8 = createLogger("Observer");
+var logger9 = createLogger("Observer");
 var Observer = class extends EventEmitter6 {
   observedTURN = new ObservedTURN();
   observedCalls = /* @__PURE__ */ new Map();
@@ -6320,6 +6483,14 @@ var Observer = class extends EventEmitter6 {
    * ```
    */
   callDetectorConfigs = /* @__PURE__ */ new Map();
+  /**
+   * Owns every call's summary: the resolved `config.callSummary`, the bus subscriptions that keep
+   * the summaries current (one per event type, not one per call), and the summaries themselves.
+   *
+   * `undefined` when `config.callSummary` was absent or `null` — so its presence *is* the answer to
+   * "are summaries on", and nothing is subscribed to anything.
+   */
+  callSummaryCollector;
   constructor(config = {}) {
     super();
     this.setMaxListeners(Infinity);
@@ -6331,6 +6502,12 @@ var Observer = class extends EventEmitter6 {
       closeClientIfIdleForMs: 6e4,
       ...config
     };
+    if (this.config.callSummary) {
+      this.callSummaryCollector = new CallSummaryCollector(this, {
+        ...defaultCallSummaryConfig,
+        ...this.config.callSummary
+      });
+    }
   }
   get numberOfCalls() {
     return this.observedCalls.size;
@@ -6369,7 +6546,7 @@ var Observer = class extends EventEmitter6 {
         break;
       }
       default: {
-        logger8.warn("Unknown detector name %s; skipping", name);
+        logger9.warn("Unknown detector name %s; skipping", name);
         return this;
       }
     }
@@ -6454,7 +6631,7 @@ var Observer = class extends EventEmitter6 {
         break;
     }
     if (!validator) {
-      logger8.warn("Unknown validator name %s; skipping", name);
+      logger9.warn("Unknown validator name %s; skipping", name);
       return this;
     }
     this.validators.add(validator);
@@ -6485,7 +6662,7 @@ var Observer = class extends EventEmitter6 {
       try {
         validator.cancel(reason);
       } catch (err) {
-        logger8.warn("Error cancelling validator %s: %o", validator.name, err);
+        logger9.warn("Error cancelling validator %s: %o", validator.name, err);
       }
     }
     return matching.length;
@@ -6494,19 +6671,24 @@ var Observer = class extends EventEmitter6 {
     if (this.closed || !this.observedCalls.has(callId)) return;
     return this.observedCalls.get(callId);
   }
-  createObservedCall(settings) {
+  /**
+   * @param acceptCtx the `accept()` context, when this call is being created to receive a sample.
+   * Passed on to `ObserverConfig.createCallAppData`, so the factory can read whatever the caller (or
+   * an accept middleware) put there — a tenant, a region, a trace id.
+   */
+  createObservedCall(settings, acceptCtx) {
     if (this.closed) {
-      logger8.warn("Attempted to create a call (callId: %s) on a closed observer", settings.callId);
+      logger9.warn("Attempted to create a call (callId: %s) on a closed observer", settings.callId);
       return void 0;
     }
     if (this.observedCalls.has(settings.callId)) {
-      logger8.warn("Observed Call with id %s already exists; returning the existing instance", settings.callId);
+      logger9.warn("Observed Call with id %s already exists; returning the existing instance", settings.callId);
       return this.observedCalls.get(settings.callId);
     }
     const callSettings = {
       ...settings,
       closeCallIfEmptyForMs: settings.closeCallIfEmptyForMs ?? this.config.closeCallIfEmptyForMs,
-      appData: settings.appData ?? this.config.createCallAppData?.({ callId: settings.callId, observer: this })
+      appData: settings.appData ?? this.config.createCallAppData?.({ callId: settings.callId, observer: this, acceptCtx })
     };
     const callActiveIssuesRegistry = new ActiveIssuesRegistry(this.activeIssuesRegistry);
     const observedCall = new ObservedCall(
@@ -6515,6 +6697,7 @@ var Observer = class extends EventEmitter6 {
       callActiveIssuesRegistry
     );
     observedCall.remoteTrackResolver = this.config.createRemoteTrackResolver?.(observedCall);
+    observedCall.enableSummary();
     for (const [name, detectorConfig] of this.callDetectorConfigs) {
       observedCall.addDetector(name, detectorConfig);
     }
@@ -6532,16 +6715,16 @@ var Observer = class extends EventEmitter6 {
     this._notify("call-added", { ...this.eventScope, observedCall });
     return observedCall;
   }
-  getOrCreateObservedCall(settings) {
-    return this.getObservedCall(settings.callId) ?? this.createObservedCall(settings);
+  getOrCreateObservedCall(settings, acceptCtx) {
+    return this.getObservedCall(settings.callId) ?? this.createObservedCall(settings, acceptCtx);
   }
   createObservedMediasoupRouter(settings) {
     if (this.closed) {
-      logger8.warn("Attempted to create mediasoup router (id: %d) on a closed observer", settings.router.id);
+      logger9.warn("Attempted to create mediasoup router (id: %d) on a closed observer", settings.router.id);
       return void 0;
     }
     if (this.observedMediasoupRouters.has(settings.router.id)) {
-      logger8.warn("Observed Mediasoup Router (id %s) already exists; returning the existing instance", settings.router.id);
+      logger9.warn("Observed Mediasoup Router (id %s) already exists; returning the existing instance", settings.router.id);
       return this.observedMediasoupRouters.get(settings.router.id);
     }
     const observedMediasoupRouter = new ObservedMediasoupRouter(settings);
@@ -6572,13 +6755,14 @@ var Observer = class extends EventEmitter6 {
   }
   close() {
     if (this.closed) {
-      return logger8.debug("Attempted to close twice");
+      return logger9.debug("Attempted to close twice");
     }
     this.closed = true;
     for (const call of [...this.observedCalls.values()]) call.close();
     this.detectors.clear();
     for (const validator of [...this.validators]) validator.cancel("observer closed");
     this.validators.clear();
+    this.callSummaryCollector?.close();
     this.activeIssuesRegistry.clear();
     this._notify("observer-closed", { ...this.eventScope });
   }
@@ -6589,7 +6773,7 @@ var Observer = class extends EventEmitter6 {
     try {
       this.acceptMiddlewares.process({ sample, context });
     } catch (err) {
-      logger8.warn("An accept middleware threw; dropping the sample. %o", err);
+      logger9.warn("An accept middleware threw; dropping the sample. %o", err);
     }
     if (!sample.callId) {
       this._notify("sample-rejected", { ...this.eventScope, reason: "missing-callId", sample });
@@ -6599,21 +6783,9 @@ var Observer = class extends EventEmitter6 {
       this._notify("sample-rejected", { ...this.eventScope, reason: "missing-clientId", sample });
       return;
     }
-    let call = this.getObservedCall(sample.callId);
-    if (!call) {
-      call = this.createObservedCall({
-        callId: sample.callId,
-        appData: this.config.createCallAppData?.({ callId: sample.callId, observer: this })
-      });
-    }
+    const call = this.getOrCreateObservedCall({ callId: sample.callId }, context);
     if (!call) return;
-    let client = call.getObservedClient(sample.clientId);
-    if (!client) {
-      client = call.createObservedClient({
-        clientId: sample.clientId,
-        appData: this.config.createClientAppData?.({ clientId: sample.clientId, observedCall: call })
-      });
-    }
+    const client = call.getOrCreateObservedClient({ clientId: sample.clientId }, context);
     if (!client) return;
     client.accept(sample, context);
   }
@@ -6641,7 +6813,7 @@ var Observer = class extends EventEmitter6 {
       try {
         validator.update();
       } catch (err) {
-        logger8.warn("Error running validator %s: %o", validator.name, err);
+        logger9.warn("Error running validator %s: %o", validator.name, err);
       }
     }
     this._notify("observer-updated", { ...this.eventScope });
@@ -6654,7 +6826,7 @@ var Observer = class extends EventEmitter6 {
    */
   addIssue(issue) {
     if (this.closed) return;
-    this._notify("observer-issue", { ...this.eventScope, issue });
+    this._notify("observer-issue", { ...this.eventScope, issue: { ...issue, scope: "observer" } });
   }
   /** Emit an Observer-bus event. */
   _notify(type, ...args) {
@@ -6772,18 +6944,11 @@ var CallHealthAggregator = class {
   }
 };
 
-// src/common/ObserverIssue.ts
-function issuePayloadOf(issue) {
-  const payload = issue.payload;
-  if (payload === void 0) return void 0;
-  return typeof payload === "string" ? parseJsonObject(payload) : payload;
-}
+// src/common/Issue.ts
 function issuePayloadAsString(issue) {
-  const payload = issue.payload;
-  if (payload === void 0) return void 0;
-  if (typeof payload === "string") return payload;
+  if (issue.payload === void 0) return void 0;
   try {
-    return JSON.stringify(payload);
+    return JSON.stringify(issue.payload);
   } catch {
     return void 0;
   }
@@ -7077,6 +7242,7 @@ export {
   CallConcurrentIssueDetector,
   CallConcurrentIssueTypes,
   CallHealthAggregator,
+  CallSummaryCollector,
   ClientEventTypes,
   ClientMetaTypes,
   ClientPopulationIssueDetector,
@@ -7135,16 +7301,17 @@ export {
   concludeObserverIssue,
   correlation,
   counterDelta,
+  createCallSummary,
   createDefaultMediasoupRemoteTrackResolverFactory,
   createInMemorySink,
   createJsonlFileSink,
   createJsonlFileSinkFactory,
   createLogger,
   createP2pRemoteTrackResolverFactory,
+  defaultCallSummaryConfig,
   defaultClientHealthThresholds,
   isClientIssueResolutionEntry,
   issuePayloadAsString,
-  issuePayloadOf,
   mannKendall,
   mannKendallVerdict,
   median,