fix(tracing): flush root spans before shutdown cleanup to prevent orphan traces (#112)

Container restart (SIGTERM → timeout → SIGKILL) killed the process before
root spans were ended. Child spans already flushed to OTLP survived in Tempo
without their parent root span, creating orphan `?` traces.

Fix:
- Add flushRootSpans() to CdpSession — ends all tab + session root spans immediately
- Call flushAllRootSpans() as Step 0 in shutdown() BEFORE slow replay/browser cleanup
- Increase shutdown timeout from 10s to 25s (aligned with replay flush timeouts)
- SpanProto.end() pushes to OTLP exporter buffer — spans survive even if killed mid-cleanup

Author: DivMode

src/index.ts

@@ -25,7 +25,10 @@ const program = Effect.fn('browserless.main')(function* () {
   const shutdown = (_reason: string, code: number) =>
     Effect.runPromise(
       Effect.tryPromise(() => browserless.stop()).pipe(
-        Effect.timeout('10 seconds'),
+        // 25s — enough for session cleanup (replay flush + browser close) + OTLP export.
+        // Docker stop_timeout must be > this (set to 30s in infra config).
+        // Previous 10s timeout killed the process during replay flush, losing root spans.
+        Effect.timeout('25 seconds'),
         Effect.catch(() => Effect.void),
       ),
     ).finally(() => process.exit(code));

src/session/cdp-session.ts

@@ -151,6 +151,26 @@ export class CdpSession {
     return this.targets.size;
   }
 
+  /**
+   * End all root spans immediately — called during graceful shutdown BEFORE
+   * slow cleanup (replay flush, browser.close). Pushes spans to the OTLP
+   * exporter buffer so they survive even if the process is killed mid-cleanup.
+   *
+   * SpanProto.end() pushes to the server exporter via export(). Tempo
+   * deduplicates by spanId, so the safety-net end() calls in ensuring/
+   * destroyEffect are no-ops in practice (same spanId, already ingested).
+   */
+  flushRootSpans(): void {
+    const now = BigInt(Date.now()) * 1_000_000n;
+    for (const [, tab] of this.tabs) {
+      tab.span.end(now, Exit.void);
+    }
+    if (this.sessionSpan) {
+      this.sessionSpan.end(now, Exit.void);
+      this.sessionSpan = null;
+    }
+  }
+
   // ─── Layer Construction ───────────────────────────────────────────────
 
   /**

src/session/session-coordinator.ts

@@ -36,6 +36,17 @@ export class SessionCoordinator {
     videoMgr?.setVideoEncoder(this.videoEncoder);
   }
 
+  /**
+   * End all root spans across all active CdpSessions immediately.
+   * Called during graceful shutdown BEFORE slow cleanup so spans reach
+   * the OTLP exporter buffer before the process is killed.
+   */
+  flushAllRootSpans(): void {
+    for (const [, cdpSession] of this.cdpSessions) {
+      cdpSession.flushRootSpans();
+    }
+  }
+
   /**
    * Check if replay is enabled (always true — replay uses external server).
    */

src/session/session-lifecycle-manager.ts

@@ -393,6 +393,13 @@ export class SessionLifecycleManager {
   async shutdown(): Promise<void> {
     this.log.info('Closing down browser sessions');
 
+    // Step 0: Flush all root spans IMMEDIATELY — before any slow cleanup.
+    // This pushes session + tab root spans to the OTLP exporter buffer so
+    // they survive even if the process is killed during replay/browser cleanup.
+    // Without this, container restart (SIGTERM → timeout → SIGKILL) loses
+    // in-memory root spans, creating orphan `?` traces in Tempo.
+    this.sessionCoordinator?.flushAllRootSpans();
+
     // Stop watchdog
     if (this.watchdogFiber) {
       await Effect.runPromise(Fiber.interrupt(this.watchdogFiber));